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

תצוגה מקדימה למפתחים בטא

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

---

שליחת משוב

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

הגדרה

עליכם להשתמש בגרסה העדכנית ביותר של Android Privacy Sandbox SDK כדי לקבל את הגרסה העדכנית ביותר של ממשקי ה-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 נמצאת ב-method 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 תחזיר נושא מהתקופה הקודמת, אבל לא תשפיע על נתוני הנושאים בתקופה הבאה. הפונקציה 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 כתוצאה מ-method 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.