כדי להצהיר על הרשאות ספציפיות ל-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 לשמירה על הפרטיות.
- מוסיפים מאגר של Maven לפרויקט.
- מצהירים על תלות של ספריית Jetpack של ads-adservices בקובץ
build.gradle
של האפליקציה או המודול. - שימוש בממשקי API מחבילות
androidx.privacysandbox.ads.adservices.*
. - ספריית 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
.