דף זה תורגם על ידי Cloud Translation API.

המדריך למפתחים של Topics API

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

שליחת משוב

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

הגדרה

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

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

להפנות להגדרה של שירותי פרסום ברכיב <application> של מניפסט:

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

מציינים את משאב ה-XML של שירותי הפרסום שיש אליו הפניה במניפסט, למשל res/xml/ad_services_config.xml אפשר להשתמש במאפיין allowAllToAccess כדי הענקת גישה לכל ערכות ה-SDK, או המאפיין allowSdksToAccess כדי להעניק גישה לערכות SDK נפרדות. מידע נוסף על הרשאות לשירותי מודעות וגישה ל-SDK הפרמטר הזה.

<ad-services-config>
    <topics allowAllToAccess="true" />
</ad-services-config>

בנוסף, צריך להפעיל גישה ל-Topics API (מושבת על ידי ברירת מחדל) עם פקודות adb האלה.

adb shell device_config put adservices ppapi_app_signature_allow_list \"\*\"

adb shell setprop debug.adservices.disable_topics_enrollment_check true

הפונקציונליות העיקרית של Topics API נמצאת getTopics() בתוך האובייקט TopicsManager, כפי שמוצג בדוגמה הבאה דוגמה:

Kotlin

fun getTopics(
        getTopicsRequest: GetTopicsRequest,
        executor: Executor,
        callback: OutcomeReceiver<GetTopicsResponse, Exception>
    ) { }

Java

public void getTopics (@NonNull GetTopicsRequest getTopicsRequest,
    @NonNull Executor executor,
    @NonNull OutcomeReceiver<GetTopicsResponse, Exception> callback)

כדי להשתמש בשיטה הזו, מאתחלים את האובייקט TopicsManager ואת הפרמטרים שנדרשים לקבלת נתוני נושאים. נדרשים מידע לגבי GetTopicsRequest כרטיסים כדי לאחזר נתונים של Topics API, כולל דגל שמציין אם מבצע הקריאה החוזרת (caller) לשמש כצופה או לא. כשלא משמשים כצופים, הקריאה getTopics מחזירה נושא מהתקופה הקודמת, אבל להשפיע על נתוני הנושאים הבאים. הקריאה החוזרת (callback) של OutcomeReceiver מטפל בתוצאה באופן אסינכרוני. לדוגמה:

Kotlin

private fun topicGetter() {
    val mContext = baseContext
    val mTopicsManager = mContext.getSystemService(TopicsManager::class.java)
    val mExecutor: Executor = Executors.newCachedThreadPool()
    val shouldRecordObservation = false
    val mTopicsRequestBuilder: GetTopicsRequest.Builder = GetTopicsRequest.Builder()
    mTopicsRequestBuilder.setAdsSdkName(baseContext.packageName)
    mTopicsRequestBuilder.setShouldRecordObservation(shouldRecordObservation)
    mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor,
        mCallback as OutcomeReceiver<GetTopicsResponse, Exception>)
}
private var mCallback: OutcomeReceiver<GetTopicsResponse, java.lang.Exception> =
object : OutcomeReceiver<GetTopicsResponse, java.lang.Exception> {
    override fun onResult(result: GetTopicsResponse) {
        // handle successful result
        val topicsResult = result.topics
        for (i in topicsResult.indices) {
            Log.i("Topic", topicsResult[i].getTopicId().toString())
        }
        if (topicsResult.size == 0) {
            Log.i("Topic", "Returned Empty")
        }
    }
    override fun onError(error: java.lang.Exception) {
        // handle error
        Log.i("Topic", "Error, did not return successfully")
    }
}

Java

