הגדרת 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" />

אופציונלי: כדי לקבל דוחות ניפוי באגים באמצעות Attribution Reporting API, צריך לכלול את ההרשאה AD_ID:

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

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

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

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

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

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

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

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

אם אתם משתמשים בספריית 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 ב-Extension SDK, צריך לבדוק את הגרסה של AdServices extensions שכוללת את ממשקי AdServices API שבהם אתם רוצים להשתמש. בהפניה ל-API תוכלו לציין את הגרסה שבה מוטמע ממשק API מסוים של AdServices. לדוגמה, הפניית ה-API למחלקה TopicsManager מציינת שהיא "נוספה ב-תוספים למודעות 4". השתמשו בבדיקות המותנות הבאות כדי לאמת תוספי SDK שמכילים ממשקי API של AdServices.

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.
...
}

מגבלת גישה בחזית

כדי להתנהל בשקיפות, הגישה לממשקי ה-API של זמן הריצה ושל השמירה על הפרטיות ב-SDK מוגבלת לאפליקציות עם פעילות גלויה, או עם RunningAppProcessInfo מתוך IMPORTANCE_FOREGROUND.