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

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

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

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

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

تعريف العناصر التابعة لمكتبة Jetpack

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

  1. أضِف مستودع Maven إلى مشروعك.
  2. يُرجى تقديم تبعيات مكتبة Jetpack لخدمات ads-adservices في ملف build.gradle الخاص بتطبيقك أو وحدتك.
  3. يمكنك استخدام واجهات برمجة التطبيقات من حِزم androidx.privacysandbox.ads.adservices.*.
  4. توفِّر مكتبة 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 API معيّنة. على سبيل المثال، يشير مرجع واجهة برمجة التطبيقات لفئة 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.