دليل مطوِّري Topics API

معاينة المطوِّر إصدار تجريبي

أثناء الاطّلاع على مستندات "مبادرة حماية الخصوصية" على Android، استخدِم الزر معاينة المطوّر أو الزر إصدار تجريبي لاختيار إصدار البرنامج الذي تعمل معه، لأنّ التعليمات قد تختلف.

---

تقديم ملاحظات

تستنتج Topics API إشارات اهتمام عامة من الجهاز فقط بالاستناد إلى بيانات استخدام التطبيق. يُطلَق على هذه الإشارات اسم المواضيع، وتتم مشاركتها مع المعلِنين لدعم الإعلانات التي تستهدف الاهتمامات بدون تتبُّع مستخدمين فرديين على مختلف التطبيقات. اطّلِع على مزيد من المعلومات عن Topics API في اقتراح التصميم. ملاحظة مهمّة: يُرجى النقر على زر "إصدار إضافات حِزم تطوير البرامج (SDK)" أو زر "معاينة المطوِّر" لاختيار إصدار البرنامج الذي يناسبك، لأنّه قد تختلف التعليمات.

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

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

بالإضافة إلى ذلك، عليك تفعيل إمكانية الوصول إلى Topics API (غير المفعَّلة تلقائيًا) باستخدام أوامر adb هذه.

adb shell device_config put adservices ppapi_app_signature_allow_list \"*\"

adb shell setprop debug.adservices.disable_topics_enrollment_check true

تكمن الوظيفة الأساسية لـ 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);

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

/Internet & Telecom/Text & Instant Messaging

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

الاختبار

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

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

القيود

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

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

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