กำหนดค่า AdServices สำหรับ Android

ทำตามวิธีการด้านล่างเพื่อประกาศสิทธิ์สำหรับ API โดยเฉพาะและกำหนดค่า สิทธิ์ของ SDK ในการเข้าถึงทรัพยากรที่จัดการโดย API เป้าหมาย

ประกาศสิทธิ์เฉพาะ AdServices API

การเข้าถึง PPAPI แต่ละรายการต้องมีสิทธิ์ normal สำหรับบริการโฆษณา ใน ให้ประกาศสิทธิ์การเข้าถึงที่เหมาะสมซึ่งสอดคล้องกับ API ที่จำเป็นในแอปหรือ SDK

Attribution Reporting API

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_ATTRIBUTION" />

Attribution Reporting API (พร้อมรายงานการแก้ไขข้อบกพร่อง)

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_ATTRIBUTION" />
<uses-permission android:name="android.permission.ACCESS_ADSERVICES_AD_ID" />

Protected Audience / Custom Audience API

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />

Topics API

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_TOPICS" />

หากต้องการรับรายงานการแก้ไขข้อบกพร่องด้วยการรายงานการระบุแหล่งที่มา (ไม่บังคับ) API โปรดรวมสิทธิ์ AD_ID ต่อไปนี้

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_AD_ID" />

หากโปรเจ็กต์ของคุณมีทรัพยากร Dependency ในโมดูลหรือ SDK โปรเจ็กต์เหล่านั้นอาจประกาศแล้ว สิทธิ์ที่จำเป็นของบริการโฆษณาในไฟล์ Manifest โดยค่าเริ่มต้น แอตทริบิวต์ บิลด์ Gradle จะรวมไฟล์ Manifest ทั้งหมดไว้ในไฟล์ Manifest เดียวที่ ลงในแอปของคุณ ใช้มุมมองไฟล์ Manifest ที่ผสานรวมเพื่อยืนยันว่าพารามิเตอร์ ที่ใช้สิทธิ์ที่ถูกต้อง

หากต้องการป้องกันไม่ให้สิทธิ์ใดๆ รวมอยู่ในแอปของคุณ ผ่านทรัพยากร Dependency เช่น SDK ให้รวมเครื่องหมายโหนด remove สำหรับ สิทธิ์เฉพาะได้ ตัวอย่างต่อไปนี้แสดงวิธีการป้องกัน การผสานสิทธิ์ Topics

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_TOPICS"
    tools:node="remove" />

กำหนดค่าบริการโฆษณาเฉพาะ API

API แต่ละรายการจะมีข้อมูลที่เกี่ยวข้องใน การกำหนดค่าบริการโฆษณา การกําหนดค่านี้จะช่วยให้คุณ ควบคุมการเข้าถึงทรัพยากรที่จัดการโดย API ในแอปของคุณแบบละเอียด หรือ SDK แบบฝัง

ในไฟล์ Manifest ให้ระบุพร็อพเพอร์ตี้ adservicesConfig ตามที่แสดง ใน ตัวอย่าง:

<application ...>
      ...
    <property android:name="android.adservices.AD_SERVICES_CONFIG"
        android:resource="@xml/ad_services_config" />

      ...
</application>

ระบุทรัพยากร XML ของบริการโฆษณาที่อ้างอิงในไฟล์ Manifest เช่น res/xml/ad_services_config.xml สำหรับ API การรักษาความเป็นส่วนตัวแต่ละรายการที่เกี่ยวข้องกับ แอป (หรือ SDK แบบฝัง) ให้ตั้งค่าแอตทริบิวต์ allowAllToAccess เป็น true เป็น มอบสิทธิ์เข้าถึงให้ผู้โทร

หรือคุณจะใช้แอตทริบิวต์ allowAdPartnersToAccess เพื่อให้สิทธิ์ก็ได้ การเข้าถึง API แบบละเอียดสำหรับเทคโนโลยีโฆษณาแต่ละรายการ คุณจะต้องระบุรายการ รหัสบัญชีการลงทะเบียนนักพัฒนาซอฟต์แวร์ซึ่งได้รับจากการลงทะเบียน หาก แอตทริบิวต์ allowAllToAccess ได้รับการตั้งค่าเป็น true โดยแอตทริบิวต์นี้จะมีลําดับความสําคัญเหนือกว่า รหัสบัญชีการลงทะเบียนที่ระบุใน allowAdPartnersToAccess

แพลตฟอร์มเทคโนโลยีโฆษณาควรตรวจสอบว่าไคลเอ็นต์แอปของตนให้สิทธิ์อย่างเหมาะสม สิทธิ์เข้าถึง API การรักษาความเป็นส่วนตัวที่จำเป็นในการกำหนดค่าบริการโฆษณา

ตัวอย่างต่อไปนี้แสดงวิธีระบุการเข้าถึงแบบกว้างเพื่ออนุญาตให้ลงทะเบียนได้ สิทธิ์เข้าถึงรหัสบัญชีไปยัง API ที่รักษาความเป็นส่วนตัวทั้งหมด

