تنفيذ Topics API على Android

bookmark_border تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

ضبط إعدادات الجهاز

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

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

/Internet & Telecom/Text & Instant Messaging

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

الاختبار

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

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

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

تفاصيل التشفير

مع إدخال التشفير، ستؤدي المكالمات إلى GetTopics() الآن إلى إنشاء استجابة تتضمّن قائمة بعناصر EncryptedTopic. سيؤدي فك تشفير هذه النتائج إلى إنشاء عنصر بتنسيق JSON نفسه المستخدَم في عنصر Topic السابق.

تتيح Topics API تنفيذ HPKE (التشفير باستخدام مفتاح عمومي مختلط) لمرة واحدة. نتوقع أن يستضيف المتصل المسجَّل مفتاحًا عامًا 32 بت على نقطة نهاية عنوان URL للتشفير العلني التي تم تقديمها أثناء التسجيل. من المفترض أن تكون هذه المفاتيح مشفّرة بترميز Base64.

يحتوي عنصر EncryptedTopic على 3 حقول. يمكن الحصول على قائمة المواضيع المعروضة باستخدام المفتاح الخاص المقابل للمفتاح العام.

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

القيود

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

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

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

الخطوات التالية

انظر أيضًا

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

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