أثناء الاطّلاع على مستندات "مبادرة حماية الخصوصية" على 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.
محتوى مُقترَح لك
- ملاحظة: يتم عرض نص الرابط عند إيقاف JavaScript.
- Protected Audience API على دليل مطوّري برامج Android
- ملاحظات الإصدار
- ضبط إعدادات AdServices {}{/restrict-adservices}