احصل على معرِّف إعلاني يمكن إعادة ضبطه من قِبل المستخدم جزء من 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.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.
    }
}

جافا

// 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. اسم مقدّم الخدمة الذي يظهر أولاً بترتيب أبجدي.