Tworzenie adaptera bezpiecznych sygnałów

Ważne: sygnały bezpieczeństwa są dostępne w wersji beta. Ten dokument jest przeznaczony tylko dla wybranych partnerów. Nie rozpowszechniaj tego dokumentu bez zgody Google.

Bezpieczne sygnały to zakodowane dane, które urządzenie klienta zbiera i udostępnia wybranym licytującym. Na tej stronie znajdziesz wskazówki dotyczące zbierania i wysyłania bezpiecznych sygnałów do Google Ad Managera za pomocą pakietu Interactive Media Ads SDK.

Zanim zaczniesz

Zanim przejdziesz dalej, upewnij się, że masz pakiet IMA SDK na Androida w wersji 3.29.0 lub nowszej.

Tworzenie interfejsu adaptera bezpiecznego sygnału

Aby zbierać i przekazywać bezpieczne sygnały, utwórz klasy, które implementują interfejs:

Uwaga: pakiet IMA SDK wczytuje klasę adaptera przy użyciu odbicia. Aby zapobiec usunięciu zminifikowanego kodu w czasie kompilacji, dodaj adnotację Androida @Keep do klasy.

package companydomain.path.to.securesignals;
import android.content.Context;
import androidx.annotation.Keep;
import com.google.ads.interactivemedia.v3.api.signals.SecureSignalsAdapter;

/**
 * An example implementation of Secure Signals adapter.
 */
@Keep
public final class MySecureSignalsAdapter implements SecureSignalsAdapter {
  /**
   * Default constructor with no arguments for IMA SDK to instantiate this class.
   */
  public MySecureSignalsAdapter() {
  }
}

Inicjowanie adaptera

Pakiet IMA SDK inicjuje każdy adapter tylko raz, wywołując metodę inicjowania tego adaptera. Za pomocą tej metody można rozpocząć tworzenie zależności szyfrowania, konfigurować pamięci podręczne lub wstępnie obliczać sygnały, które pozostają takie same we wszystkich wywołaniach funkcji zbierania sygnałów.

Ten przykład inicjuje adapter:

  ...
  /**
   * Initialize your SDK and any dependencies.
   * IMA SDK calls this function exactly once before signal collection.
   *
   * @param context  The activity context that creates an ads loader.
   * @param callback A callback function to pass initialization results to IMA SDK.
   */
  @Override
  public void initialize(Context context, SecureSignalsInitializeCallback callback) {
    // Initialize your SDK and any dependencies.
    ...

    // Notify IMA SDK of initialization success.
    callback.onSuccess();

    // If signal collection fails, call callback.onFailure();
    // callback.onFailure(new Exception("Signal collection failed."));
  }
  ...

Zbieranie sygnałów

Przed rozpoczęciem żądania reklamy pakiet IMA SDK asynchronicznie wywołuje metodę collect signals. Te metody zbierania sygnałów zawierają funkcję wywołania zwrotnego, która przekazuje zaszyfrowane sygnały lub zgłasza błąd.

Uwaga: w ciągu 500 milisekund musisz przeprowadzić zbieranie i szyfrowanie sygnału oraz przekazać zaszyfrowany sygnał do funkcji wywołania zwrotnego. Po 500 milisekundach pakiet IMA SDK odrzuca wszystkie sygnały.

W tych przykładach bezpieczne sygnały są zbierane za pomocą funkcji wywołania zwrotnego:

  ...
  /**
   * Invokes your SDK to collect, encrypt and pass the signal collection results to IMA SDK.
   * IMA SDK calls this function before each ad request.
   *
   * @param context  The activity context that creates an ads loader.
   * @param callback A callback function to pass signal collection results to IMA SDK.
   */
  @Override
  public void collectSignals(Context context, SecureSignalsCollectSignalsCallback callback) {

    try {
      // Collect and encrypt the signals.
      String signals = ...;

      // Pass the encrypted signals to IMA SDK.
      callback.onSuccess(signals);
    } catch (Exception e) {
      // Pass signal collection failures to IMA SDK.
      callback.onFailure(e);
    }
  }
  ...

Zgłaszanie błędów

Aby komunikować się z użytkownikami, którzy korzystają z Twojej klasy adaptera, zgłaszaj wszystkie błędy podczas zbierania sygnałów i przekazuj je do funkcji wywołania zwrotnego zbieracza sygnałów. Ten proces umożliwia rozwiązywanie problemów występujących podczas integracji adaptera z aplikacjami.

Mogą pojawić się takie błędy:

• W aplikacji nie znaleziono Twojego pakietu SDK ani zależności.
• Pakiet SDK lub jego zależność nie ma wymaganych uprawnień ani zgody użytkownika.

Określanie wersji adaptera

W przepływie pracy pamiętaj, aby określić wersję adaptera. Pakiet IMA SDK uwzględnia wersję adaptera w każdym żądaniu reklamy i przekazuje ją wraz z bezpiecznymi sygnałami w żądaniu stawki.

W pytaniu o stawkę, w zależności od wersji adaptera, możesz określić szczegóły szyfrowania, kodowania i formatowania używane przez adapter do tworzenia bezpiecznych sygnałów.

