הגדרת AdServices ל-Android

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

הערה: יש ספריית Jetpack חדשה שמאפשרת שילוב עם פרטיות ממשקי ה-API לשמירה על הפרטיות של Sandbox (Topics, Protected Audience ו- דוחות שיוך (Attribution). אפשר להשתמש בספרייה הזו ככניסה תחליף לממשקי ה-API של ארגז החול לפרטיות שצוינו ב-Extension 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 / 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) API, יש לכלול את ההרשאה AD_ID:

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

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

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

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

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

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

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

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

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

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

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