الحصول على معرّف إعلاني يمكن للمستخدم إعادة ضبطه جزء من Android Jetpack.
لحماية خصوصية المستخدم، من أفضل الممارسات أن تعمل جميع تطبيقات Android باستخدام معرّفات يمكن للمستخدم إعادة ضبطها. ومن بين هذه المعرّفات المعرّف الإعلاني الذي يحدِّد هوية مستخدم معيّن بشكل فريد لحالات الاستخدام الإعلانية، مثل تخصيص الإعلانات.
لدعم حل موحّد لتتبع الإعلانات عبر الأجهزة التي تشغل يمكنك استخدام مكتبة المعرِّف الإعلاني. هذه المكتبة المتاحة على الأجهزة التي تعمل بنظام التشغيل Android 4.0 (المستوى 14 من واجهة برمجة التطبيقات) والمستويات الأعلى، تحدد واجهة للتفاعل مع موفّري الإعلانات على مستوى النظام. تسمح هذه الواجهة لتطبيقك بتلقّي قيم متسقة للمعرِّف الإعلاني.
يحدِّد مزوّد الإعلانات المضمّن في مكتبة Advertising ID أيضًا نية عادية لفتح شاشة إعدادات ينفّذها مزوّد الإعلانات. تسمح شاشة الإعدادات هذه للمستخدم بإعادة ضبط المعرِّف الإعلاني وإيقاف تلك الميزة. عن تخصيص الإعلانات
يوضِّح هذا الدليل كيفية استخدام وحدة العميل في مكتبة المعرِّف الإعلاني. للحصول على معرِّف إعلاني متسق على أساس كل جهاز على حدة يقدّم هذا الدليل بعد ذلك نظرة عامة على بنية المكتبة.
ضبط تطبيق العميل
ومن خلال التفاعل مع وحدة العميل في مكتبة المعرِّف الإعلاني، يستخدم تطبيقك استرداد معرِّف إعلاني متسق يمثل المستخدم الذي التفاعل مع التطبيق.
يتم تمثيل المعرِّف الإعلاني باستخدام الإصدار 3 من تنسيق المعرِّف الفريد على مستوى العالم (UUID) أو تنسيق مكافئ 128 بت:
38400000-8cf0-11bd-b23e-10b96e40000d
تضبط مكتبة المعرِّف الإعلاني القيمة المعروضة حسب الضرورة لتقديم المعرفات التي تستخدم هذا التنسيق.
لاسترداد المعرّف الإعلاني الذي يمكن للمستخدم إعادة ضبطه لتطبيقك، أكمِل الخطوات التالية:
التحقّق ممّا إذا كان أحد مقدّمي الإعلانات متاحًا من خلال الاتصال
AdvertisingIdClient.isAdvertisingIdProviderAvailable()
إذا كانت هذه الطريقة تعرضfalse
، يجب أن يستخدم تطبيقك وسيلة أخرى لتنفيذ أي حالات استخدام مطلوبة تتعلّق بالتتبّع الإعلاني.يمكنك الحصول على تفاصيل معرِّف الإعلان، بما في ذلك المعرِّف الإعلاني، من خلال طلب
AdvertisingIdClient.getAdvertisingIdInfo()
مكتبة المعرِّف الإعلاني تنفذ هذه الطريقة على مؤشر ترابط العامل وتستخدم مهلة اتصال مدتها 10 ثوانٍ.
توضِّح المقتطف التالي من الرمز كيفية استرداد المعرّف الإعلاني بالإضافة إلى معلومات أخرى من موفّر الإعلانات:
app/build.gradle
رائع
dependencies { implementation 'androidx.ads:ads-identifier:1.0.0-alpha01' // Used for the calls to addCallback() in the snippets on this page. implementation 'com.google.guava:guava:28.0-android' }
Kotlin
dependencies { implementation("androidx.ads:ads-identifier:1.0.0-alpha01") // Used for the calls to addCallback() in the snippets on this page. implementation("com.google.guava:guava:28.0-android") }
MyAdIdClient
Kotlin
// Used for the call to addCallback() within this snippet. import com.google.common.util.concurrent.Futures.addCallback private fun determineAdvertisingInfo() { if (AdvertisingIdClient.isAdvertisingIdProviderAvailable()) { val advertisingIdInfoListenableFuture = AdvertisingIdClient.getAdvertisingIdInfo(applicationContext) addCallback(advertisingIdInfoListenableFuture, object : FutureCallback<AdvertisingIdInfo> { override fun onSuccess(adInfo: AdvertisingIdInfo?) { val id: String = adInfo?.id val providerPackageName: String = adInfo?.providerPackageName val isLimitTrackingEnabled: Boolean = adInfo?.isLimitTrackingEnabled } // Any exceptions thrown by getAdvertisingIdInfo() // cause this method to be called. override fun onFailure(t: Throwable) { Log.e("MY_APP_TAG", "Failed to connect to Advertising ID provider.") // Try to connect to the Advertising ID provider again or fall // back to an ad solution that doesn't require using the // Advertising ID library. } }, Executors.newSingleThreadExecutor()) } else { // The Advertising ID client library is unavailable. Use a different // library to perform any required ad use cases. } }
Java
// Used for the call to addCallback() within this snippet. import com.google.common.util.concurrent.Futures; private void determineAdvertisingInfo() { if (AdvertisingIdClient.isAdvertisingIdProviderAvailable()) { ListenableFuture<AdvertisingIdInfo> advertisingIdInfoListenableFuture = AdvertisingIdClient.getAdvertisingIdInfo(getApplicationContext()); Futures.addCallback(advertisingIdInfoListenableFuture, new FutureCallback<AdvertisingIdInfo>() { @Override public void onSuccess(AdvertisingIdInfo adInfo) { String id = adInfo.getId(); String providerPackageName = adInfo.getProviderPackageName(); boolean isLimitTrackingEnabled = adInfo.isLimitTrackingEnabled(); // Any exceptions thrown by getAdvertisingIdInfo() // cause this method to be called. @Override public void onFailure(Throwable throwable) { Log.e("MY_APP_TAG", "Failed to connect to Advertising ID provider."); // Try to connect to the Advertising ID provider again // or fall back to an ad solution that doesn't require // using the Advertising ID library. } }); } else { // The Advertising ID client library is unavailable. Use a different // library to perform any required ad use cases. } }
بنية مكتبة المعرّف الإعلاني
يوضّح الشكل 1 بنية مكتبة المعرّف الإعلاني. تتكوّن المكتبة من الوحدات التالية:
- وحدة العميل، وهي طبقة رفيعة مضمّنة في التطبيقات.
- وحدة مقدّم الخدمة التي يوفّرها المصنّع يجب أن تحدِّد عمليات تنفيذ هذه الوحدة واجهة مستخدم للإعدادات لمنح المستخدمين إمكانية إعادة ضبط معرّفهم الإعلاني وتبديل الإعدادات المفضّلة لتتبُّع الإعلانات.
تتواصل وحدة العميل مع وحدة الموفِّر لاسترداد المعرّفات الإعلانية والإعدادات المفضّلة للمستخدم بشأن تتبُّع الإعلانات.
كيفية تعامل المكتبة مع عدة مقدّمين
من الممكن أن يتوافق جهاز مع العديد من موفّري الإعلانات على مستوى النظام في صفحة في نفس الوقت. إذا رصدت مكتبة "معرّف الإعلان" هذا الموقف، تضمن أن يُسترجع تطبيقك المعلومات دائمًا من الموفّر نفسه، بافتراض أنّه سيظلّ موفّرًا. تؤدي هذه العملية إلى الحفاظ على اتساق المعرِّف الإعلاني.
إذا تغيّرت مجموعة مزوّدي الإعلانات المتاحين بمرور الوقت وتفاعل تطبيقك مع مزوّد معرّف إعلانات مختلف، ستبدأ جميع تطبيقات العميل الأخرى في استخدام هذا المزوّد الجديد أيضًا. يعرض تطبيقك السلوك نفسه الذي سيحدث إذا طلب المستخدم إعادة ضبط معرّفه الإعلاني.
تستخدِم مكتبة مزوّدي المعرّف الإعلاني الترتيب الحتمي التالي لترتيب المزوّدين:
- مقدّمو الخدمات الذين طلبوا
إذن
androidx.ads.identifier.provider.HIGH_PRIORITY
. - مقدّمو الخدمات الذين تم تثبيتهم على الجهاز منذ فترة طويلة
- مقدّمو الخدمة الذين يظهرون أولاً بترتيب أبجدي