تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
الحصول على معرّف إعلاني يمكن للمستخدم إعادة ضبطه جزء من
Android Jetpack.
لحماية خصوصية المستخدم، من أفضل الممارسات أن تعمل جميع تطبيقات Android باستخدام
معرّفات يمكن للمستخدم إعادة ضبطها. ومن بين هذه المعرّفات المعرّف الإعلاني الذي يحدِّد هوية مستخدم معيّن بشكل فريد لحالات الاستخدام الإعلانية، مثل تخصيص الإعلانات.
لدعم حل موحّد لتتبع الإعلانات عبر الأجهزة التي تشغل
يمكنك استخدام مكتبة المعرِّف الإعلاني.
هذه المكتبة المتاحة على الأجهزة التي تعمل بنظام التشغيل Android 4.0 (المستوى 14 من واجهة برمجة التطبيقات)
والمستويات الأعلى، تحدد واجهة للتفاعل مع موفّري الإعلانات على مستوى النظام.
تسمح هذه الواجهة لتطبيقك بتلقّي قيم متسقة للمعرِّف الإعلاني.
يحدِّد مزوّد الإعلانات المضمّن في مكتبة Advertising ID أيضًا
نية عادية لفتح شاشة إعدادات ينفّذها مزوّد الإعلانات.
تسمح شاشة الإعدادات هذه للمستخدم بإعادة ضبط المعرِّف الإعلاني وإيقاف تلك الميزة.
عن تخصيص الإعلانات
يوضِّح هذا الدليل كيفية استخدام وحدة العميل في مكتبة المعرِّف الإعلاني.
للحصول على معرِّف إعلاني متسق على أساس كل جهاز على حدة يقدّم هذا الدليل
بعد ذلك نظرة عامة على بنية المكتبة.
ضبط تطبيق العميل
ومن خلال التفاعل مع وحدة العميل في مكتبة المعرِّف الإعلاني، يستخدم تطبيقك
استرداد معرِّف إعلاني متسق يمثل المستخدم الذي
التفاعل مع التطبيق.
تضبط مكتبة المعرِّف الإعلاني القيمة المعروضة حسب الضرورة لتقديم
المعرفات التي تستخدم هذا التنسيق.
لاسترداد المعرّف الإعلاني الذي يمكن للمستخدم إعادة ضبطه لتطبيقك، أكمِل الخطوات التالية:
التحقّق ممّا إذا كان أحد مقدّمي الإعلانات متاحًا من خلال الاتصال
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.importcom.google.common.util.concurrent.Futures.addCallbackprivatefundetermineAdvertisingInfo(){if(AdvertisingIdClient.isAdvertisingIdProviderAvailable()){valadvertisingIdInfoListenableFuture=AdvertisingIdClient.getAdvertisingIdInfo(applicationContext)addCallback(advertisingIdInfoListenableFuture,object:FutureCallback<AdvertisingIdInfo>{overridefunonSuccess(adInfo:AdvertisingIdInfo?){valid:String=adInfo?.idvalproviderPackageName:String=adInfo?.providerPackageNamevalisLimitTrackingEnabled:Boolean=adInfo?.isLimitTrackingEnabled}// Any exceptions thrown by getAdvertisingIdInfo()// cause this method to be called.overridefunonFailure(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.importcom.google.common.util.concurrent.Futures;privatevoiddetermineAdvertisingInfo(){if(AdvertisingIdClient.isAdvertisingIdProviderAvailable()){ListenableFuture<AdvertisingIdInfo>advertisingIdInfoListenableFuture=AdvertisingIdClient.getAdvertisingIdInfo(getApplicationContext());Futures.addCallback(advertisingIdInfoListenableFuture,newFutureCallback<AdvertisingIdInfo>(){@OverridepublicvoidonSuccess(AdvertisingIdInfoadInfo){Stringid=adInfo.getId();StringproviderPackageName=adInfo.getProviderPackageName();booleanisLimitTrackingEnabled=adInfo.isLimitTrackingEnabled();// Any exceptions thrown by getAdvertisingIdInfo()// cause this method to be called.@OverridepublicvoidonFailure(Throwablethrowable){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. بنية مكتبة المعرِّف الإعلاني
يوضّح الشكل 1 بنية مكتبة المعرّف الإعلاني.
تتكوّن المكتبة من الوحدات التالية:
وحدة العميل، وهي طبقة رفيعة مضمّنة في التطبيقات.
وحدة مقدّم الخدمة التي يوفّرها المصنّع
يجب أن تحدِّد عمليات تنفيذ هذه الوحدة واجهة مستخدم للإعدادات لمنح المستخدمين
إمكانية إعادة ضبط معرّفهم الإعلاني وتبديل الإعدادات المفضّلة لتتبُّع الإعلانات.
تتواصل وحدة العميل مع وحدة الموفِّر لاسترداد المعرّفات
الإعلانية والإعدادات المفضّلة للمستخدم بشأن تتبُّع الإعلانات.
كيفية تعامل المكتبة مع عدة مقدّمين
من الممكن أن يتوافق جهاز مع العديد من موفّري الإعلانات على مستوى النظام في صفحة
في نفس الوقت. إذا رصدت مكتبة "معرّف الإعلان" هذا الموقف، تضمن أن يُسترجع
تطبيقك المعلومات دائمًا من الموفّر نفسه، بافتراض أنّه
سيظلّ موفّرًا. تؤدي هذه العملية إلى الحفاظ على اتساق المعرِّف الإعلاني.
إذا تغيّرت مجموعة مزوّدي الإعلانات المتاحين بمرور الوقت وتفاعل تطبيقك
مع مزوّد معرّف إعلانات مختلف، ستبدأ جميع تطبيقات العميل الأخرى في
استخدام هذا المزوّد الجديد أيضًا. يعرض تطبيقك السلوك نفسه الذي
سيحدث إذا طلب المستخدم إعادة ضبط معرّفه الإعلاني.
تستخدِم مكتبة مزوّدي المعرّف الإعلاني الترتيب الحتمي التالي لترتيب المزوّدين:
مقدّمو الخدمات الذين طلبوا
إذن androidx.ads.identifier.provider.HIGH_PRIORITY.
مقدّمو الخدمات الذين تم تثبيتهم على الجهاز منذ فترة طويلة
مقدّمو الخدمة الذين يظهرون أولاً بترتيب أبجدي
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["Get a user-resettable advertising ID Part of [Android Jetpack](/jetpack).\n=========================================================================\n\n| **Note:** If you plan to publish and distribute your app using Google Play, use the [ads identifier\n| library](https://developers.google.com/android/reference/com/google/android/gms/ads/identifier/AdvertisingIdClient) that's available as part of Google Play services instead of this library.\n\nTo protect user privacy, it's a best practice for all Android apps to work with\nuser-resettable identifiers. One such identifier is an *advertising ID*, which\nuniquely identifies a particular user for advertising use cases, such as ad\npersonalization.\n\nTo support a standardized ad-tracking solution across the devices running your\napp, you can use the [Advertising ID library](/jetpack/androidx/releases/ads).\nThis library, which is available on devices running Android 4.0 (API level 14)\nand higher, defines an interface to interact with system-level ad providers.\nThis interface allows your app to receive consistent advertising ID values.\n\nThe ad provider that's included with the Advertising ID library also defines a\nstandard intent for opening a settings screen that the ad provider implements.\nThis settings screen allows the user to reset their advertising ID and opt out\nof ad personalization.\n\nThis guide explains how to use the client module of the Advertising ID library\nto obtain a consistent advertising ID on a per-device-user basis. This guide\nthen presents an overview of the library's architecture.\n\nConfigure your client app\n-------------------------\n\nBy interacting with the client module of the Advertising ID library, your app\ncan retrieve a consistent advertising ID that represents the user who is\ninteracting with the app.\n\nThe advertising ID is represented using version 3 of the [universally unique\nidentifier (UUID)\nformat](https://www.rfc-editor.org/rfc/rfc4122.txt) or an\nequivalent 128-bit format: \n\n```\n38400000-8cf0-11bd-b23e-10b96e40000d\n```\n\nThe Advertising ID library normalizes the return value as necessary to provide\nIDs using this format.\n| **Note:** Most ad providers make sure that the advertising ID is unique *per device\n| user*. On Android devices that support multiple users, including guest users, it's possible for your app to obtain different advertising IDs on the same device. These different IDs correspond to different users who could be signed in on that device.\n\nTo retrieve the user-resettable advertising ID for your app, complete the\nfollowing steps:\n\n1. Check whether an ad provider is available by calling\n [`AdvertisingIdClient.isAdvertisingIdProviderAvailable()`](/reference/androidx/ads/identifier/AdvertisingIdClient#isAdvertisingIdProviderAvailable(android.content.Context)).\n If this method returns\n `false`, your app should use another means to perform any required ad-tracking\n use cases.\n\n | **Caution:** Even if this method returns `true`, your app should be able to handle any exceptions that could occur when attempting to retrieve the advertising ID.\n2. Get the ad identifier details, including the advertising ID, by calling\n [`AdvertisingIdClient.getAdvertisingIdInfo()`](/reference/androidx/ads/identifier/AdvertisingIdClient#getAdvertisingIdInfo(android.content.Context)). The Advertising ID library\n executes this method on a worker thread and uses a 10-second connection timeout.\n\n | **Note:** Because the user can reset their advertising ID after your app starts, you should call `AdvertisingIdClient.getAdvertisingIdInfo()` each time your app needs to check the value of the ID. Don't cache the value.\n\nThe following code snippet demonstrates how to retrieve the advertising ID\nalong with other information from the ad provider:\n\napp/build.gradle \n\n### Groovy\n\n```groovy\ndependencies {\n implementation 'androidx.ads:ads-identifier:1.0.0-alpha01'\n\n // Used for the calls to addCallback() in the snippets on this page.\n implementation 'com.google.guava:guava:28.0-android'\n}\n```\n\n### Kotlin\n\n```kotlin\ndependencies {\n implementation(\"androidx.ads:ads-identifier:1.0.0-alpha01\")\n\n // Used for the calls to addCallback() in the snippets on this page.\n implementation(\"com.google.guava:guava:28.0-android\")\n}\n```\n\nMyAdIdClient \n\n### Kotlin\n\n```kotlin\n// Used for the call to addCallback() within this snippet.\nimport com.google.common.util.concurrent.Futures.addCallback\n\nprivate fun determineAdvertisingInfo() {\n if (AdvertisingIdClient.isAdvertisingIdProviderAvailable()) {\n val advertisingIdInfoListenableFuture =\n AdvertisingIdClient.getAdvertisingIdInfo(applicationContext)\n\n addCallback(advertisingIdInfoListenableFuture,\n object : FutureCallback\u003cAdvertisingIdInfo\u003e {\n override fun onSuccess(adInfo: AdvertisingIdInfo?) {\n val id: String = adInfo?.id\n val providerPackageName: String = adInfo?.providerPackageName\n val isLimitTrackingEnabled: Boolean =\n adInfo?.isLimitTrackingEnabled\n }\n\n // Any exceptions thrown by getAdvertisingIdInfo()\n // cause this method to be called.\n override fun onFailure(t: Throwable) {\n Log.e(\"MY_APP_TAG\",\n \"Failed to connect to Advertising ID provider.\")\n // Try to connect to the Advertising ID provider again or fall\n // back to an ad solution that doesn't require using the\n // Advertising ID library.\n }\n }, Executors.newSingleThreadExecutor())\n } else {\n // The Advertising ID client library is unavailable. Use a different\n // library to perform any required ad use cases.\n }\n}\n```\n\n### Java\n\n```java\n// Used for the call to addCallback() within this snippet.\nimport com.google.common.util.concurrent.Futures;\n\nprivate void determineAdvertisingInfo() {\n if (AdvertisingIdClient.isAdvertisingIdProviderAvailable()) {\n ListenableFuture\u003cAdvertisingIdInfo\u003e advertisingIdInfoListenableFuture =\n AdvertisingIdClient.getAdvertisingIdInfo(getApplicationContext());\n Futures.addCallback(advertisingIdInfoListenableFuture,\n new FutureCallback\u003cAdvertisingIdInfo\u003e() {\n @Override\n public void onSuccess(AdvertisingIdInfo adInfo) {\n String id = adInfo.getId();\n String providerPackageName =\n adInfo.getProviderPackageName();\n boolean isLimitTrackingEnabled =\n adInfo.isLimitTrackingEnabled();\n\n // Any exceptions thrown by getAdvertisingIdInfo()\n // cause this method to be called.\n @Override\n public void onFailure(Throwable throwable) {\n Log.e(\"MY_APP_TAG\",\n \"Failed to connect to Advertising ID provider.\");\n // Try to connect to the Advertising ID provider again\n // or fall back to an ad solution that doesn't require\n // using the Advertising ID library.\n }\n });\n } else {\n // The Advertising ID client library is unavailable. Use a different\n // library to perform any required ad use cases.\n }\n}\n```\n\nAdvertising ID library architecture\n-----------------------------------\n\n**Figure 1.** Advertising ID library architecture\n\nFigure 1 depicts the structure of the Advertising ID library.\nThe library consists of the following modules:\n\n- A *client module*, which is a thin layer included in apps.\n- A *provider module*, which the device manufacturer makes available. Implementations of this module must define a settings UI to give users the ability to reset their advertising ID and toggle ad tracking preferences.\n\nThe client module communicates with the provider module to retrieve advertising\nIDs and user preferences regarding ad tracking.\n\n### How the library handles multiple providers\n\nIt's possible for a device to support multiple system-level ad providers at the\nsame time. If the Advertising ID library detects this situation, it ensures that\nyour app always retrieves information from the same provider, assuming that the\nprovider remains available. This process keeps the advertising ID consistent.\n\nIf the set of available ad providers changes over time and your app\ninteracts with a different ad identifier provider, all other client apps start\nusing that new provider as well. Your app demonstrates the same behavior that\nwould occur if the user had requested to reset their advertising ID.\n\nThe Advertising ID provider library uses the following deterministic order to\nrank the providers:\n\n1. Providers that have requested the `androidx.ads.identifier.provider.HIGH_PRIORITY` permission.\n2. Providers that have been installed on the device for the longest time.\n3. Providers that appear first in alphabetical order."]]