Tworzenie adaptera bezpiecznych sygnałów

Ważne: bezpieczne sygnały są w wersji beta. Ten dokument jest przeznaczony do wyboru tylko dla partnerów. Nie rozpowszechniaj tego dokumentu bez zgody Google.

Bezpieczne sygnały to zakodowane dane, które urządzenie klienckie zbiera i udostępnia wybranym licytujących. Na tej stronie dowiesz się, jak zbierać i wysyłać bezpieczne sygnały do Google Ad Manager z pakietem SDK Interactive Media Ads (IMA).

Zanim zaczniesz

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

Tworzenie interfejsu bezpiecznego adaptera sygnału

Aby zbierać i udostępniać bezpieczne sygnały, utwórz klasy, które stosują interfejs:

Uwaga: pakiet IMA SDK wczytuje klasę adaptera za pomocą odbicia lustrzanego. 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

IMA SDK inicjuje każdy adapter raz, wywołując metodę inicjowania. lub przejściówki. 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 zainicjowaniem żądania reklamy pakiet IMA SDK wywołuje metodę zbierania sygnałów. asynchronicznie. Te metody zbierania sygnałów zawierają funkcję wywołania zwrotnego do przekazywania zaszyfrowanych sygnałów lub zgłaszanie błędu.

Uwaga: zbieranie sygnałów należy zakończyć w ciągu 500 milisekund. i 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 klasy adaptera, zgłoś wszystkie błędy podczas zbierania sygnałów i przekazywanie ich do wywołania zwrotnego odbierającego sygnały. Ten proces umożliwia rozwiązywanie problemów występujących podczas integracji adaptera z aplikacjami.

Błędy, które mogą się pojawić:

• Pakiet SDK lub zależność nie został znaleziony w aplikacji.
• Pakiet SDK lub jego zależność nie ma wymaganych uprawnień ani zgody użytkownika.

Podaj wersję adaptera

Pamiętaj, aby w swoim przepływie pracy określić wersję adaptera. Pakiet IMA SDK uwzględnia wersję adaptera w każdym żądaniu reklamy i przekazuje ją za pomocą bezpiecznego parametru w pytaniu o stawkę.

W pytaniu o stawkę możesz określić wersję adaptera na podstawie wersji adaptera dotyczące szyfrowania, kodowania i formatowania, które są używane przez adapter do tworzenia i bezpiecznych sygnałów.

W poniższym 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 zwracasz wersję środowiska wykonawczego pakietu SDK. W każdym żądaniu reklamy pakiet IMA SDK zawiera wersję runtime 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, wykonaj te czynności:

Konfigurowanie aplikacji testowej

Zanim zweryfikujesz adapter, skonfiguruj aplikację testową. Wypełnij następujące kroki:

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

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

2. Dodaj zależności kompilacji, na przykład adaptera i pakietu SDK.

Sprawdzanie 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]);
  }
}