public void TopicGetter() {
    @NonNull Context mContext = getBaseContext();
    TopicsManager mTopicsManager = mContext.getSystemService(TopicsManager.class);
    Executor mExecutor = Executors.newCachedThreadPool();
    boolean shouldRecordObservation = false;
    GetTopicsRequest.Builder mTopicsRequestBuilder = new GetTopicsRequest.Builder();
    mTopicsRequestBuilder.setAdsSdkName(getBaseContext().getPackageName());
    mTopicsRequestBuilder.setShouldRecordObservation(shouldRecordObservation);
    mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor, mCallback);
}
OutcomeReceiver mCallback = new OutcomeReceiver<GetTopicsResponse, Exception>() {
    @Override
    public void onResult(@NonNull GetTopicsResponse result) {
        //Handle Successful Result
        List<Topic> topicsResult = result.getTopics();
        for (int i = 0; i < topicsResult.size(); i++) {
            Log.i("Topic", topicsResult.get(i).getTopicId().toString());
        }
        if (topicsResult.size() == 0) {
            Log.i("Topic", "Returned Empty");
        }
    }
    @Override
    public void onError(@NonNull Exception error) {
        // Handle error
        Log.i("Topic", "Experienced an error, and did not return successfully");
    }
};

בקשה לקבוצת נושאים

כשתהליך ההגדרה יהיה מוכן, אפשר להתקשר ולקבל GetTopicsResponse כתוצאה מהשיטה getTopics():

Kotlin

mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor,
        mCallback as OutcomeReceiver<GetTopicsResponse, java.lang.Exception>)

Java

mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor, mCallback);

ההפעלה שלמעלה תספק רשימה של אובייקטים של Topics שמכילים ערכי מזהים שתואמים לנושאים בטקסונומיית הקוד הפתוח שרלוונטיים או שגיאה רלוונטית. הנושאים יהיו דומים לדוגמה הבאה:

/Internet & Telecom/Text & Instant Messaging

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

בדיקה

Topics API מספק נושאים רלוונטיים ועדכניים על סמך השימוש באפליקציה. מוקדם מספקת תצוגה מקדימה של התנהגות ה-API, ונשפר את האיכות בנושאים שונים בגרסאות עתידיות. כדי ליהנות מהחוויה המלאה, מומלץ ליצור סביבת בדיקה עם אפליקציות שבהן השתמשת באפשרות getTopics() כדי לראות איך הנושאים נבחרים. ה-SDK מאגר ממשקי ה-API של זמן ריצה ופרטיות ב-GitHub מכיל קבוצה של פרויקטים נפרדים ב-Android Studio שיעזרו לך להתחיל, כולל דוגמאות שמדגימים איך לאתחל את Topics API ולקרוא לו.

חישוב הנושאים מתבצע בסוף 'תקופה'. כברירת מחדל, כל תקופה של זמן מערכת היא 7 ימים, אבל אפשר לשנות את מרווח הזמן הזה כדי לקבל תוצאה. הזה פקודת המעטפת של Android Debug Bridge מקצרת את משך התקופה ל-5 דקות:

adb shell device_config put adservices topics_epoch_job_period_ms 300000

אפשר לאשר את הערך של topics_epoch_job_period_ms באמצעות get:

adb shell device_config get adservices topics_epoch_job_period_ms

כדי להפעיל באופן ידני חישוב של תקופה של זמן מערכת, מריצים את הפקודה הבאה:

adb shell cmd jobscheduler run -f com.google.android.adservices.api 2

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

מגבלות

רשימת היכולות בתהליך פיתוח של Topics API מופיעה במאמר נתוני גרסה.

דיווח על באגים ובעיות

המשוב שלכם הוא חלק חיוני בארגז החול לפרטיות ב-Android. חשוב לנו לדעת בכל בעיה שמצאתם או רעיונות לשיפור ארגז החול לפרטיות ב-Android.

מומלץ עבורך

הערה: טקסט הקישור מוצג כאשר JavaScript מושבת
Protected Audience API במדריך למפתחים של Android
נתוני גרסה
הגדרת AdServices {:#Configure-adservices}