W tym przykładzie określono wersję adaptera:

  ...
  /**
   * Specifies this adapter's version.
   */
  private static final VersionInfo AdapterVersion = new VersionInfo(1, 0, 1);
  ...
  /**
   * @return The version of this adapter.
   *         IMA SDK calls this function before each ad request.
   */
  @Override
  public VersionInfo getVersion() {
    return AdapterVersion;
  }
  ...

zwracać wersję pakietu SDK w czasie wykonywania;

Możesz zaprojektować adapter tak, aby działał z różnymi wersjami Twojego pakietu SDK. Aby adapter działał z wieloma wersjami, upewnij się, że zwracana jest wersja środowiska wykonawczego SDK. W każdym żądaniu reklamy pakiet IMA SDK zawiera wersję środowiska wykonawczego z wersją adaptera.

W tych przykładach żądana i zwracana jest wersja środowiska wykonawczego pakietu SDK:

  ...
  /**
   * @return The version of your SDK that this adapter is depending on.
   *         IMA SDK calls this function before each ad request.
   */
  @Override
  public VersionInfo getSDKVersion() {
    // Request the version from your SDK and convert to an IMAVersion.
    int[] mySDKVersion = ...;

    return new VersionInfo(mySDKVersion[0], mySDKVersion[1], mySDKVersion[2]);
  }
  ...

Rejestrowanie adaptera w Google

Aby Google mogło autoryzować adapter do zbierania sygnałów, musisz zarejestrować nazwę pakietu Androida lub zarejestrować się w Google. Pakiet IMA SDK inicjuje tylko adaptery zarejestrowane w Google.

Sprawdzanie adaptera

Aby sprawdzić adapter, zapoznaj się z tymi sekcjami:

Konfigurowanie aplikacji testowej

Zanim sprawdzisz poprawność adaptera, skonfiguruj aplikację testową. Wykonaj te czynności:

1. Dodaj zależności dla pakietu IMA SDK do pliku Gradle na poziomie aplikacji modułu, np. app/build.gradle:

   dependencies {
     implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.29.0'
   }
   

2. Dodaj zależności kompilacji, takie jak adapter i pakiet SDK.

Weryfikowanie sygnałów

Aby sprawdzić, czy adapter wysyła sygnały, użyj serwera proxy sieci, aby śledzić ruch z zapytań o reklamy w Twojej aplikacji. Jeśli się powiedzie, sygnały będą widoczne w każdej prośbie o reklamę.

Zapoznaj się z pełnymi przykładami

Ta sekcja zawiera przykładowe wykonanie wszystkich czynności i jest dostępna do wglądu.

package companydomain.path.to.securesignals;
import android.content.Context;
import androidx.annotation.Keep;
import com.google.ads.interactivemedia.v3.api.VersionInfo;
import com.google.ads.interactivemedia.v3.api.signals.SecureSignalsAdapter;
import com.google.ads.interactivemedia.v3.api.signals.SecureSignalsCollectSignalsCallback;
import com.google.ads.interactivemedia.v3.api.signals.SecureSignalsInitializeCallback;

/**
 * An example implementation of Secure Signals adapter.
 */
@Keep
public final class MySecureSignalsAdapter implements SecureSignalsAdapter {
  /**
   * Specifies this adapter's version.
   */
  private static final VersionInfo AdapterVersion = new VersionInfo(1, 0, 1);
  /**
   * Default constructor with no arguments for IMA SDK to instantiate this class.
   */
  public MySecureSignalsAdapter() {
  }
  /**
   * Initialize your SDK and any dependencies.
   * IMA SDK calls this function exactly once before signal collection.
   *
   * @param context  The activity context that creates an ads loader.
   * @param callback A callback function to pass initialization results to IMA SDK.
   */
  @Override
  public void initialize(Context context, SecureSignalsInitializeCallback callback) {
    try {
      // Initialize your SDK and any dependencies.
      ...

      // Notify IMA SDK of initialization success.
      callback.onSuccess();
    } catch (Exception e) {
      // Pass initialization failures to IMA SDK.
      callback.onFailure(e);
    }
  }
  /**
   * Invokes your SDK to collect, encrypt and send the signal collection results to IMA SDK.
   * IMA SDK calls this function before each ad request.
   *
   * @param context  The activity context that creates an ads loader.
   * @param callback A callback function to pass signal collection results to IMA SDK.
   */
  @Override
  public void collectSignals(Context context, SecureSignalsCollectSignalsCallback callback) {
    try {
      // Collect and encrypt the signals.
      String signals = ...;

      // Pass the encrypted signals to IMA SDK.
      callback.onSuccess(signals);
    } catch (Exception e) {
      // Pass signal collection failures to IMA SDK.
      callback.onFailure(e);
    }
  }
  /**
   * @return The version of this adapter.
   * IMA SDK calls this function before each ad request.
   */
  @Override
  public VersionInfo getVersion() {
    return AdapterVersion;
  }
  /**
   * @return The version of your SDK that this adapter is depending on.
   * IMA SDK calls this function before each ad request.
   */
  @Override
  public VersionInfo getSDKVersion() {
    // Request the version from your SDK and convert to an IMAVersion.
    int[] mySDKVersion = ...;
    return new VersionInfo(mySDKVersion[0], mySDKVersion[1], mySDKVersion[2]);
  }
}