הטמעת Topics API ב-Android

הגדרה

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

  1. כדאי להשתמש ב-Android Privacy Sandbox SDK העדכני ביותר כדי לקבל את הגרסה העדכנית ביותר של ממשקי ה-API לשמירה על פרטיות.

  2. מוסיפים את הקטע הבא למניפסט:

    • הרשאה: צריך לכלול את ההרשאה ACCESS_ADSERVICES_TOPICS כדי לאפשר לאפליקציה לגשת ל-Topics API:

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

    • הגדרות של Ad Services: הפניה לקובץ הגדרות של Ad Services ברכיב <application> במניפסט.

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

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

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

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

    adb shell setprop debug.adservices.disable_topics_enrollment_check true

  4. מפעילים את הגישה ל-Topics API. כברירת מחדל, Topics API מושבת. צריך להפעיל אותו באמצעות פקודות ADB:

    adb shell device_config put adservices ppapi_app_signature_allow_list \"\*\"
    adb shell setprop debug.adservices.disable_topics_enrollment_check true

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

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

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

פרטי ההצפנה

בעקבות ההצפנה, קריאות ל-GetTopics() ייצרו עכשיו תגובה עם רשימה של אובייקטים מסוג EncryptedTopic. פענוח התוצאות האלה יניב אובייקט באותו פורמט JSON של האובייקט הקודם Topic.

Topics API תומך בהטמעה חד-פעמית של HPKE (הצפנה היברידית של מפתח ציבורי). אנחנו מצפים שהגורם שמבצע את הקריאה יהיה מארח מפתח ציבורי של 32 ביט בנקודת הקצה של כתובת ה-URL להצפנה הציבורית שסופקה במהלך ההרשמה. המפתחות האלה אמורים להיות בקידוד Base64.

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

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

מגבלות

בנתוני הגרסה תוכלו למצוא רשימה של יכולות שאנחנו עובדים עליהן ב-Topics API.

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

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

השלבים הבאים

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

ראה גם

כדאי לעיין במקורות המידע שלנו כדי להבין טוב יותר את Topics API ב-Android.