Wykonaj poniższe instrukcje, aby zadeklarować uprawnienia interfejsu API i skonfigurować dostęp pakietu SDK do zasobów zarządzanych przez docelowy interfejs API.
Deklarowanie uprawnień do interfejsu AdServices API
Dostęp do każdego interfejsu PPAPI wymaga uprawnienia normal dla 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 / Custom Audience API:
<uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />
Interfejs Topics API:
<uses-permission android:name="android.permission.ACCESS_ADSERVICES_TOPICS" />
Opcjonalnie, aby otrzymywać raporty debugowania za pomocą interfejsu Attribution Reporting API, dodaj uprawnienie AD_ID:
<uses-permission android:name="android.permission.ACCESS_ADSERVICES_AD_ID" />
Jeśli Twój projekt jest uzależniony od modułów lub pakietów SDK, może już w plikach manifestu zadeklarować wymagane uprawnienia dotyczące usług reklamowych. Domyślnie kompilacja Gradle scala wszystkie pliki manifestu w jeden plik manifestu spakowany z aplikacją. Użyj widoku pliku manifestu scalonego, aby sprawdzić, czy są używane odpowiednie uprawnienia.
Jeśli nie chcesz scalać uprawnień z aplikacją przez zależności takie jak pakiety SDK, dla poszczególnych uprawnień dołącz znacznik węzła remove. Poniższy przykład pokazuje, jak zapobiec łączeniu uprawnienia Topics.
<uses-permission android:name="android.permission.ACCESS_ADSERVICES_TOPICS"
tools:node="remove" />
Konfigurowanie usług reklamowych związanych z interfejsem API
Podobnie jak uprawnienia dostępu PPAPI, każdy interfejs API ma odpowiedni wpis w konfiguracji usług reklamowych. Ta konfiguracja zapewnia szczegółową kontrolę dostępu do zasobów zarządzanych przez interfejsy API w aplikacji lub osadzony pakiet SDK.
W pliku manifestu określ właściwość adservicesConfig zgodnie z poniższym przykładem:
<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 obiektom wywołującym.
Możesz też użyć atrybutu allowAdPartnersToAccess, aby przyznać szczegółowy dostęp do poszczególnych technologii reklamowych przez interfejs API. Musisz też podać listę identyfikatorów kont rejestracji dewelopera uzyskanych podczas rejestracji. Jeśli atrybut allowAllToAccess ma wartość true, ten atrybut ma pierwszeństwo przed wszystkimi identyfikatorami kont rejestracji określonymi w atrybucie allowAdPartnersToAccess.
Platformy technologii reklamowych powinny też zadbać o to, aby klienci aplikacji prawidłowo przyznawali w konfiguracji usług reklamowych wymagane interfejsy API chroniące prywatność.
Ten przykład pokazuje, jak określić szeroki dostęp, aby umożliwić dowolnemu identyfikatorowi konta rejestracji 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 tego przykładu dowiesz się, jak określić szczegółowy dostęp do każdego interfejsu API chroniącego prywatność w przypadku określonych identyfikatorów kont 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
Skorzystaj z biblioteki Jetpack ads-adservices w wersji 1.0.0-beta01 lub nowszej, aby przeprowadzić integrację z chroniącymi prywatność interfejsami API Piaskownicy prywatności. Za pomocą tej biblioteki możesz wyodrębnić swoją aplikację ze szczegółów na poziomie platformy i uprościć integrację z interfejsami API chroniącymi prywatność.
- Dodaj repozytorium Maven do swojego projektu.
- W pliku
build.gradleaplikacji lub modułu zadeklaruj zależności od biblioteki Jetpack z reklamami ads-adservices. - Użyj interfejsów API z pakietów
androidx.privacysandbox.ads.adservices.*. - Biblioteka Jetpack z usługami ads-adservices ma wbudowaną obsługę współprogramu Kotlin. Aby zarządzać zakresami współrzędnych, może być konieczne włączenie odpowiednich zależności uwzględniających cykl życia odpowiednich w projekcie.
Sprawdzanie dostępności wersji rozszerzeń usług reklamowych
Jeśli do integracji z interfejsami API chroniącymi prywatność używasz biblioteki Jetpack z usługami reklamowymi, 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 podobnie przy dostępie
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 Extension, sprawdź wersję rozszerzeń AdServices, która zawiera interfejsy AdServices API, których chcesz używać.
W dokumentacji interfejsu API możesz sprawdzić, w jakiej wersji został wprowadzony dany interfejs AdServices API. Na przykład dokumentacja interfejsu API klasy TopicsManager wskazuje, że ma ona wartość „Dodano w rozszerzeniach usług reklamowych 4”. Wykonaj poniższe kontrole warunkowe, aby zweryfikować rozszerzenia pakietu SDK, które zawierają interfejsy 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.
...
}
Ograniczenie dostępu na pierwszym planie
Aby zapewnić przejrzystość, dostęp do środowiska wykonawczego SDK i interfejsów API chroniących prywatność jest ograniczony do aplikacji, w których widać aktywność, lub do RunningAppProcessInfo o wartości IMPORTANCE_FOREGROUND.