הטמעת Topics API ב-Android

bookmark_border קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

הגדרה

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

1. כדי לקבל את הגרסה העדכנית ביותר, צריך להשתמש ב-SDK העדכני של ארגז החול לפרטיות ב-Android של ממשקי ה-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 של שירותי הפרסום שיש אליו הפניה במניפסט, למשל 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. כדי להתחיל את ההטמעה, צריך ליצור פורק (fork) של הגרסה של האפליקציה לדוגמה ב-Java או ב-Kotlin כדי להכיר את האופן שבו אפשר לאחזר נושאים במכשיר.

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

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

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

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

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

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")
    }
}

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():

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

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 יש 3 שדות. אפשר לקבל את רשימת הנושאים שהוחזרו באמצעות המפתח הפרטי התואם למפתח הציבורי.

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

מגבלות

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

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

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

השלבים הבאים

ראה גם

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

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