กำหนดค่า 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" />

Topics 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

API แต่ละรายการจะมีรายการที่เกี่ยวข้องในการกำหนดค่าบริการโฆษณา เช่นเดียวกับสิทธิ์การเข้าถึง PPAPI การกำหนดค่านี้ช่วยให้คุณควบคุมการเข้าถึงทรัพยากรที่จัดการโดย 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. ประกาศทรัพยากร Dependency ของไลบรารี Jetpack ของ ads-adservices ในไฟล์ build.gradle สําหรับแอปหรือโมดูล
  3. ใช้ API จากแพ็กเกจ androidx.privacysandbox.ads.adservices.*
  4. ไลบรารี ads-adservices Jetpack รองรับโครูทีน Kotlin ในตัว คุณอาจต้องรวมทรัพยากร Dependency ตามวงจรที่เหมาะสมสำหรับโปรเจ็กต์ของคุณเพื่อจัดการขอบเขตโครูทีน

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

หากคุณใช้ไลบรารี 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 ที่มี 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 เท่านั้น