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

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

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

การเข้าถึง PPAPI แต่ละรายการต้องมีสิทธิ์ normal สำหรับบริการโฆษณา ในไฟล์ Manifest ให้ประกาศสิทธิ์การเข้าถึงที่เหมาะสมซึ่งสอดคล้องกับ 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" />

API หัวข้อ:

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

(ไม่บังคับ) หากต้องการรับรายงานการแก้ไขข้อบกพร่องด้วย Attribution Reporting 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

เช่นเดียวกับสิทธิ์การเข้าถึง PPAPI แต่ละ 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 ads-adservices เวอร์ชัน 1.0.0-beta01 ขึ้นไปเพื่อผสานรวมกับ API การรักษาความเป็นส่วนตัวของ Privacy Sandbox คุณใช้ไลบรารีนี้เพื่อ แยกแอปออกจากรายละเอียดระดับแพลตฟอร์ม และลดความซับซ้อนในการผสานรวมกับ API การรักษาความเป็นส่วนตัว

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

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

หากคุณใช้ไลบรารี Jetpack ของ Google Ads เพื่อผสานรวมกับ 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 เท่านั้น