Android için AdServices'ı yapılandırma

API'ye özel izinleri tanımlamak ve hedeflenen API tarafından yönetilen kaynaklara SDK erişimini yapılandırmak için aşağıdaki talimatları uygulayın.

Not: Özel Korumalı Alan'ın gizliliği korumaya yönelik API'leriyle (Topics, Protected Audience ve Attribution Reporting) entegrasyona olanak tanıyan yeni bir Jetpack kitaplığı vardır. Bu kitaplığı, Uzantı SDK'sında sağlanan Özel Korumalı Alan API'lerinin yerine yedek olarak kullanabilirsiniz.

AdServices API'ye özel izinleri bildirme

Her PPAPI'ye erişim için Reklam Hizmetleri normal izni gerekir. Manifestinizde, uygulamanızda veya SDK'nızda gereken API'lere karşılık gelen uygun erişim izinlerini belirtin.

Attribution Reporting API:

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

Attribution Reporting API (hata ayıklama raporlarıyla birlikte):

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

Protected Audience / özel kitle API'si:

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

Topics API:

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

İsteğe bağlı olarak, Attribution Reporting API ile hata ayıklama raporları almak için AD_ID iznini ekleyin:

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

Projenizin modül veya SDK'lara bağımlılığı varsa gerekli Reklam Hizmetleri izinlerini manifest dosyalarında halihazırda beyan etmiş olabilirler. Varsayılan olarak Gradle derlemesi, tüm manifest dosyalarını uygulamanızda paketlenmiş tek bir manifest dosyasında birleştirir. Doğru izinlerin kullanıldığını doğrulamak için Birleştirilmiş Manifest görünümünü kullanın.

SDK'lar gibi bağımlılıklar aracılığıyla izinlerden herhangi birinin uygulamanızla birleştirilmesini engellemeniz gerekiyorsa söz konusu izinler için remove düğüm işaretçisini ekleyin. Aşağıdaki örnekte Topics izninin birleştirilmesinin nasıl önleneceği gösterilmektedir.

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

API'ye Özel Reklam Hizmetlerini Yapılandır

PPAPI erişim izinlerine benzer şekilde, her API'nin reklam hizmetleri yapılandırmasında karşılık gelen bir girişi vardır. Bu yapılandırma, uygulamanızdaki API'ler veya yerleştirilmiş SDK'lar tarafından yönetilen kaynaklara ayrıntılı kontrol erişimi sağlar. Manifestinizde, aşağıdaki örnekte gösterildiği gibi bir adservicesConfig özelliği belirtin:

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

      ...
</application>

Manifest'te referans verilen reklam hizmetleri XML kaynağını belirtin (ör. res/xml/ad_services_config.xml). Uygulamanıza (veya yerleştirilmiş SDK'ya) uygun olan ve gizliliği korumaya yönelik her API'nin allowAllToAccess özelliğini true olarak ayarlayarak arayanlara erişim izni verin.

Alternatif olarak, her bir reklam teknolojisine ayrıntılı API erişimi vermek için allowAdPartnersToAccess özelliğini kullanabilirsiniz. Kayıt yoluyla elde edilen geliştirici kayıt hesap kimliklerinin listesini sağlamanız gerekir. allowAllToAccess özelliği true olarak ayarlanırsa bu özellik, allowAdPartnersToAccess özelliğinde belirtilen tüm kayıt hesabı kimliklerine göre öncelikli olur.

Not: AdServices SDK'sının son sürümünde ve Geliştirici Önizlemesi sürümünde Özel Korumalı Alan API'lerine erişmek için kayıt işlemini tamamlamanız gerekir.

Reklam teknolojisi platformları, uygulama istemcilerinin reklam hizmetleri yapılandırmasında gizliliği korumaya yönelik gerekli API'lere düzgün şekilde erişim izni verdiğinden de emin olmalıdır.

Not: Bilinen bir hata nedeniyle, yerel olarak test ederken allowAllToAccess değerini true olarak ayarlamanız gerekir.

Aşağıdaki örnekte, gizliliği korumaya yönelik tüm API'lere kayıt hesap kimliği erişimlerine izin vermek için geniş erişimin nasıl belirtileceği gösterilmektedir:

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

Aşağıdaki örnekte, belirli kayıt hesabı kimlikleri için her bir gizliliği korumaya yönelik API'ye ayrıntılı erişimin nasıl belirtileceği gösterilmektedir:

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

Not: Topics API veya Protected Audience API için adb komutları kullanılarak kayıt devre dışı bırakılırsa uygulama, ad-services-config içinde belirtilen erişim denetimlerinden bağımsız olarak ilgili API'lere erişebilir.

Jetpack kitaplık bağımlılıklarını bildirme

Özel Korumalı Alan'ın gizliliği korumaya yönelik API'leriyle entegrasyon yapmak için ads-adservices Jetpack kitaplığı 1.0.0-beta01 veya sonraki bir sürümünü kullanın. Uygulamanızı platform düzeyindeki ayrıntılardan soyutlamak ve gizliliği korumaya yönelik API'lerle entegrasyonu basitleştirmek için bu kitaplığı kullanabilirsiniz.

1. Projenize bir Maven deposu ekleyin.
2. Uygulamanızın veya modülünüz için build.gradle dosyasında ads-adservices Jetpack kitaplık bağımlılıklarını bildirin.
3. androidx.privacysandbox.ads.adservices.* paketlerindeki API'leri kullanın.
4. Ads reklam hizmetleri Jetpack kitaplığı, yerleşik Kotlin eş yordam desteği sağlar. Eş yordam kapsamlarını yönetmek için projenize uygun olan yaşam döngüsüne duyarlı bağımlılıkları dahil etmeniz gerekebilir.

Reklam Hizmetleri Uzantıları sürümünün kullanılabilirliğini kontrol etme

Gizliliği koruyan API'lerle entegrasyon için reklam hizmetleri Jetpack kitaplığını kullanıyorsanız kitaplık, obtain() işlevindeki istenen API'lerin kullanılabilir olup olmadığını kontrol eder. İstenen API cihazda mevcut değilse işlev null değerini döndürür. Aşağıdaki örnekte, Topics API için TopicsManager öğesinin nasıl başlatılacağı gösterilmektedir. Gizliliği koruyan diğer API'lere erişimde de benzer şekilde çalışır.

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

Doğrudan Uzantı SDK'sında AdServices API'lerini kullanıyorsanız kullanmak istediğiniz AdServices API'lerini içeren AdServices Extensions sürümünü kontrol edin. API referansında, belirli bir AdServices API'nin kullanıma sunulduğu sürümü tanımlayabilirsiniz. Örneğin, TopicsManager sınıfına ilişkin API referansı, bunun "Reklam Hizmetleri Uzantıları 4'te Eklendi" olduğunu belirtir. AdServices API'lerini içeren SDK uzantılarını doğrulamak için aşağıdaki koşullu kontrolleri kullanın.

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

Ön plan erişim sınırlaması

Şeffaflık sağlamak amacıyla SDK Çalışma Zamanı ve gizliliği korumaya yönelik API'lere erişim, görünür Etkinliği olan veya RunningAppProcessInfo değerindeki IMPORTANCE_FOREGROUND uygulamalarla sınırlıdır.