Adapter für sichere Signale erstellen

Plattform auswählen: Android iOS

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

Hinweis

Prüfen Sie, ob Sie das IMA SDK für Android v3.29.0 oder höher verwenden.

Schnittstelle für sichere Signaladapter erstellen

Erstellen Sie Klassen, die die Schnittstelle implementieren, um sichere Signale zu erfassen und bereitzustellen:

Hinweis: Das IMA SDK lädt Ihre Adapterklasse mithilfe der Reflektion. Fügen Sie Ihrer Klasse

die Android-Annotation @Keep hinzu, um zu verhindern, dass minimierter Code zur Build-Zeit entfernt wird.

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 es die Initialisierungsmethode des Adapters aufruft. Implementieren Sie diese Methode, um Verschlüsselungsabhängigkeiten zu starten, Caches einzurichten oder Signale vorzuberechnen, 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 initiiert wird, ruft das IMA SDK asynchron eine Methode zum Erfassen von Signalen auf. Diese Methoden zum Erfassen von Signalen enthalten eine Callback-Funktion, um die verschlüsselten Signale zu übergeben oder einen Fehler zu melden.

Hinweis: Innerhalb von 500 Millisekunden müssen Sie die Signalerfassung und ‑verschlüsselung abschließen und das verschlüsselte Signal an die Callback-Funktion übergeben. Nach 500 Millisekunden verwirft das IMA SDK alle erfassten Signale.

In den folgenden Beispielen werden die sicheren Signale über die Callback-Funktion 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

Um mit Nutzern zu kommunizieren, die Ihre Adapterklasse verwenden, melden Sie alle Fehler während der Signalerfassung und übergeben Sie sie an den Callback des Signalerfassers. So können Sie Probleme beheben, die bei der Einbindung Ihres Adapters in Anwendungen auftreten.

Folgende Fehler können auftreten:

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

Adapterversion angeben

Prüfen Sie, ob Sie in Ihrem Workflow die Version des Adapters angeben. Das IMA SDK fügt die 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 ermitteln, 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 SDK funktioniert. Damit der Adapter mit mehreren Versionen funktioniert, müssen Sie die Laufzeitversion des SDK zurückgeben. In jeder Anzeigenanfrage fügt das IMA SDK die Laufzeitversion zusammen mit der Adapterversion ein.

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 oder bei Google registrieren. Das IMA SDK initialisiert nur die Adapter, die Sie bei Google registrieren.

Adapter validieren

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 auf App-Ebene Ihres Moduls 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 wie Ihren Adapter und das SDK.

Signale überprüfen

Wenn Sie prüfen möchten, ob Ihr Adapter Signale sendet, verwenden Sie einen Netzwerkproxy, um den Traffic von Anzeigenanfragen Ihrer Anwendung zu überwachen. Wenn alles geklappt hat, sehen Sie die Signale in jeder Anzeigenanfrage.

Vollständige Beispiele ansehen

In diesem Abschnitt finden Sie das vollständige Beispiel für alle Schritte.

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