تنفيذ Topics API على Android

الإعداد

لتنفيذ Topics API، عليك أولاً إعداد بيئة التطوير من خلال اتّباع خطوات الإعداد التالية:

1. استخدِم أحدث إصدار من حزمة تطوير البرامج (SDK) الخاصة بـ "مبادرة حماية الخصوصية" على Android للحصول على أحدث إصدار من واجهات برمجة التطبيقات التي تحافظ على الخصوصية.

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 فردية. مزيد من المعلومات حول أذونات "خدمات الإعلانات" وعناصر التحكّم في الوصول إلى حزمة تطوير البرامج (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، كما هو موضّح في المثال التالي:

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);

سيوفّر هذا الاستدعاء قائمة بكائنات "المواضيع" التي تحتوي على قيم معرّفات تتطابق مع المواضيع في التصنيف المفتوح المصدر ذات الصلة بالمستخدم، أو سيعرض خطأ ذا صلة. ستكون المواضيع مشابهة للمثال التالي:

/Internet & Telecom/Text & Instant Messaging

راجِع التصنيف للاطّلاع على قائمة بالمواضيع المحتملة التي يمكن عرضها. هذا التصنيف مفتوح المصدر ويمكن إرسال التغييرات المقترَحة باستخدام زر الملاحظات في أعلى هذه الصفحة.

الاختبار

توفّر Topics API مواضيع ذات صلة وحديثة استنادًا إلى استخدام التطبيقات. تقدّم هذه النسخة المبكرة معاينة لسلوكيات واجهة برمجة التطبيقات، وسنعمل على تحسين جودة المواضيع في الإصدارات المستقبلية.

للحصول على أفضل تجربة، ننصحك باستخدام بيئة اختبار تتضمّن تطبيقات متعدّدة يمكنك فيها الاتصال بالرقم getTopics() لمعرفة كيفية اختيار المواضيع. يحتوي مستودع SDK Runtime وواجهات برمجة التطبيقات التي تحافظ على الخصوصية على GitHub على مجموعة من مشاريع "استوديو Android" الفردية لمساعدتك في البدء، بما في ذلك عيّنات توضّح كيفية إعداد واجهة 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 من خلال إيقاف فحص التسجيل. سيؤدي ذلك إلى فرض استخدام المفتاح العام التجريبي في واجهة برمجة التطبيقات لتشفير الردود. يمكنك فك تشفير المواضيع المشفّرة باستخدام المفتاح الخاص المناسب.

القيود

للاطّلاع على قائمة بالقدرات التي يتم العمل عليها حاليًا في Topics API، يُرجى الرجوع إلى ملاحظات الإصدار.

الإبلاغ عن الأخطاء والمشاكل

تُعدّ ملاحظاتك جزءًا مهمًا من "مبادرة حماية الخصوصية" على Android. يُرجى إعلامنا بأي مشاكل تواجهك أو أفكار لديك لتحسين "مبادرة حماية الخصوصية" على Android.

Next steps

Control & transparency

Learn how users and developers can manage and customize the Topics API to suit user's preferences and needs.

Topics on Android overview

Understand how Topics works on Android and lear about the core steps of the API flow.

انظر أيضًا

يمكنك الاطّلاع على مراجعنا لفهم Topics API على Android بشكل أفضل.

• يمكنك الاطّلاع على نماذج تطبيقات ومحتوى تعاون وجولة تفصيلية حول Topics.
• تعرَّف على كيفية تمكُّن المستخدمين والمطوّرين من التحكُّم في واجهة برمجة التطبيقات.
• يمكنك الاطّلاع على مراجع الدعم لطرح الأسئلة والتفاعل مع المستخدمين ومشاركة الملاحظات.