<ad-services-config>
   <!-- Attribution API -->
   <attribution allowAllToAccess="true" />

   <!-- Topics API -->
   <topics allowAllToAccess="true" />

   <!-- Protected Audience on Android API -->
   <custom-audiences allowAllToAccess="true" />
</ad-services-config>

ตัวอย่างต่อไปนี้แสดงวิธีระบุสิทธิ์เข้าถึงแบบละเอียดสำหรับแต่ละรายการ API การรักษาความเป็นส่วนตัวสำหรับรหัสบัญชีการลงทะเบียนเฉพาะ:

<ad-services-config>
    <!-- Attribution API -->
    <attribution allowAdPartnersToAccess="ENROLLMENT-ID" allowAllToAccess="false" />

    <!-- Topics API -->
    <includes-sdk-library name="ENROLLMENT-ID" />
    <topics allowAdPartnersToAccess="ENROLLMENT-ID" allowAllToAccess="false" />

    <!-- Protected Audience on Android API -->
    <custom-audiences allowAdPartnersToAccess="ENROLLMENT-ID" allowAllToAccess="false" />
</ad-services-config>

ประกาศทรัพยากร Dependency ของไลบรารี Jetpack

ใช้ไลบรารี Jetpack เวอร์ชัน 1.0.0-beta01 ขึ้นไป ads-adservices เพื่อผสานรวม ด้วย API การรักษาความเป็นส่วนตัวของ Privacy Sandbox คุณใช้ไลบรารีนี้เพื่อ สรุปแอปของคุณจากรายละเอียดระดับแพลตฟอร์มและลดความซับซ้อนในการผสานรวมกับแอป API การรักษาความเป็นส่วนตัว

  1. เพิ่มที่เก็บ Maven ลงในโปรเจ็กต์
  2. ประกาศ ads-adservices ทรัพยากร Dependency ของไลบรารี Jetpack ใน build.gradle สำหรับแอปหรือโมดูล
  3. ใช้ API จากแพ็กเกจ androidx.privacysandbox.ads.adservices.*
  4. ไลบรารี ads-adservices Jetpack มีโครูทีน Kotlin ในตัว การสนับสนุน คุณอาจต้องติดตั้งใช้งาน Lifecycle-Aware ที่เหมาะสม ทรัพยากร Dependency ที่เหมาะกับโปรเจ็กต์เพื่อจัดการขอบเขตของ Coroutine

ตรวจสอบความพร้อมใช้งานของเวอร์ชันส่วนขยายบริการโฆษณา

หากคุณใช้ไลบรารี Jetpack สำหรับบริการโฆษณาเพื่อผสานรวมกับ API ที่รักษาความเป็นส่วนตัว ไลบรารีจะตรวจสอบความพร้อมใช้งานของ API ที่ขอในฟังก์ชัน obtain() ฟังก์ชันจะแสดงผลค่า Null หากฟังก์ชัน API ที่ขอไม่พร้อมใช้งานในอุปกรณ์ ตัวอย่างต่อไปนี้แสดงให้เห็นถึง วิธีเริ่มต้น TopicsManager สำหรับ Topics API ทำงานคล้ายกับ เข้าถึง API การรักษาความเป็นส่วนตัวอื่นๆ

Kotlin 

import androidx.privacysandbox.ads.adservices.topics.TopicsManager

// The initialization function will return null if the requested
// functionality is not available on the device.
val topicsManager = TopicsManager.obtain(context)

Java 

import androidx.privacysandbox.ads.adservices.topics.TopicsManager;

// The initialization function will return null if the requested
// functionality is not available on the device.
TopicsManager topicsManager = TopicsManager.obtain(context);

หากคุณใช้ AdServices API ใน SDK ส่วนขยายโดยตรง ให้ตรวจสอบ เวอร์ชัน AdServices Extensions ที่มี AdServices API ที่คุณต้องการใช้ ในการอ้างอิง API คุณสามารถระบุเวอร์ชันที่ AdServices หนึ่งๆ มีการนำ API มาใช้ ตัวอย่างเช่น ข้อมูลอ้างอิง API สำหรับคลาส TopicsManager ระบุว่ามีการ "เพิ่มในส่วนขยายบริการโฆษณา 4" ใช้รายการต่อไปนี้ การตรวจสอบแบบมีเงื่อนไขเพื่อตรวจสอบส่วนขยาย SDK ที่มี AdServices API

Kotlin 

import android.os.ext.SdkExtensions

if (SDK_INT >= Build.VERSION_CODES.R && // The extensions API is available since R.
   SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4) {

    // AdServices API is available.
...
}

Java 

import android.os.ext.SdkExtensions;

if (SDK_INT >= Build.VERSION_CODES.R && // The extensions API is available since R.
   SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4) {

    // AdServices API is available.
...
}

การจํากัดการเข้าถึงเมื่ออยู่เบื้องหน้า

เพื่อแสดงความโปร่งใส การเข้าถึงรันไทม์ของ SDK และ API การรักษาความเป็นส่วนตัว จำกัดเฉพาะแอปที่มีกิจกรรมที่มองเห็นได้ หรือ RunningAppProcessInfo จาก IMPORTANCE_FOREGROUND