Valider les rappels de validation côté serveur (SSV)

Les rappels de validation côté serveur sont des requêtes d'URL, avec des paramètres de requête développés par Google, qui sont envoyées par Google à un système externe pour l'informer qu'un utilisateur doit être récompensé pour avoir interagi avec une annonce vidéo avec récompense ou une annonce interstitielle avec récompense. Les rappels de validation côté serveur pour les annonces avec récompense offrent une protection supplémentaire contre l'usurpation des rappels côté client pour récompenser les utilisateurs.

Ce guide vous explique comment valider les rappels SSV avec récompense à l'aide de la bibliothèque cryptographique tierce Tink Java Apps pour vous assurer que les paramètres de requête du rappel sont des valeurs légitimes. Bien que Tink soit utilisé dans ce guide, vous pouvez utiliser n'importe quelle bibliothèque tierce compatible avec ECDSA. Vous pouvez également tester votre serveur avec l'outil de test dans l'UI AdMob.

Prérequis

• Activez la validation côté serveur des récompenses sur votre bloc d'annonces.

Utiliser RewardedAdsVerifier à partir de la bibliothèque Tink Java Apps

Le dépôt GitHub Tink Java Apps inclut une classe d'assistance RewardedAdsVerifier pour réduire le code requis pour valider un rappel SSV avec récompense. Cette classe vous permet de valider une URL de rappel avec le code suivant.

RewardedAdsVerifier verifier = new RewardedAdsVerifier.Builder()
    .fetchVerifyingPublicKeysWith(
        RewardedAdsVerifier.KEYS_DOWNLOADER_INSTANCE_PROD)
    .build();
String rewardUrl = ...;
verifier.verify(rewardUrl);

Si la méthode verify() s'exécute sans générer d'exception, l'URL de rappel a été validée. La section Récompenser l'utilisateur décrit les bonnes pratiques concernant le moment où les utilisateurs doivent être récompensés. Pour obtenir une description détaillée des étapes effectuées par cette classe pour valider les rappels SSV avec récompense, vous pouvez consulter la section Validation manuelle des rappels SSV avec récompense.

Paramètres de rappel SSV

Les rappels de validation côté serveur contiennent des paramètres de requête qui décrivent l'interaction avec l'annonce avec récompense. Vous trouverez ci-dessous les noms, les descriptions et des exemples de valeurs pour ces paramètres. Les paramètres sont envoyés par ordre alphabétique.

Identifiants de sources d'annonces

Récompenser l'utilisateur

Il est important de trouver le bon équilibre entre l'expérience utilisateur et la validation des récompenses lorsque vous décidez quand récompenser un utilisateur. Les rappels côté serveur peuvent être retardés avant d'atteindre les systèmes externes. Par conséquent, la bonne pratique recommandée consiste à utiliser le rappel côté client pour récompenser immédiatement l'utilisateur, tout en effectuant la validation de toutes les récompenses à la réception des rappels côté serveur. Cette approche offre une bonne expérience utilisateur tout en garantissant la validité des récompenses accordées.

