AdServices را برای اندروید پیکربندی کنید

دستورالعمل های زیر را برای اعلام مجوزهای خاص API و پیکربندی دسترسی SDK به منابع مدیریت شده توسط API هدفمند دنبال کنید.

توجه: یک کتابخانه Jetpack جدید وجود دارد که امکان ادغام با APIهای حفظ حریم خصوصی Privacy Sandbox ( موضوعات ، مخاطبین محافظت شده و گزارش اسناد را فراهم می کند. می توانید از این کتابخانه به عنوان جایگزینی برای APIهای Privacy Sandbox ارائه شده در Extension SDK استفاده کنید.

مجوزهای مربوط به API AdServices را اعلام کنید

دسترسی به هر PPAPI نیاز به مجوز normal سرویس تبلیغات دارد. در مانیفست خود، مجوزهای دسترسی مناسب را که با APIهای مورد نیاز در برنامه یا SDK شما مطابقت دارد، اعلام کنید.

Attribution Reporting API:

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_ATTRIBUTION" />

Attribution Reporting API (با گزارش‌های اشکال‌زدایی):

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_ATTRIBUTION" />
<uses-permission android:name="android.permission.ACCESS_ADSERVICES_AD_ID" />

API مخاطبان محافظت شده / مخاطبان سفارشی:

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />

Topics API:

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_TOPICS" />

در صورت تمایل، برای دریافت گزارش‌های اشکال‌زدایی با API Attribution Reporting، مجوز AD_ID را اضافه کنید:

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_AD_ID" />

اگر پروژه شما به ماژول ها یا SDK ها وابستگی دارد، ممکن است مجوزهای مورد نیاز سرویس های تبلیغاتی را در فایل های مانیفست خود اعلام کنند. به طور پیش‌فرض، ساخت Gradle همه فایل‌های مانیفست را در یک فایل مانیفست واحد که در برنامه شما بسته‌بندی شده است، ادغام می‌کند. از نمای Manifest Merged برای تأیید اینکه مجوزهای صحیح استفاده شده است استفاده کنید.

اگر نیاز دارید از ادغام هر یک از مجوزها از طریق وابستگی هایی مانند SDK در برنامه خود جلوگیری کنید، نشانگر remove گره را برای مجوزهای خاص اضافه کنید. مثال زیر نحوه جلوگیری از ادغام مجوز Topics را نشان می دهد.

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_TOPICS"
    tools:node="remove" />

پیکربندی سرویس های تبلیغاتی خاص API

مشابه مجوزهای دسترسی PPAPI، هر API دارای ورودی مربوطه در پیکربندی سرویس های تبلیغاتی است. این پیکربندی به شما امکان دسترسی کنترل دقیق به منابع مدیریت شده توسط APIهای برنامه یا SDK تعبیه شده را می دهد. همانطور که در مثال زیر نشان داده شده است، در مانیفست خود، یک ویژگی adservicesConfig را مشخص کنید:

<application ...>
      ...
    <property android:name="android.adservices.AD_SERVICES_CONFIG"
        android:resource="@xml/ad_services_config" />

      ...
</application>

منبع XML خدمات تبلیغاتی را که در مانیفست ارجاع داده شده است، مشخص کنید، مانند res/xml/ad_services_config.xml . برای هر API حفظ حریم خصوصی که برای برنامه شما (یا SDK تعبیه شده) قابل اجرا است، ویژگی allowAllToAccess را روی true تنظیم کنید تا به هر تماس گیرنده دسترسی داشته باشید.

از طرف دیگر، می‌توانید از ویژگی allowAdPartnersToAccess برای اعطای دسترسی API دقیق به هر فناوری تبلیغاتی استفاده کنید. باید فهرستی از شناسه‌های حساب ثبت‌نام توسعه‌دهنده که از طریق ثبت‌نام به دست آمده‌اند ارائه کنید. اگر ویژگی allowAllToAccess روی true تنظیم شود، این ویژگی بر هر شناسه حساب ثبت نامی که در ویژگی allowAdPartnersToAccess مشخص شده است، اولویت دارد.

توجه: برای دسترسی به APIهای Privacy Sandbox در آخرین نسخه AdServices SDK Extension و در نسخه Developer Preview، باید فرآیند ثبت نام را تکمیل کنید.

پلتفرم‌های فناوری تبلیغات همچنین باید مطمئن شوند که سرویس‌گیرندگان برنامه‌شان به درستی به APIهای مورد نیاز حفظ حریم خصوصی در پیکربندی سرویس‌های تبلیغاتی دسترسی دارند.

توجه: به دلیل یک اشکال شناخته شده، هنگام آزمایش محلی، باید allowAllToAccess را روی true تنظیم کنید.

مثال زیر نشان می دهد که چگونه می توان دسترسی گسترده را تعیین کرد تا به هر شناسه حساب ثبت نامی اجازه دسترسی به همه APIهای حفظ حریم خصوصی داده شود:

<ad-services-config>
   <!-- Attribution API -->
   <attribution allowAllToAccess="true" />

   <!-- Topics API -->
   <topics allowAllToAccess="true" />

   <!-- Protected Audience on Android API -->
   <custom-audiences allowAllToAccess="true" />
</ad-services-config>

مثال زیر نحوه تعیین دسترسی دقیق به هر API حفظ حریم خصوصی را برای شناسه های حساب ثبت نام خاص نشان می دهد:

<ad-services-config>
    <!-- Attribution API -->
    <attribution allowAdPartnersToAccess="ENROLLMENT-ID" allowAllToAccess="false" />

    <!-- Topics API -->
    <includes-sdk-library name="ENROLLMENT-ID" />
    <topics allowAdPartnersToAccess="ENROLLMENT-ID" allowAllToAccess="false" />

    <!-- Protected Audience on Android API -->
    <custom-audiences allowAdPartnersToAccess="ENROLLMENT-ID" allowAllToAccess="false" />
</ad-services-config>

توجه: اگر ثبت‌نام برای Topics API یا Protected Audience API با استفاده از دستورات adb غیرفعال باشد، برنامه می‌تواند بدون در نظر گرفتن کنترل‌های دسترسی مشخص‌شده در ad-services-config به APIهای مرتبط دسترسی داشته باشد.

وابستگی های کتابخانه Jetpack را اعلام کنید

از کتابخانه تبلیغاتی Jetpack 1.0.0-beta01 یا بالاتر برای ادغام با APIهای حفظ حریم خصوصی Privacy Sandbox استفاده کنید. می توانید از این کتابخانه برای انتزاع برنامه خود از جزئیات سطح پلت فرم و ساده سازی ادغام با API های حفظ حریم خصوصی استفاده کنید.

1. یک مخزن Maven به پروژه خود اضافه کنید.
2. در فایل build.gradle برای برنامه یا ماژول خود ، وابستگی های کتابخانه Jetpack ads-adservices را اعلام کنید.
3. از API های بسته های androidx.privacysandbox.ads.adservices.* استفاده کنید.
4. کتابخانه Jetpack Ads-Adservices پشتیبانی داخلی Kotlin را فراهم می کند. ممکن است لازم باشد وابستگی‌های آگاه از چرخه حیات مناسب برای پروژه خود را برای مدیریت دامنه‌های معمولی ترکیب کنید.

در دسترس بودن نسخه افزونه های خدمات تبلیغاتی را بررسی کنید

اگر از کتابخانه سرویس‌های تبلیغاتی Jetpack برای ادغام با APIهای حفظ حریم خصوصی استفاده می‌کنید، کتابخانه در دسترس بودن APIهای درخواستی را در تابع obtain() بررسی می‌کند. در صورتی که API درخواستی در دستگاه موجود نباشد، این تابع null برمی‌گرداند. مثال زیر نحوه تنظیم اولیه TopicsManager برای Topics API را نشان می دهد. به طور مشابه برای دسترسی به سایر APIهای حفظ حریم خصوصی کار می کند.

کاتلین

import androidx.privacysandbox.ads.adservices.topics.TopicsManager

// The initialization function will return null if the requested
// functionality is not available on the device.
val topicsManager = TopicsManager.obtain(context)

جاوا

import androidx.privacysandbox.ads.adservices.topics.TopicsManager;

// The initialization function will return null if the requested
// functionality is not available on the device.
TopicsManager topicsManager = TopicsManager.obtain(context);

اگر مستقیماً از AdServices API در Extension SDK استفاده می‌کنید، نسخه AdServices Extensions را که شامل AdServices APIهایی است که می‌خواهید استفاده کنید، بررسی کنید. در مرجع API، می‌توانید نسخه‌ای را شناسایی کنید که یک AdServices API خاص در آن معرفی شده است. به عنوان مثال، مرجع API برای کلاس TopicsManager نشان می‌دهد که "افزوده شده در Ad Services Extensions 4" است. از بررسی‌های شرطی زیر برای تأیید اعتبار برنامه‌های افزودنی SDK که حاوی AdServices API هستند استفاده کنید.

کاتلین

import android.os.ext.SdkExtensions

if (SDK_INT >= Build.VERSION_CODES.R && // The extensions API is available since R.
   SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4) {

    // AdServices API is available.
...
}

جاوا

import android.os.ext.SdkExtensions;

if (SDK_INT >= Build.VERSION_CODES.R && // The extensions API is available since R.
   SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4) {

    // AdServices API is available.
...
}

محدودیت دسترسی به پیش زمینه

برای ایجاد شفافیت، دسترسی به SDK Runtime و APIهای حفظ حریم خصوصی به برنامه‌هایی با یک Activity قابل مشاهده یا با RunningAppProcessInfo از IMPORTANCE_FOREGROUND محدود می‌شود.