دریافت شناسه تبلیغاتی قابل تنظیم مجدد توسط کاربر، بخشی از Android Jetpack .

توجه: اگر قصد دارید برنامه خود را با استفاده از گوگل پلی منتشر و توزیع کنید، به جای این کتابخانه ، از کتابخانه شناسه تبلیغات که به عنوان بخشی از سرویس‌های گوگل پلی در دسترس است، استفاده کنید.

برای محافظت از حریم خصوصی کاربر، بهترین روش برای همه برنامه‌های اندروید این است که با شناسه‌های قابل تنظیم مجدد کاربر کار کنند. یکی از این شناسه‌ها، شناسه تبلیغاتی است که به طور منحصر به فرد یک کاربر خاص را برای موارد استفاده تبلیغاتی، مانند شخصی‌سازی تبلیغات، شناسایی می‌کند.

برای پشتیبانی از یک راهکار استاندارد ردیابی تبلیغات در دستگاه‌هایی که برنامه شما را اجرا می‌کنند، می‌توانید از کتابخانه Advertising ID استفاده کنید. این کتابخانه که در دستگاه‌های دارای اندروید ۴.۰ (سطح API ۱۴) و بالاتر موجود است، رابطی را برای تعامل با ارائه‌دهندگان تبلیغات در سطح سیستم تعریف می‌کند. این رابط به برنامه شما اجازه می‌دهد مقادیر شناسه تبلیغاتی ثابتی را دریافت کند.

ارائه‌دهنده‌ی تبلیغاتی که در کتابخانه‌ی شناسه‌ی تبلیغات (Advertising ID) قرار دارد، یک هدف استاندارد برای باز کردن صفحه‌ی تنظیماتی که ارائه‌دهنده‌ی تبلیغات پیاده‌سازی می‌کند، تعریف می‌کند. این صفحه‌ی تنظیمات به کاربر اجازه می‌دهد شناسه‌ی تبلیغاتی خود را مجدداً تنظیم کند و از شخصی‌سازی تبلیغات انصراف دهد.

این راهنما نحوه استفاده از ماژول کلاینت کتابخانه Advertising ID را برای دستیابی به یک شناسه تبلیغاتی ثابت بر اساس هر دستگاه-کاربر توضیح می‌دهد. سپس این راهنما مروری بر معماری کتابخانه ارائه می‌دهد.

برنامه کلاینت خود را پیکربندی کنید

با تعامل با ماژول کلاینت کتابخانه‌ی Advertising ID، برنامه‌ی شما می‌تواند یک Advertising ID ثابت را بازیابی کند که نشان دهنده‌ی کاربری است که با برنامه در تعامل است.

شناسه تبلیغاتی با استفاده از نسخه ۳ قالب شناسه منحصر به فرد جهانی (UUID) یا یک قالب ۱۲۸ بیتی معادل آن نمایش داده می‌شود:

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

کتابخانه‌ی Advertising ID مقدار بازگشتی را در صورت لزوم برای ارائه‌ی شناسه‌ها با استفاده از این قالب، نرمال‌سازی می‌کند.

توجه: اکثر ارائه‌دهندگان تبلیغات اطمینان حاصل می‌کنند که شناسه تبلیغاتی برای هر کاربر دستگاه منحصر به فرد باشد. در دستگاه‌های اندرویدی که از چندین کاربر، از جمله کاربران مهمان، پشتیبانی می‌کنند، برنامه شما می‌تواند شناسه‌های تبلیغاتی مختلفی را در یک دستگاه دریافت کند. این شناسه‌های مختلف مربوط به کاربران مختلفی است که می‌توانند در آن دستگاه وارد سیستم شوند.

برای بازیابی شناسه تبلیغاتی قابل تنظیم مجدد توسط کاربر برای برنامه خود، مراحل زیر را انجام دهید:

