Callbacks für serverseitige Überprüfungen validieren

Callbacks für die serverseitige Überprüfung sind URL-Anfragen mit Suchparametern die von Google an ein externes System gesendet werden, darüber informieren, dass ein Nutzer für die Interaktion mit einer Interstitial-Anzeige mit Prämie. Callbacks für die serverseitige Überprüfung von Anzeigen mit Prämie bieten zusätzlichen Schutz vor Spoofing clientseitiger Callbacks. um Nutzer zu belohnen.

In diesem Leitfaden erfahren Sie, wie Sie Callbacks für die serverseitige Überprüfung von Anzeigen mit Prämie mithilfe der Methode Tink Java Apps (Drittanbieter) Kryptografiebibliothek verwenden, um sicherzustellen, dass die Abfrageparameter im Callback korrekt sind. und legitime Werte. Obwohl Tink für die Zwecke dieses Leitfadens verwendet wird, können Sie Sie können eine beliebige Bibliothek von Drittanbietern verwenden, die ECDSA: Sie können Ihren Server auch mit der Testfunktion auf der AdMob-Benutzeroberfläche.

Sehen Sie sich diese voll funktionsfähige Beispiel mit dem Java-Spring-Boot.

Vorbereitung

• Anzeigen mit Prämie in Ihre mobile App mit Version 7.28.0 oder höher des Google Mobile Ads SDK.

• Serverseitige Anzeigen mit Prämie aktivieren für den Anzeigenblock.

„RewardAdsVerifier“ aus der Bibliothek für Tink-Java-Apps verwenden

GitHub-Repository für Tink Java Apps enthält ein RewardedAdsVerifier Hilfsklasse verwenden, um den Code zu reduzieren, der zur Bestätigung eines SSV-Rückrufs für Anzeigen mit Prämie erforderlich ist. Mit dieser Klasse können Sie eine Callback-URL mit dem folgenden Code verifizieren.

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

Wenn die Methode verify() ohne Ausnahme ausgeführt wird, Die URL wurde bestätigt. Die Option Belohnen für den Nutzer finden Sie Best Practices dazu, wann Nutzer Prämien erhalten sollten. Für eine Aufschlüsselung der Schritte, die in diesem Kurs ausgeführt wurden, um SSV-Rückrufe mit Prämie zu bestätigen Weitere Informationen zur manuellen Bestätigung SSV.

SSV-Callback-Parameter

Callbacks für die serverseitige Überprüfung enthalten Suchparameter, die die Interaktion mit einer Anzeige mit Prämie. Parameternamen, Beschreibungen und Beispielwerte (siehe unten). Parameter werden in alphabetischer Reihenfolge gesendet.

IDs der Anzeigenquellen

Nutzer belohnen

Es ist wichtig, bei der Entscheidung ein Gleichgewicht zwischen User Experience und Validierung der Prämie zu finden. wann Nutzende belohnen sollen. Bei serverseitigen Callbacks kann es vor dem externe Systeme zu erreichen. Daher empfiehlt es sich, den clientseitigen Callback, um den Nutzer sofort zu belohnen, während Überprüfung aller Prämien nach Erhalt von serverseitigen Callbacks. Dieses eine gute User Experience bietet und gleichzeitig die Gültigkeit der gewährten Prämien.

Bei Anwendungen, bei denen die Gültigkeit von Prämien entscheidend ist (z. B. hat Auswirkungen auf die In-Game-Ökonomie Ihrer App. Außerdem kann es zu Verzögerungen bei der Vergabe von Prämien kommen. akzeptabel ist, warten Sie am besten auf den verifizierten serverseitigen Rückruf. Ansatz.

Benutzerdefinierte Daten

Apps, die zusätzliche Daten in Callbacks zur serverseitigen Überprüfung benötigen, sollten Folgendes verwenden: die Funktion für benutzerdefinierte Daten von Anzeigen mit Prämie. Beliebiger Stringwert, der in einer Anzeige mit Prämie festgelegt ist wird an den custom_data-Abfrageparameter des SSV-Callbacks übergeben. Falls nein festgelegt ist, ist der Wert des Suchparameters custom_data nicht gleich im SSV-Callback vorhanden sind.

Im folgenden Codebeispiel wird gezeigt, wie die SSV-Optionen nach dem Anzeige mit Prämie wurde geladen.

GADRewardedAd.load(withAdUnitID:"ca-app-pub-3940256099942544/1712485313",
                       request: request,
                       completionHandler: { [self] ad, error in
      if let error != error {
      rewardedAd = ad
      let options = GADServerSideVerificationOptions()
      options.customRewardString = "SAMPLE_CUSTOM_DATA_STRING"
      rewardedAd.serverSideVerificationOptions = options
    }

GADRequest *request = [GADRequest request];
[GADRewardedAd loadWithAdUnitID:@"ca-app-pub-3940256099942544/1712485313"
                        request:request
              completionHandler:^(GADRewardedAd *ad, NSError *error) {
                if (error) {
                  // Handle Error
                  return;
                }
                self.rewardedAd = ad;
                GADServerSideVerificationOptions *options =
                    [[GADServerSideVerificationOptions alloc] init];
                options.customRewardString = @"SAMPLE_CUSTOM_DATA_STRING";
                ad.serverSideVerificationOptions = options;
              }];

Manuelle Bestätigung der SSV mit Prämie

Die Schritte, die von der Klasse „RewardedAdsVerifier“ ausgeführt werden, um eine Prämie zu bestätigen Die serverseitige Überprüfung wird im Folgenden beschrieben. Die enthaltenen Code-Snippets sind zwar in Java, die Tink-Drittanbieterbibliothek nutzen, können Sie diese Schritte in der Sprache Ihrer Wahl. Verwenden Sie dazu eine Drittanbieterbibliothek, die ECDSA:

Öffentliche Schlüssel abrufen

Zum Bestätigen eines Callbacks für eine SSV mit Prämie benötigen Sie einen von AdMob bereitgestellten öffentlichen Schlüssel.

Eine Liste mit öffentlichen Schlüsseln, mit denen die SSV-Callbacks mit Prämie validiert werden können aus dem AdMob-Schlüssel Server. Die Liste der öffentlichen Schlüssel wird als JSON-Darstellung in einem Format wie dem folgenden bereitgestellt:

{
 "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=="
    },
  ],
}

Stellen Sie zum Abrufen der öffentlichen Schlüssel eine Verbindung zum AdMob-Schlüsselserver her und laden Sie den Schlüssel. Der folgende Code führt diese Aufgabe durch und speichert die JSON-Datei Darstellung der Schlüssel für die 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();
}

