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

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

لإتاحة حلّ موحّد لتتبُّع الإعلانات على جميع الأجهزة التي يشغّل تطبيقك، يمكنك استخدام مكتبة المعرّف الإعلاني. تتوفّر هذه المكتبة على الأجهزة التي تعمل بالإصدار 4.0 من نظام التشغيل Android (المستوى 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'
}

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

// 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. مقدّمو الخدمات الذين طلبوا الحصول على إذن androidx.ads.identifier.provider.HIGH_PRIORITY
2. مقدّمو الخدمات الذين تم تثبيتهم على الجهاز لأطول مدة
3. مقدّمو الخدمة الذين يظهرون أولاً بالترتيب الأبجدي