Konfigurowanie AdServices na Androida

Wykonaj instrukcje poniżej, aby zadeklarować uprawnienia do interfejsu API i skonfigurować Dostęp pakietu SDK do zasobów zarządzanych przez docelowy interfejs API.

Uwaga: dostępna jest nowa biblioteka Jetpack, która umożliwia integrację z zasadami ochrony prywatności. Interfejsy API do ochrony prywatności w Piaskownicy prywatności (Topics, Protected Audience i Raporty atrybucji. Tej biblioteki możesz używać jako dodatku na interfejs API Piaskownicy prywatności dostępny w pakiecie SDK rozszerzeń.

Deklarowanie uprawnień do interfejsu AdServices API

Dostęp do każdego interfejsu PPAPI wymaga uprawnienia normal dla usług reklamowych. W w pliku manifestu, zadeklaruj odpowiednie uprawnienia dostępu odpowiadające interfejsom API. wymaganych 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 w celu otrzymywania raportów o debugowaniu za pomocą funkcji Attribution Reporting API, uwzględnij uprawnienie AD_ID:

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

Jeśli Twój projekt wymaga zależności od modułów lub pakietów SDK, mogą one już zadeklarować wymagane uprawnienia dostępu do usług reklamowych w plikach manifestu. Domyślnie atrybut Kompilacja Gradle scala wszystkie pliki manifestu w jeden plik manifestu, który do aplikacji. Skorzystaj z widoku pliku manifestu scalonego, aby sprawdzić, czy pole używane są odpowiednie uprawnienia.

Jeśli nie chcesz, by którekolwiek uprawnienia zostały scalone z Twoją aplikacją za pomocą zależności, takich jak pakiety SDK, uwzględnij znacznik węzła remove dla: z konkretnymi uprawnieniami. Poniższy przykład pokazuje, jak zapobiegać przez połączenie uprawnień Topics.

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

Konfigurowanie usług reklamowych związanych z interfejsem API

Podobnie jak w przypadku uprawnień 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; umieszczonego pakietu SDK.

Uwaga: konfigurowanie konkretnych usług reklamowych jest opcjonalne. i wymagane tylko wtedy, gdy deweloper chce zmienić lub ograniczyć dostęp API, ponieważ domyślnie każdy dostęp jest przyznawany.

W pliku manifestu określ właściwość adservicesConfig zgodnie z wyświetlaną ilustracją w następujących przykład:

<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 swojej aplikacji (lub umieszczonego pakietu SDK), ustaw atrybut allowAllToAccess na true na przyznać dostęp wszystkim wywołującym.

Możesz też użyć atrybutu allowAdPartnersToAccess, aby przyznać szczegółowe informacje o dostępie do poszczególnych technologii reklamowych. Musisz podać listę identyfikatory kont rejestracji deweloperów uzyskanych przy rejestracji. Jeśli Atrybut allowAllToAccess ma wartość true. Ten atrybut ma pierwszeństwo nad wszelkimi identyfikatorami kont rejestracji określonymi w allowAdPartnersToAccess .

Uwaga: aby uzyskać dostęp do interfejsów API Piaskownicy prywatności w najnowszym rozszerzeniu pakietu SDK AdServices oraz w wersji przedpremierowej dla programistów, musisz dokończyć procesu rejestracji.

Platformy technologii reklamowych powinny też dbać o to, aby klienci, którzy korzystają z ich aplikacji, prawidłowo dostęp do wymaganych interfejsów API chroniących prywatność w konfiguracji usług reklamowych.

Uwaga: ze względu na znany błąd ustaw allowAllToAccess na true podczas i testować lokalnie.

Ten przykład pokazuje, jak określić szeroki dostęp, aby umożliwić dowolną rejestrację dostęp za pomocą identyfikatora konta 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>

Poniższy przykład pokazuje, jak określić szczegółowy dostęp do każdego z nich interfejs API chroniący prywatność dla 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>

Uwaga: jeśli rejestracja w interfejsie Topics API lub Protected Audience API jest wyłączona używając poleceń adb, aplikacja może uzyskać dostęp do powiązanych interfejsów API niezależnie ustawienia dostępu określone w ad-services-config.

Deklarowanie zależności biblioteki Jetpack

Aby przeprowadzić integrację, skorzystaj z biblioteki ads-adservices Jetpack w wersji 1.0.0-beta01 lub nowszej. przy użyciu chroniących prywatność interfejsów API Piaskownicy prywatności. Za pomocą tej biblioteki możesz: wyodrębnić aplikację ze szczegółów na poziomie platformy i uprościć integrację interfejsów API chroniących prywatność.

1. Dodaj repozytorium Maven do swojego projektu.
2. Zadeklaruj zależności biblioteki ads-adservices Jetpack w build.gradle aplikacji lub modułu.
3. Użyj interfejsów API z pakietów androidx.privacysandbox.ads.adservices.*.
4. Biblioteka Jetpack z usługami ads-adservices ma wbudowaną współrzędną Kotlin . Konieczne może być uwzględnienie odpowiednich uwzględniających cykl życia zależności odpowiednie do Twojego projektu do zarządzania zakresami współprac.

Sprawdzanie dostępności wersji rozszerzeń usług reklamowych

Jeśli używasz biblioteki Jetpack do integracji z reklamami interfejsów API chroniących prywatność, biblioteka sprawdza dostępność żądanych interfejsów API w funkcji obtain(). Funkcja zwraca wartość null, jeśli żądany interfejs API nie jest dostępny na urządzeniu. Poniższy przykład pokazuje, jak zainicjować interfejs TopicsManager dla interfejsu Topics API. Analogicznie działa dostęp 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, zapoznaj się z Wersja rozszerzeń AdServices zawierająca interfejsy AdServices API, których chcesz używać. W dokumentacji interfejsu API możesz wskazać wersję konkretnej usługi AdServices Wprowadzono interfejs API. Na przykład dokumentacja interfejsu API klasy TopicsManager wskazuje, że ma stan „Dodano w rozszerzeniach usług reklamowych 4”. Użyj następujących testy warunkowe, które pozwalają 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ść, przejdź do środowiska wykonawczego SDK i interfejsów API chroniących prywatność jest ograniczona do aplikacji, w których widać aktywność, lub RunningAppProcessInfo z IMPORTANCE_FOREGROUND.