تنفيذ Topics API على Android

الإعداد

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

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

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

التحكّم والشفافية

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

نظرة عامة على Topics على Android

فهم آلية عمل Topics على Android والتعرّف على الخطوات الأساسية لمسار واجهة برمجة التطبيقات

انظر أيضًا

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

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