إعداد AdServices لنظام Android

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

ملاحظة: تتوفّر مكتبة Jetpack الجديدة لإتاحة التكامل مع واجهات برمجة التطبيقات التي تحافظ على الخصوصية ضمن "مبادرة حماية الخصوصية" (Topics وProtected Audience وAttribution Reporting. يمكنك استخدام هذه المكتبة كبديل لواجهات برمجة تطبيقات "مبادرة حماية الخصوصية" المتوفّرة في حزمة تطوير البرامج (SDK) للإضافات.

تعريف الأذونات الخاصة بواجهة AdServices API

يتطلب الوصول إلى كل PPAPI الحصول على إذن normal للخدمات الإعلانية. في بيانك، أعلِن عن أذونات الوصول المناسبة التي تتوافق مع واجهات برمجة التطبيقات المطلوبة في تطبيقك أو حزمة تطوير البرامج (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" />

Protected Audience API / custom Audience API:

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

Topics API:

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

إذا أردت تلقّي تقارير تصحيح الأخطاء باستخدام Attribution Reporting API، يجب تضمين الإذن AD_ID:

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

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

إذا كنت بحاجة إلى منع دمج أي من الأذونات في تطبيقك من خلال الاعتماديات مثل حِزم SDK، عليك تضمين علامة العُقدة remove للأذونات المعيّنة. يوضّح المثال التالي كيفية منع دمج إذن Topics.

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

ضبط "الخدمات الإعلانية" الخاصة بواجهة برمجة التطبيقات

على غرار أذونات الوصول إلى PPAPI، يكون لكل واجهة برمجة تطبيقات إدخال مطابق في إعدادات الخدمات الإعلانية. تمنحك هذه الإعدادات تحكمًا أكثر دقة في الوصول إلى الموارد التي تديرها واجهات برمجة التطبيقات في تطبيقك أو في حزمة تطوير البرامج (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. بالنسبة إلى كل واجهة برمجة تطبيقات تحافظ على الخصوصية تنطبق على تطبيقك (أو حزمة تطوير البرامج (SDK) المضمّنة)، عليك ضبط السمة allowAllToAccess على true لمنح إمكانية الوصول إلى أي متصِلين.

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

ملاحظة: للوصول إلى واجهات برمجة تطبيقات "مبادرة حماية الخصوصية" في أحدث إصدار من إضافة AdServices SDK وفي إصدار "معاينة المطوّرين"، عليك إكمال عملية التسجيل.

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

ملاحظة: بسبب خطأ معروف، يجب ضبط allowAllToAccess على true عند الاختبار محليًا.

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

<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>

يوضّح المثال التالي كيفية تحديد أذونات وصول أكثر دقة إلى كل واجهة برمجة تطبيقات تحافظ على الخصوصية لأرقام تعريف حساب تسجيل محدَّد:

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

تعريف تبعيات مكتبة Jetpack

استخدِم الإصدار 1.0.0-beta01 من مكتبة ads-adservices Jetpack أو الإصدارات الأحدث للدمج مع واجهات برمجة التطبيقات التي تحافظ على الخصوصية في "مبادرة حماية الخصوصية". يمكنك استخدام هذه المكتبة لاستخلاص تطبيقك من التفاصيل على مستوى النظام الأساسي وتبسيط التكامل مع واجهات برمجة التطبيقات التي تحافظ على الخصوصية.

1. يمكنك إضافة مستودع Maven إلى مشروعك.
2. يجب توضيح تبعيات مكتبة Jetpack على الإعلانات (ads-adservices) في ملف build.gradle لتطبيقك أو الوحدة.
3. يمكنك استخدام واجهات برمجة التطبيقات من حِزم androidx.privacysandbox.ads.adservices.*.
4. إنّ مكتبة ads-adservices Jetpack توفّر دعمًا مُدمَجًا لكروتين في لغة Kotlin. قد تحتاج إلى دمج التبعيات الواعية بدورة الحياة المناسبة لمشروعك من أجل إدارة نطاقات الكوروتين.

التحقق من مدى توفّر إصدار "إضافات خدمات الإعلانات"

إذا كنت تستخدم مكتبة Jetpack للخدمات الإعلانية للدمج مع واجهات برمجة التطبيقات التي تحافظ على الخصوصية، ستتحقّق المكتبة من مدى توفّر واجهات برمجة التطبيقات المطلوبة في الدالة obtain(). تعرض الدالة قيمة فارغة إذا لم تكن واجهة برمجة التطبيقات المطلوبة متاحة على الجهاز. يوضّح المثال التالي كيفية إعداد TopicsManager لواجهة Topics API. وهي تعمل بشكل مشابه للوصول إلى واجهات برمجة التطبيقات الأخرى للحفاظ على الخصوصية.

Kotlin

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)

Java

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 في حزمة تطوير البرامج (SDK) للإضافات مباشرةً، تحقَّق من إصدار إضافات AdServices الذي يتضمّن واجهات برمجة تطبيقات AdServices التي تريد استخدامها. في مرجع واجهة برمجة التطبيقات، يمكنك تحديد الإصدار الذي يتضمّن واجهة برمجة تطبيقات معيّنة لخدمات AdServices. على سبيل المثال، يشير مرجع واجهة برمجة التطبيقات للفئة TopicsManager إلى أنّه "تمت الإضافة في إضافات الخدمات الإعلانية 4". يمكنك تنفيذ عمليات التحقّق المشروطة التالية للتحقّق من صحة إضافات حزمة تطوير البرامج (SDK) التي تحتوي على واجهات برمجة تطبيقات AdServices.

Kotlin

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

Java

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" وواجهات برمجة التطبيقات التي تحافظ على الخصوصية على التطبيقات التي تتضمّن نشاطًا مرئيًا أو التي تتضمّن RunningAppProcessInfo من IMPORTANCE_FOREGROUND.