הטמעת Topics API ב-Android

הגדרה

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

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

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

   • הרשאה: צריך לכלול את ההרשאה ACCESS_ADSERVICES_TOPICS כדי לאפשר לאפליקציה לגשת אל 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 נפרדות. מידע נוסף על הרשאות של Ad Services ובקרת גישה ל-SDK

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

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

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

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

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

ראה גם

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

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