Beachten Sie, dass öffentliche Schlüssel regelmäßig rotiert werden. Sie werden per E-Mail darüber informiert. eine bevorstehende Rotation. Wenn Sie öffentliche Schlüssel im Cache speichern, sollten Sie erhalten Sie nach Erhalt dieser E-Mail die Schlüssel.

Sobald die öffentlichen Schlüssel abgerufen wurden, müssen sie geparst werden. Die Für die Methode parsePublicKeysJson unten wird ein JSON-String wie im Beispiel verwendet und erstellt eine Zuordnung von key_id-Werten zu öffentlichen Schlüsseln. die als ECPublicKey-Objekte aus der Tink-Bibliothek gekapselt sind.

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

Inhalte bestätigen lassen

Die letzten beiden Suchparameter von SSV-Callbacks mit Prämie sind immer signature und key_id, in dieser Reihenfolge. Die verbleibenden Suchparameter geben den Inhalt an, noch nicht bestätigt werden. Angenommen, Sie haben AdMob so konfiguriert, dass Rückrufe für Prämien https://www.myserver.com/mypath Das Snippet unten zeigt ein Beispiel für eine Anzeige mit Prämie SSV-Rückruf mit hervorgehobenem Inhalt

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

Der folgende Code zeigt, wie der zu überprüfende Inhalt von einem -Callback-URL als UTF-8-Byte-Array.

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"));

Signatur und key_id aus Callback-URL abrufen

Mit dem Wert queryString aus dem vorherigen Schritt parsen Sie signature und key_id-Abfrageparameter aus der Callback-URL, wie unten dargestellt:

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()));

Überprüfung durchführen

Der letzte Schritt besteht darin, den Inhalt der Callback-URL mit der Methode entsprechenden öffentlichen Schlüssel. Nehmen Sie die Zuordnung, die vom parsePublicKeysJson-Methode und verwenden Sie den key_id-Parameter aus dem Callback. URL zum Abrufen des öffentlichen Schlüssels aus dieser Zuordnung. Bestätigen Sie dann die Signatur mit diesen öffentlichen Schlüssel. Diese Schritte werden unten in der Methode verify beschrieben.

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

Wird die Methode ohne Ausnahme ausgeführt, lautete die Callback-URL: wurde bestätigt.

FAQ

Kann ich den vom AdMob-Schlüsselserver bereitgestellten öffentlichen Schlüssel im Cache speichern?

Wir empfehlen, den vom AdMob-Schlüssel bereitgestellten öffentlichen Schlüssel im Cache zu speichern Server, um die Anzahl der Vorgänge zur Validierung der SSV-Datei zu reduzieren Callbacks angegeben werden. Beachten Sie jedoch, dass öffentliche Schlüssel regelmäßig rotiert werden und nicht länger als 24 Stunden im Cache gespeichert werden.

Wie oft werden die vom AdMob-Schlüsselserver bereitgestellten öffentlichen Schlüssel rotiert?

Vom AdMob-Schlüsselserver bereitgestellte öffentliche Schlüssel werden für eine Variable rotiert ein. Um sicherzustellen, dass SSV-Rückrufe weiterhin funktionieren, sollten öffentliche Schlüssel nicht länger als 24 Stunden im Cache gespeichert werden.

Was passiert, wenn mein Server nicht erreichbar ist?

Google erwartet einen Erfolgsstatusantwortcode für die serverseitige Überprüfung von HTTP 200 OK Callbacks angegeben werden. Wenn Ihr Server nicht erreichbar ist oder nicht den erwarteten antwortet, versucht Google bis zu fünfmal ein-Sekunden-Intervall.

Wie kann ich prüfen, ob SSV-Rückrufe von Google stammen?

Mit dem umgekehrten DNS-Lookup können Sie prüfen, ob die SSV-Rückrufe von Google stammen.