Créer un adaptateur de signaux sécurisés

Important :Les signaux sécurisés sont actuellement disponibles en version bêta. Ce document est destiné à certains partenaires uniquement. Ne distribuez pas ce document sans l'autorisation de Google.

Les signaux sécurisés sont des données encodées qu'un appareil client collecte et partage avec certains enchérisseurs. Cette page explique comment collecter et envoyer des signaux sécurisés à Google Ad Manager à l'aide du SDK IMA (Interactive Media Ads).

Avant de commencer

Avant de continuer, assurez-vous de disposer du SDK IMA pour Android 3.29.0 ou version ultérieure.

Créer l'interface de l'adaptateur de signal sécurisé

Pour collecter et fournir des signaux sécurisés, créez des classes qui implémentent l'interface:

Remarque :Le SDK IMA charge votre classe d'adaptateur à l'aide de la réflexion. Pour éviter la suppression du code minifié au moment de la compilation, ajoutez l'annotation Android @Keep à votre classe.

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

Initialiser l'adaptateur

Le SDK IMA initialise chaque adaptateur une fois en appelant la méthode d'initialisation de l'adaptateur. Implémentez cette méthode pour commencer les dépendances de chiffrement, configurer des caches ou précalculer les signaux qui restent les mêmes dans tous les appels de collecte de signaux.

L'exemple suivant initialise l'adaptateur:

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

Collecte des signaux

Avant le début d'une demande d'annonce, le SDK IMA appelle une méthode de collecte des signaux de manière asynchrone. Ces méthodes de collecte de signaux contiennent une fonction de rappel pour transmettre les signaux chiffrés ou signaler une erreur.

Remarque :Dans un délai de 500 millisecondes, vous devez terminer la collecte et le chiffrement des signaux, puis transmettre le signal chiffré à la fonction de rappel. Au bout de 500 millisecondes, le SDK IMA supprime toute collecte de signaux.

Les exemples suivants collectent les signaux sécurisés via la fonction de rappel:

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

Signaler les erreurs

Pour communiquer avec les utilisateurs qui utilisent votre classe d'adaptateur, signalez toutes les erreurs lors de la collecte des signaux et transmettez-les au rappel du collecteur de signaux. Ce processus permet de résoudre les problèmes survenant lors de l'intégration de votre adaptateur aux applications.

Les erreurs suivantes peuvent s'afficher:

• Votre SDK ou une dépendance ne sont pas trouvés dans l'application.
• Votre SDK ou une dépendance ne dispose pas de l'autorisation ou du consentement de l'utilisateur requis pour fonctionner.

Spécifier la version de l'adaptateur

Dans votre workflow, veillez à spécifier la version de l'adaptateur. Le SDK IMA inclut votre version d'adaptateur dans chaque demande d'annonce et les transmet avec les signaux sécurisés dans une demande d'enchère.

Dans la requête d'enchère, en fonction de la version de l'adaptateur, vous pouvez identifier les détails de chiffrement, d'encodage et de mise en forme que l'adaptateur utilise pour créer les signaux sécurisés.

L'exemple suivant spécifie la version de l'adaptateur:

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

Renvoyer la version du SDK Runtime

Vous pouvez concevoir votre adaptateur pour qu'il fonctionne avec plusieurs versions de votre SDK. Pour que l'adaptateur fonctionne avec plusieurs versions, assurez-vous de renvoyer la version d'exécution du SDK. Dans chaque demande d'annonce, le SDK IMA inclut la version d'exécution avec la version de l'adaptateur.

Les exemples suivants demandent et renvoient la version du SDK Runtime:

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

Enregistrer l'adaptateur auprès de Google

Pour que Google autorise l'adaptateur à collecter des signaux, vous devez enregistrer le nom du package Android ou le nom de l'application auprès de Google. Le SDK IMA initialise uniquement les adaptateurs que vous enregistrez auprès de Google.

Valider l'adaptateur

Pour valider l'adaptateur, suivez les sections suivantes:

Configurer l'application de test

Avant de valider l'adaptateur, configurez l'application de test. Procédez comme suit:

1. Ajoutez les dépendances du SDK IMA au fichier Gradle au niveau de l'application de votre module, par exemple app/build.gradle:

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

2. Ajoutez des dépendances de compilation, telles que votre adaptateur et votre SDK.

Vérifier les signaux

Pour vérifier que votre adaptateur envoie des signaux, utilisez un proxy réseau pour surveiller le trafic des requêtes publicitaires de votre application. Si la requête aboutit, les signaux s'affichent dans chaque requête d'annonce.

Examiner les exemples complets

Cette section capture l'exemple terminé de toutes les étapes et est disponible pour référence.

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