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

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

الإفصاح عن الأذونات الخاصة بواجهة برمجة التطبيقات AdServices API

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

تلقّي تقارير تصحيح الأخطاء من خلال "تقارير تحديد المصدر" اختياريًا واجهة برمجة التطبيقات، يجب تضمين إذن AD_ID:

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

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

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

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

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.