Adapter für sichere Signale erstellen

Sichere Signale sind codierte Daten, die von einem Clientgerät erhoben und an ausgewählte Bieter weitergegeben werden. Auf dieser Seite erfahren Sie, wie Sie mit dem Interactive Media Ads SDK (IMA SDK) sichere Signale erfassen und an Google Ad Manager senden.

Hinweis

Bevor du fortfährst, musst du das IMA SDK für Android Version 3.29.0 oder höher installiert haben.

Schnittstelle für sicheren Signaladapter erstellen

Wenn Sie sichere Signale erfassen und bereitstellen möchten, erstellen Sie Klassen, die die Schnittstelle implementieren:

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() {
  }
}

Adapter initialisieren

Das IMA SDK initialisiert jeden Adapter einmal, indem die Initialisierungsmethode des Adapters aufgerufen wird. Implementieren Sie diese Methode, um Verschlüsselungsabhängigkeiten zu starten, Caches einzurichten oder Signale vorab zu berechnen, die in allen Aufrufen zur Signalerfassung gleich bleiben.

Im folgenden Beispiel wird der Adapter initialisiert:

  ...
  /**
   * 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."));
  }
  ...

Signalerfassung

Bevor eine Anzeigenanfrage gestartet wird, ruft das IMA SDK asynchron eine Methode zum Erfassen von Signalen auf. Diese Methoden zum Erfassen von Signalen enthalten eine Rückruffunktion, um die verschlüsselten Signale weiterzuleiten oder einen Fehler zu melden.

In den folgenden Beispielen werden die sicheren Signale über die Rückruffunktion erfasst:

  ...
  /**
   * 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);
    }
  }
  ...

Berichtsfehler

Wenn Sie mit Nutzern kommunizieren möchten, die Ihre Adapterklasse verwenden, melden Sie alle Fehler während der Signalerfassung und übergeben Sie sie an den Rückruf des Signalempfängers. Mit diesem Verfahren können Probleme behoben werden, die bei der Integration des Adapters in Anwendungen auftreten.

Mögliche Fehler:

  • Ihr SDK oder eine Abhängigkeit wird in der Anwendung nicht gefunden.
  • Ihr SDK oder eine Abhängigkeit hat nicht die erforderliche Berechtigung oder Nutzereinwilligung, um zu funktionieren.

Adapterversion angeben

Geben Sie in Ihrem Workflow die Version des Adapters an. Das IMA SDK fügt deine Adapterversion in jede Anzeigenanfrage ein und übergibt sie zusammen mit den sicheren Signalen in einer Gebotsanfrage.

In der Gebotsanfrage können Sie anhand der Adapterversion die Details zur Verschlüsselung, Codierung und Formatierung angeben, die der Adapter zum Erstellen der sicheren Signale verwendet.

Im folgenden Beispiel wird die Adapterversion angegeben:

  ...
  /**
   * 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;
  }
  ...

SDK-Laufzeitversion zurückgeben

Sie können Ihren Adapter so gestalten, dass er mit mehreren Versionen Ihres SDKs funktioniert. Damit der Adapter mit mehreren Versionen funktioniert, muss die Laufzeitversion des SDK zurückgegeben werden. In jeder Anzeigenanfrage enthält das IMA SDK die Laufzeitversion mit der Adapterversion.

In den folgenden Beispielen wird die SDK-Laufzeitversion angefordert und zurückgegeben:

  ...
  /**
   * @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]);
  }
  ...

Adapter bei Google registrieren

Damit Google den Adapter für die Signalerfassung autorisieren kann, müssen Sie den Android-Paketnamen bei Google registrieren. Das IMA SDK initialisiert nur die Adapter, die du bei Google registrierst.

Adapter prüfen

Führen Sie die folgenden Schritte aus, um den Adapter zu validieren:

Testanwendung konfigurieren

Konfigurieren Sie die Testanwendung, bevor Sie den Adapter validieren. Gehen Sie folgendermaßen vor:

  1. Fügen Sie der Gradle-Datei Ihres Moduls auf App-Ebene die Abhängigkeiten für das IMA SDK hinzu, z. B. app/build.gradle:

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

  2. Fügen Sie Build-Abhängigkeiten hinzu, z. B. Ihren Adapter und Ihr SDK.

Signale prüfen

Um zu prüfen, ob Ihr Adapter Signale sendet, verwenden Sie einen Netzwerkproxy, um den Traffic für Anzeigenanfragen Ihrer Anwendung zu überwachen. Wenn die Einrichtung erfolgreich war, werden die Signale in jeder Anzeigenanfrage angezeigt.

Vollständige Beispiele ansehen

In diesem Abschnitt finden Sie ein vollständiges Beispiel für alle Schritte, das Sie als Referenz verwenden können.

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