تنفيذ 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 لـ "خدمات Google الإعلانية" المُشار إليه في البيان، مثل 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 ، كما هو موضّح في هذا المثال:

Kotlin 

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

Java 

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

لاستخدام هذه الطريقة، عليك إعداد عنصر TopicsManager والمَعلمات اللازمة لتلقّي بيانات المواضيع. تُرسِل GetTopicsRequest المعلومات المطلوبة لاسترداد بيانات Topics API، بما في ذلك علامة للإشارة إلى ما إذا كان المُتصل سيتصرّف كمُراقب أم لا. عندما لا تكون في دور مراقب، يعرض طلب getTopics موضوعًا من الحقبة السابقة، ولكنّه لن يؤثّر في بيانات المواضيع الخاصة بالفترة التالية. يعالج الإجراء المُعاد الاتصال به OutcomeReceiver النتيجة بشكل غير متزامن. على سبيل المثال:

Kotlin 

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

Java 

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

Kotlin 

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

Java 

mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor, mCallback);

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

/Internet & Telecom/Text & Instant Messaging

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

الاختبار

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

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

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

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

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

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

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

القيود

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

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

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

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

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

انظر أيضًا

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