Wykonaj podane niżej instrukcje, aby zadeklarować uprawnienia dotyczące interfejsu API i skonfigurować dostęp pakietu SDK do zasobów zarządzanych przez docelowy interfejs API.
Deklarowanie uprawnień specyficznych dla interfejsu AdServices API
Dostęp do każdego PPAPI wymaga uprawnienia normal
usług reklamowych. W pliku manifestu zadeklaruj odpowiednie uprawnienia dostępu odpowiadające interfejsom API wymaganym w aplikacji lub pakiecie SDK.
Interfejs Attribution Reporting API:
<uses-permission android:name="android.permission.ACCESS_ADSERVICES_ATTRIBUTION" />
Attribution Reporting API (z raportami debugowania):
<uses-permission android:name="android.permission.ACCESS_ADSERVICES_ATTRIBUTION" />
<uses-permission android:name="android.permission.ACCESS_ADSERVICES_AD_ID" />
Protected Audience API / niestandardowy interfejs API:
<uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />
Topics API:
<uses-permission android:name="android.permission.ACCESS_ADSERVICES_TOPICS" />
Opcjonalnie, jeśli chcesz otrzymywać raporty debugowania za pomocą interfejsu Attribution Reporting API, użyj uprawnienia AD_ID:
<uses-permission android:name="android.permission.ACCESS_ADSERVICES_AD_ID" />
Jeśli Twój projekt jest zależny od modułów lub pakietów SDK, może już zadeklarować wymagane uprawnienia usług reklamowych w swoich plikach manifestu. Domyślnie kompilacja Gradle scala wszystkie pliki manifestu w jeden plik manifestu w pakiecie z Twoją aplikacją. Aby sprawdzić, czy używasz właściwych uprawnień, skorzystaj z widoku pliku manifestu scalonego.
Jeśli chcesz zapobiec scalaniu jakichkolwiek uprawnień z aplikacją za pomocą zależności takich jak pakiety SDK, dodaj znacznik węzła remove
przy konkretnych uprawnieniach. Poniższy przykład pokazuje, jak zapobiec scalaniu uprawnień Topics.
<uses-permission android:name="android.permission.ACCESS_ADSERVICES_TOPICS"
tools:node="remove" />
Skonfiguruj usługi reklamowe związane z interfejsem API
Podobnie jak w przypadku uprawnień dostępu do PPAPI każdy interfejs API ma swój wpis w konfiguracji usług reklamowych. Ta konfiguracja zapewnia szczegółową kontrolę dostępu do zasobów zarządzanych przez interfejsy API w Twojej aplikacji lub osadzonym pakiecie SDK. W pliku manifestu określ właściwość adservicesConfig
w ten sposób:
<application ...>
...
<property android:name="android.adservices.AD_SERVICES_CONFIG"
android:resource="@xml/ad_services_config" />
...
</application>
Określ zasób XML usług reklamowych, do którego odwołuje się plik manifestu, np. res/xml/ad_services_config.xml
. W przypadku każdego interfejsu API chroniącego prywatność, który ma zastosowanie do Twojej aplikacji (lub umieszczonego pakietu SDK), ustaw atrybut allowAllToAccess
na true
, aby przyznać dostęp wszystkim elementom wywołującym.
Możesz też użyć atrybutu allowAdPartnersToAccess
, aby przyznać wszystkim technikom reklamowym szczegółowe uprawnienia dostępu do interfejsu API. Musisz podać listę identyfikatorów kont do rejestracji deweloperów uzyskanych w ramach rejestracji. Jeśli atrybut allowAllToAccess
ma wartość true
, ten atrybut ma pierwszeństwo przed identyfikatorami kont rejestracji określonymi w atrybucie allowAdPartnersToAccess
.
Platformy AdTech powinny się też upewnić, że ich klienty aplikacji prawidłowo przyznają dostęp do wymaganych interfejsów API chroniących prywatność w konfiguracji usług reklamowych.
Z przykładu poniżej dowiesz się, jak określić szeroki dostęp, aby zezwolić każdemu identyfikatorowi konta do rejestracji na dostęp do wszystkich interfejsów API chroniących prywatność:
<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>
Z przykładu poniżej dowiesz się, jak określić szczegółową kontrolę dostępu do każdego interfejsu API chroniącego prywatność w przypadku określonych identyfikatorów kont do rejestracji:
<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>
Deklarowanie zależności biblioteki Jetpack
Użyj biblioteki Jetpack ads-adservices w wersji 1.0.0-beta01 lub nowszej, aby przeprowadzić integrację z interfejsami API Piaskownicy prywatności chroniącymi prywatność. Za pomocą tej biblioteki możesz wyodrębnić informacje o aplikacji od szczegółów na poziomie platformy i uprościć integrację z interfejsami API chroniącymi prywatność.
- Dodaj do projektu repozytorium Maven.
- Zadeklaruj zależności biblioteki ads-adservices Jetpack w pliku
build.gradle
aplikacji lub modułu. - Używaj interfejsów API z pakietów
androidx.privacysandbox.ads.adservices.*
. - Biblioteka ads-adservices Jetpack ma wbudowaną obsługę sterownika Kotlin. Zarządzanie zakresami koordynacji może być konieczne w przypadku zastosowania w projekcie odpowiednich zależności związanych z cyklem życia.
Sprawdzanie dostępności wersji rozszerzeń usług reklamowych
Jeśli do integracji z interfejsami API chroniącymi prywatność używasz biblioteki Jetpack w usługach reklamowych, biblioteka sprawdza dostępność żądanych interfejsów API w funkcji obtain()
. Jeśli żądany interfejs API nie jest dostępny na urządzeniu, funkcja zwraca wartość null. Poniższy przykład pokazuje, jak zainicjować TopicsManager
dla interfejsu Topics API. Działa ona podobnie w przypadku
dostępu do innych interfejsów API chroniących prywatność.
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);
Jeśli używasz interfejsów AdServices API bezpośrednio w pakiecie SDK rozszerzeń, sprawdź wersję AdServices Extensions, która zawiera interfejsy AdServices API, których chcesz używać.
W dokumentacji API możesz sprawdzić, w której wersji został wprowadzony dany interfejs AdServices API. Na przykład dokumentacja interfejsu API klasy TopicsManager
wskazuje, że jest to „Dodano w rozszerzeniach usług reklamowych 4”. Aby zweryfikować rozszerzenia pakietu SDK, które zawierają interfejsy AdServices API, użyj podanych niżej testów warunkowych.
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.
...
}
Ograniczenie dostępu na pierwszym planie
Aby zapewnić przejrzystość, dostęp do środowiska wykonawczego pakietu SDK i interfejsów API chroniących prywatność jest ograniczony do aplikacji z widoczną aktywnością lub o wartości RunningAppProcessInfo
o wartości IMPORTANCE_FOREGROUND
.