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

API'ye özel izinleri beyan etmek 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 Koruyan API'leriyle (Topics, Protected Audience ve Attribution Reporting) entegrasyonu sağlayan yeni bir Jetpack kitaplığı var. Bu kitaplığı, Uzantı SDK'sında sağlanan Özel Korumalı Alan API'lerinin yerine kullanabileceğiniz bir alternatif olarak kullanabilirsiniz.

AdServices API'ye özel izinleri bildirme

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

Attribution Reporting API:

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

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

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

Dilerseniz hata ayıklama raporlarını Attribution Reporting API ile almak için AD_ID iznini ekleyin:

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

Projenizin modüllere veya SDK'lara bağımlıları varsa bunlar manifest dosyalarında gerekli Reklam Hizmetleri izinlerini zaten bildirmiş olabilir. Varsayılan olarak, Gradle derlemesi tüm manifest dosyalarını uygulamanızda paketlenen 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.

İzinlerden herhangi birinin, SDK gibi bağımlılıklar aracılığıyla uygulamanızla birleştirilmesini önlemeniz 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ırma

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şik SDK'lar tarafından yönetilen kaynaklara ayrıntılı denetim erişimi sağlar.

Not: Belirli Reklam Hizmetleri'ni yapılandırmak isteğe bağlıdır ve yalnızca uygulama geliştirici bir API'ye erişimi değiştirmek veya kısıtlamak istediğinde gerekir. Çünkü tüm erişim varsayılan olarak verilir.

Manifest'inizde, 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 başvurulan reklam hizmetleri XML kaynağını (ör. res/xml/ad_services_config.xml) belirtin. Uygulamanız (veya yerleştirilmiş SDK) için geçerli olan gizliliği korumaya yönelik her API'de, arayan kişilere erişim izni vermek için allowAllToAccess özelliğini true olarak ayarlayın.

Alternatif olarak, her reklam teknolojisine ayrıntılı API erişimi vermek için allowAdPartnersToAccess özelliğini kullanabilirsiniz. Kayıt yoluyla edinilen 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ı kimliklerinden öncelikli olur.

Not: En yeni AdServices SDK Uzantısı 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 müşterilerinin reklam hizmetleri yapılandırmasındaki gizliliği korumaya yönelik gerekli API'lere düzgün bir şekilde erişim izni vermesini de sağlamalı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şimine 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 hesap kimlikleri için gizliliği korumaya yönelik her bir 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 kaydı adb komutları kullanılarak devre dışı bırakılırsa uygulama, ad-services-config bölümünde belirtilen erişim kontrollerinden bağımsız olarak ilgili API'lere erişebilir.

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

Özel Korumalı Alan'ın gizliliği korumaya yönelik API'leriyle entegrasyon için ads-adservices Jetpack kitaplığı 1.0.0-beta01 veya üstü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 Maven deposu ekleyin.
2. Uygulamanız veya modülünüz için build.gradle dosyasında ads-adservices Jetpack kitaplığı bağımlılıklarını bildirin.
3. androidx.privacysandbox.ads.adservices.* paketlerindeki API'leri kullanın.
4. Ads-adservices Jetpack kitaplığı, yerleşik Kotlin eş yordam desteği sağlar. Koordin kapsamları yönetmek için projenize uygun, 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 korumaya yönelik API'lerle entegrasyon için reklam hizmetleri Jetpack kitaplığını kullanıyorsanız kitaplık, istenen API'lerin obtain() işlevinde kullanılabilir olup olmadığını kontrol eder. İstenen API cihazda yoksa işlev null değerini döndürür. Aşağıdaki örnekte, Topics API için TopicsManager özelliğinin nasıl ilk kullanıma hazırlanacağı gösterilmektedir. Gizliliği korumaya yönelik diğer API'lere erişmek için 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);

Uzantı SDK'sında AdServices API'lerini doğrudan 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'sinin kullanıma sunulduğu sürümü tanımlayabilirsiniz. Örneğin, TopicsManager sınıfının API referansı, "Ad Services Uzantıları 4'e eklendi" durumunu belirtiyor. AdServices API'leri içeren SDK uzantılarını doğrulamak için aşağıdaki koşullu denetimleri 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ı'na ve gizliliği korumaya yönelik API'lere erişim, görünür bir Etkinliği olan veya RunningAppProcessInfo IMPORTANCE_FOREGROUND bulunan uygulamalarla sınırlıdır.