הגדרת AdServices ל-Android

יש לפעול לפי ההוראות הבאות כדי להצהיר על הרשאות ספציפיות ל-API ולהגדיר את הגישה של ה-SDK למשאבים שמנוהלים על ידי ה-API המטורגט.

הערה: ספריית Jetpack חדשה מאפשרת שילוב עם ממשקי ה-API לשמירה על הפרטיות של ארגז החול לפרטיות (Topics, Protected Audience ו-Attribution Reporting. אפשר להשתמש בספרייה הזו כתחליף לממשקי API של ארגז החול לפרטיות שמסופקים ב-SDK של התוספים.

הצהרה על הרשאות ספציפיות ל-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 API / 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" />

אם הפרויקט תלוי במודולים או בערכות SDK, יכול להיות שהם כבר מצהירים על ההרשאות הנדרשות של שירותי המודעות בקובצי המניפסט. כברירת מחדל, גרסת ה-Gradle ממזגת את כל קובצי המניפסט לקובץ מניפסט יחיד שארוז בתוך האפליקציה שלכם. כדאי להשתמש בתצוגה מניפסט ממוזג כדי לוודא שנעשה שימוש בהרשאות הנכונות.

כדי למנוע מיזוג של הרשאות באפליקציה באמצעות יחסי תלות כמו SDK, צריך לכלול את סמן הצומת remove להרשאות הספציפיות. הדוגמה הבאה ממחישה איך למנוע מיזוג של ההרשאות של Topics.

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

הגדרת שירותי מודעות ספציפיים ל-API

בדומה להרשאות הגישה ל-PPAPI, לכל API יש רשומה תואמת בהגדרה של שירותי המודעות. ההגדרות האלה מאפשרות לכם לשלוט בגישה פרטנית למשאבים שמנוהלים על ידי ממשקי ה-API באפליקציה או ב-SDK המוטמע. במניפסט, מציינים את המאפיין adservicesConfig כפי שמוצג בדוגמה הבאה:

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

      ...
</application>

צריך לציין את משאב ה-XML של שירותי המודעות שיש אליו הפניה במניפסט, למשל res/xml/ad_services_config.xml. בכל API לשמירה על פרטיות שרלוונטי לאפליקציה שלך (או ל-SDK מוטמע), צריך להגדיר את המאפיין allowAllToAccess כ-true כדי להעניק גישה לקריאות.

לחלופין, אפשר להשתמש במאפיין allowAdPartnersToAccess כדי להעניק גישת API פרטנית לכל טכנולוגיות פרסום, וצריך לספק רשימה של מזהים של חשבונות מפתחים שהושגו דרך ההרשמה. אם המאפיין allowAllToAccess מוגדר לערך true, המאפיין הזה מקבל קדימות על פני כל מזהה של חשבון רישום שמצוינים במאפיין allowAdPartnersToAccess.

הערה: כדי לגשת לממשקי ה-API של ארגז החול לפרטיות בגרסה העדכנית ביותר של תוסף ה-SDK של AdServices ובגרסת התצוגה המקדימה למפתחים, צריך להשלים את תהליך ההרשמה.

בנוסף, הפלטפורמות של הפרסום הדיגיטלי צריכות לוודא שלקוחות האפליקציות שלהן מעניקים גישה לממשקי ה-API הנדרשים לשמירה על הפרטיות בהגדרה של שירותי הפרסום.

הערה: עקב באג ידוע, צריך להגדיר את allowAllToAccess לערך true כשמבצעים בדיקה באופן מקומי.

הדוגמה הבאה מראה איך לציין גישה רחבה כדי לאפשר לכל מזהה של חשבון הרשמה גישה לכל ממשקי ה-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>

הערה: אם ההרשמה ל-Topics API או ל-Protected Audience API מושבתת באמצעות פקודות adb, האפליקציה יכולה לגשת לממשקי ה-API הקשורים ללא קשר לבקרות הגישה שצוינו ב-ad-services-config.

הצהרה על יחסי תלות של ספריית Jetpack

כדאי להשתמש בספריית Jetpack של ads-adservices בגרסה 1.0.0-בטא01 ואילך כדי לשלב עם ממשקי ה-API לשמירה על הפרטיות של ארגז החול לפרטיות. תוכלו להשתמש בספרייה הזו כדי לפשט את האפליקציה מפרטים ברמת הפלטפורמה ולפשט את השילוב עם ממשקי API ששומרים על הפרטיות.

1. מוסיפים מאגר Maven לפרויקט.
2. צריך להצהיר על יחסי תלות של ספריית Jetpack ads-adservices בקובץ build.gradle של האפליקציה או המודול.
3. שימוש בממשקי API מחבילות androidx.privacysandbox.ads.adservices.*.
4. ספריית Jetpack הכוללת מודעות פרסום מספקת תמיכה מובנית בקוראים קוראוטיים ב-Kotlin. כדי לנהל את היקפי התרחישים, יכול להיות שתצטרכו לשלב תלויי מחזור חיים שמתאימים לפרויקט שלכם.

בדיקת הזמינות של הגרסה של 'תוספים לשירותי מודעות'

אם אתם משתמשים בספריית Jetpack של שירותי מודעות כדי לשלב עם ממשקי API לשמירה על הפרטיות, הספרייה תבדוק אם ממשקי ה-API המבוקשים בפונקציה obtain(). אם ה-API המבוקש לא זמין במכשיר, הפונקציה מחזירה את הערך null. הדוגמה הבאה ממחישה איך לאתחל את 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.