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