احصل على معرِّف إعلاني يمكن للمستخدم إعادة ضبطه جزءًا من Android Jetpack.

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

لإتاحة حل موحّد لتتبّع الإعلانات على مستوى الأجهزة التي تشغّل تطبيقك، يمكنك استخدام مكتبة المعرِّف الإعلاني. إنّ هذه المكتبة المتوفرة على الأجهزة التي تعمل بنظام التشغيل Android 4.0 (المستوى 14 لواجهة برمجة التطبيقات) والإصدارات الأحدث، تحدّد واجهة للتفاعل مع مقدّمي الإعلانات على مستوى النظام. تسمح هذه الواجهة لتطبيقك بتلقّي قيم متّسقة للمعرِّف الإعلاني.

يحدّد أيضًا موفِّر الإعلانات المضمَّن في مكتبة المعرِّف الإعلاني هدفًا عاديًا لفتح شاشة إعدادات يستخدمها موفِّر الإعلانات. تتيح شاشة الإعدادات هذه للمستخدم إعادة ضبط المعرّف الإعلاني وإيقاف ميزة تخصيص الإعلانات.

يشرح هذا الدليل كيفية استخدام وحدة العميل في مكتبة المعرِّف الإعلاني للحصول على معرِّف إعلاني ثابت لكل مستخدم على حدة. يقدم هذا الدليل بعد ذلك نظرة عامة على بنية المكتبة.

ضبط تطبيق العميل

من خلال التفاعل مع وحدة العميل في مكتبة المعرِّف الإعلاني، يمكن لتطبيقك استرداد معرِّف إعلاني متسق يمثّل المستخدم الذي يتفاعل مع التطبيق.

يتم تمثيل المعرّف الإعلاني باستخدام الإصدار 3 من تنسيق المعرّف الفريد عالميًا (UUID) أو تنسيق 128 بت مكافئ:

38400000-8cf0-11bd-b23e-10b96e40000d

تعمل مكتبة المعرِّف الإعلاني على تسوية القيمة المعروضة حسب الضرورة لتقديم معرّفات باستخدام هذا التنسيق.

لاسترداد المعرِّف الإعلاني الذي يمكن للمستخدم إعادة ضبطه في تطبيقك، أكمل الخطوات التالية:

  1. يمكنك التحقّق مما إذا كان مقدّم الإعلانات متاحًا من خلال الاتصال على الرقم AdvertisingIdClient.isAdvertisingIdProviderAvailable(). وإذا نتج عن هذه الطريقة عرض false، يجب أن يستخدم تطبيقك وسيلة أخرى لتنفيذ أي حالات استخدام مطلوبة لتتبُّع الإعلانات.

  2. يمكنك الحصول على تفاصيل معرّف الإعلان، بما في ذلك المعرّف الإعلاني، من خلال الاتصال على الرقم AdvertisingIdClient.getAdvertisingIdInfo(). تنفّذ مكتبة المعرِّف الإعلاني هذه الطريقة على سلسلة محادثات عاملة وتستخدم مهلة اتصال مدتها 10 ثوانٍ.

يوضّح مقتطف الرمز التالي كيفية استرداد المعرّف الإعلاني إلى جانب معلومات أخرى من موفِّر الإعلانات:

app/build.grale

رائع

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. بنية مكتبة المعرِّف الإعلاني

يوضّح الشكل 1 بنية مكتبة المعرِّفات الإعلانية. وتتكوّن المكتبة من الوحدات التالية:

  • وحدة العميل، وهي طبقة رفيعة مضمَّنة في التطبيقات.
  • وحدة مزوّد الخدمة التي توفّرها الشركة المصنّعة للجهاز يجب أن تحدّد عمليات تنفيذ هذه الوحدة واجهة مستخدم للإعدادات لمنح المستخدمين القدرة على إعادة ضبط المعرِّف الإعلاني وتبديل الإعدادات المفضّلة الخاصة بتتبُّع الإعلانات.

تتواصل وحدة العميل مع وحدة مقدّم الخدمة لاسترداد معرّفات الإعلانات وتفضيلات المستخدم في ما يتعلق بتتبُّع الإعلانات.

كيفية تعامل المكتبة مع العديد من مقدّمي الخدمات

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

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

تستخدم مكتبة موفّري المعرِّف الإعلاني الترتيب المؤكد التالي لترتيب المزوّدين:

  1. مقدّمو الخدمات الذين طلبوا إذن "androidx.ads.identifier.provider.HIGH_PRIORITY":
  2. مقدّمو الخدمات الذين ثبّتوا الجهاز على الجهاز لمدة أطول
  3. مقدّمو الخدمات الذين يظهرون أولاً بترتيب أبجدي.