1. با فراخوانی AdvertisingIdClient.isAdvertisingIdProviderAvailable() بررسی کنید که آیا یک ارائه‌دهنده تبلیغات در دسترس است یا خیر. اگر این متد false برگرداند، برنامه شما باید از روش دیگری برای انجام هرگونه موارد استفاده ردیابی تبلیغات مورد نیاز استفاده کند.

   احتیاط: حتی اگر این متد true را برگرداند، برنامه شما باید بتواند هرگونه استثنائی را که ممکن است هنگام تلاش برای بازیابی شناسه تبلیغات رخ دهد، مدیریت کند.

2. با فراخوانی AdvertisingIdClient.getAdvertisingIdInfo() جزئیات شناسه تبلیغ، از جمله شناسه تبلیغات، را دریافت کنید. کتابخانه Advertising ID این متد را روی یک نخ کارگر اجرا می‌کند و از یک زمان اتصال 10 ثانیه‌ای استفاده می‌کند.

   نکته: از آنجایی که کاربر می‌تواند شناسه تبلیغاتی خود را پس از شروع برنامه، مجدداً تنظیم کند، باید هر بار که برنامه شما نیاز به بررسی مقدار شناسه دارد، AdvertisingIdClient.getAdvertisingIdInfo() را فراخوانی کنید. این مقدار را ذخیره نکنید.

قطعه کد زیر نحوه بازیابی شناسه تبلیغات به همراه سایر اطلاعات از ارائه دهنده تبلیغ را نشان می‌دهد:

برنامه/ساخت.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")
}

کلاینت من

کاتلین

// 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.
    }
}

معماری کتابخانه شناسایی تبلیغات

شکل ۱. معماری کتابخانه شناسه تبلیغات

شکل ۱ ساختار کتابخانه‌ی Advertising ID را نشان می‌دهد. این کتابخانه از ماژول‌های زیر تشکیل شده است:

• یک ماژول کلاینت ، که یک لایه نازک است که در برنامه‌ها گنجانده شده است.
• یک ماژول ارائه‌دهنده ، که سازنده دستگاه آن را در دسترس قرار می‌دهد. پیاده‌سازی‌های این ماژول باید یک رابط کاربری تنظیمات را تعریف کنند تا به کاربران امکان تنظیم مجدد شناسه تبلیغات خود و تغییر تنظیمات ردیابی تبلیغات را بدهد.

ماژول کلاینت با ماژول ارائه‌دهنده ارتباط برقرار می‌کند تا شناسه‌های تبلیغاتی و تنظیمات برگزیده کاربر در مورد ردیابی تبلیغات را بازیابی کند.

نحوه مدیریت کتابخانه توسط چندین ارائه‌دهنده

این امکان وجود دارد که یک دستگاه به طور همزمان از چندین ارائه‌دهنده تبلیغات در سطح سیستم پشتیبانی کند. اگر کتابخانه شناسه تبلیغات این وضعیت را تشخیص دهد، تأیید می‌کند که برنامه شما همیشه اطلاعات را از همان ارائه‌دهنده بازیابی می‌کند، با فرض اینکه ارائه‌دهنده در دسترس باشد. این فرآیند، شناسه تبلیغات را ثابت نگه می‌دارد.

اگر مجموعه ارائه‌دهندگان تبلیغات موجود به مرور زمان تغییر کند و برنامه شما با یک ارائه‌دهنده شناسه تبلیغات متفاوت تعامل داشته باشد، همه برنامه‌های کلاینت دیگر نیز شروع به استفاده از آن ارائه‌دهنده جدید می‌کنند. برنامه شما همان رفتاری را نشان می‌دهد که اگر کاربر درخواست تنظیم مجدد شناسه تبلیغات خود را داده بود، رخ می‌داد.

کتابخانه ارائه دهنده شناسه تبلیغاتی از ترتیب قطعی زیر برای رتبه بندی ارائه دهندگان استفاده می کند:

1. ارائه‌دهندگانی که مجوز androidx.ads.identifier.provider.HIGH_PRIORITY را درخواست کرده‌اند.
2. ارائه دهندگانی که برای طولانی ترین مدت روی دستگاه نصب شده اند.
3. ارائه دهندگانی که به ترتیب حروف الفبا ابتدا ظاهر می‌شوند.