Toutefois, pour les applications où la validité des récompenses est essentielle (par exemple, si la récompense affecte l'économie du jeu dans votre application) et où les retards dans l'attribution des récompenses sont acceptables, il peut être préférable d'attendre le rappel côté serveur validé.

Données personnalisées

Les applications qui nécessitent des données supplémentaires dans les rappels de validation côté serveur doivent utiliser la fonctionnalité de données personnalisées des annonces avec récompense. Toute valeur de chaîne définie sur un objet d'annonce avec récompense est transmise au paramètre de requête custom_data du rappel SSV. Si aucune valeur de données personnalisée n'est définie, la valeur du paramètre de requête custom_data ne sera pas présente dans le rappel SSV.

L'exemple de code suivant montre comment définir des données personnalisées sur un objet d'annonce avec récompense avant de demander une annonce.

  firebase::gma::RewardedAd* rewarded_ad;
  rewarded_ad = new firebase::gma::RewardedAd();

  firebase::gma::RewardedAd::ServerSideVerificationOptions options;
  options.custom_data = "SAMPLE_CUSTOM_DATA_STRING";
  rewarded_ad->SetServerSideVerificationOptions(options);

Si vous souhaitez définir la chaîne de récompense personnalisée, vous devez le faire avant d'afficher l'annonce.

Validation manuelle des SSV avec récompense

Les étapes effectuées par la classe RewardedAdsVerifier pour valider un SSV récompensé sont décrites ci-dessous. Bien que les extraits de code inclus soient en Java et utilisent la bibliothèque tierce Tink, vous pouvez implémenter ces étapes dans la langue de votre choix, en utilisant n'importe quelle bibliothèque tierce compatible avec ECDSA.

Récupérer les clés publiques

Pour valider un rappel SSV avec récompense, vous avez besoin d'une clé publique fournie par AdMob.

Une liste de clés publiques à utiliser pour valider les rappels SSV avec récompense peut être récupérée à partir du serveur de clés AdMob. La liste des clés publiques est fournie sous forme de représentation JSON avec un format semblable à celui-ci :

{
 "keys": [
    {
      keyId: 1916455855,
      pem: "-----BEGIN PUBLIC KEY-----\nMF...YTPcw==\n-----END PUBLIC KEY-----"
      base64: "MFkwEwYHKoZIzj0CAQYI...ltS4nzc9yjmhgVQOlmSS6unqvN9t8sqajRTPcw=="
    },
    {
      keyId: 3901585526,
      pem: "-----BEGIN PUBLIC KEY-----\nMF...aDUsw==\n-----END PUBLIC KEY-----"
      base64: "MFYwEAYHKoZIzj0CAQYF...4akdWbWDCUrMMGIV27/3/e7UuKSEonjGvaDUsw=="
    },
  ],
}

Pour récupérer les clés publiques, connectez-vous au serveur de clés AdMob et téléchargez les clés. Le code suivant effectue cette tâche et enregistre la représentation JSON des clés dans la variable data.

String url = ...;
NetHttpTransport httpTransport = new NetHttpTransport.Builder().build();
HttpRequest httpRequest =
    httpTransport.createRequestFactory().buildGetRequest(new GenericUrl(url));
HttpResponse httpResponse = httpRequest.execute();
if (httpResponse.getStatusCode() != HttpStatusCodes.STATUS_CODE_OK) {
  throw new IOException("Unexpected status code = " + httpResponse.getStatusCode());
}
String data;
InputStream contentStream = httpResponse.getContent();
try {
  InputStreamReader reader = new InputStreamReader(contentStream, UTF_8);
  data = readerToString(reader);
} finally {
  contentStream.close();
}

Notez que les clés publiques sont régulièrement alternées. Vous recevrez un e-mail vous informant d'une rotation à venir. Si vous mettez en cache des clés publiques, vous devez les mettre à jour dès que vous recevez cet e-mail.

Une fois les clés publiques récupérées, elles doivent être analysées. La méthode parsePublicKeysJson ci-dessous prend en entrée une chaîne JSON, comme l'exemple ci-dessus, et crée un mappage des valeurs key_id aux clés publiques, qui sont encapsulées en tant qu'objets ECPublicKey de la bibliothèque Tink.

private static Map<Integer, ECPublicKey> parsePublicKeysJson(String publicKeysJson)
    throws GeneralSecurityException {
  Map<Integer, ECPublicKey> publicKeys = new HashMap<>();
  try {
    JSONArray keys = new JSONObject(publicKeysJson).getJSONArray("keys");
    for (int i = 0; i < keys.length(); i++) {
      JSONObject key = keys.getJSONObject(i);
      publicKeys.put(
          key.getInt("keyId"),
          EllipticCurves.getEcPublicKey(Base64.decode(key.getString("base64"))));
    }
  } catch (JSONException e) {
    throw new GeneralSecurityException("failed to extract trusted signing public keys", e);
  }
  if (publicKeys.isEmpty()) {
    throw new GeneralSecurityException("No trusted keys are available.");
  }
  return publicKeys;
}

Obtenir du contenu à valider

Les deux derniers paramètres de requête des rappels SSV avec récompense sont toujours signature et key_id,, dans cet ordre. Les autres paramètres de requête spécifient le contenu à valider. Imaginons que vous ayez configuré AdMob pour envoyer des rappels de récompense à https://www.myserver.com/mypath. L'extrait ci-dessous montre un exemple de rappel SSV avec récompense, le contenu à valider étant mis en évidence.

https://www.myserver.com/path?ad_network=54...55&ad_unit=12345678&reward_amount=10&reward_item=coins
&timestamp=150777823&transaction_id=12...DEF&user_id=1234567&signature=ME...Z1c&key_id=1268887

Le code ci-dessous montre comment analyser le contenu à vérifier à partir d'une URL de rappel en tant que tableau d'octets UTF-8.

public static final String SIGNATURE_PARAM_NAME = "signature=";
...
URI uri;
try {
  uri = new URI(rewardUrl);
} catch (URISyntaxException ex) {
  throw new GeneralSecurityException(ex);
}
String queryString = uri.getQuery();
int i = queryString.indexOf(SIGNATURE_PARAM_NAME);
if (i == -1) {
  throw new GeneralSecurityException("needs a signature query parameter");
}
byte[] queryParamContentData =
    queryString
        .substring(0, i - 1)
        // i - 1 instead of i because of & in the query string
        .getBytes(Charset.forName("UTF-8"));

Obtenir la signature et l'ID de clé à partir de l'URL de rappel

À l'aide de la valeur queryString de l'étape précédente, analysez les paramètres de requête signature et key_id de l'URL de rappel, comme indiqué ci-dessous :

public static final String KEY_ID_PARAM_NAME = "key_id=";
...
String sigAndKeyId = queryString.substring(i);
i = sigAndKeyId.indexOf(KEY_ID_PARAM_NAME);
if (i == -1) {
  throw new GeneralSecurityException("needs a key_id query parameter");
}
String sig =
    sigAndKeyId.substring(
        SIGNATURE_PARAM_NAME.length(), i - 1 /* i - 1 instead of i because of & */);
int keyId = Integer.valueOf(sigAndKeyId.substring(i + KEY_ID_PARAM_NAME.length()));

Effectuer la validation

La dernière étape consiste à valider le contenu de l'URL de rappel avec la clé publique appropriée. Prenez le mappage renvoyé par la méthode parsePublicKeysJson et utilisez le paramètre key_id de l'URL de rappel pour obtenir la clé publique à partir de ce mappage. Validez ensuite la signature avec cette clé publique. Ces étapes sont illustrées ci-dessous dans la méthode verify.

private void verify(final byte[] dataToVerify, int keyId, final byte[] signature)
    throws GeneralSecurityException {
  Map<Integer, ECPublicKey> publicKeys = parsePublicKeysJson();
  if (publicKeys.containsKey(keyId)) {
    foundKeyId = true;
    ECPublicKey publicKey = publicKeys.get(keyId);
    EcdsaVerifyJce verifier = new EcdsaVerifyJce(publicKey, HashType.SHA256, EcdsaEncoding.DER);
    verifier.verify(signature, dataToVerify);
  } else {
    throw new GeneralSecurityException("cannot find verifying key with key ID: " + keyId);
  }
}

Si la méthode s'exécute sans générer d'exception, l'URL de rappel a été validée.

Questions fréquentes

Puis-je mettre en cache la clé publique fournie par le serveur de clés AdMob ?

Nous vous recommandons de mettre en cache la clé publique fournie par le serveur de clés AdMob afin de réduire le nombre d'opérations nécessaires pour valider les rappels SSV. Toutefois, notez que les clés publiques sont régulièrement remplacées et ne doivent pas être mises en cache pendant plus de 24 heures.

À quelle fréquence les clés publiques fournies par le serveur de clés AdMob sont-elles alternées ?

Les clés publiques fournies par le serveur de clés AdMob sont renouvelées selon un calendrier variable. Pour que la validation des rappels SSV continue de fonctionner comme prévu, les clés publiques ne doivent pas être mises en cache pendant plus de 24 heures.

Que se passe-t-il si mon serveur est inaccessible ?

Google attend un code de réponse d'état de réussite HTTP 200 OK pour les rappels SSV. Si votre serveur est inaccessible ou ne fournit pas la réponse attendue, Google tentera à nouveau d'envoyer des rappels SSV jusqu'à cinq fois à intervalles d'une seconde.

Comment puis-je vérifier que les rappels SSV proviennent de Google ?

 Utilisez la résolution DNS inverse pour vérifier que les rappels SSV proviennent de Google.