Serverseitige Überprüfung

Plattform auswählen: Android (Beta) Android iOS Unity Flutter

Serverseitige Überprüfungs-Callbacks sind URL-Anfragen, deren Abfrageparameter von Google erweitert werden. Sie werden von Google an ein externes System gesendet, um es darüber zu informieren, dass ein Nutzer für die Interaktion mit einer Anzeige mit Prämie oder einer Interstitial-Anzeige mit Prämie belohnt werden sollte. Serverseitige Überprüfungs-Callbacks für Anzeigen mit Prämie bieten eine zusätzliche Schutzebene gegen das Spoofing von clientseitigen Überprüfungs-Callbacks, um Nutzer zu belohnen.

In diesem Leitfaden erfahren Sie, wie Sie serverseitige Überprüfungs-Callbacks für Anzeigen mit Prämie mithilfe der kryptografischen Drittanbieterbibliothek „Tink Java Apps“ überprüfen können, um sicherzustellen, dass die Abfrageparameter im Callback gültige Werte sind. Obwohl in diesem Leitfaden Tink verwendet wird, können Sie jede Drittanbieterbibliothek verwenden, die unterstützt ECDSA. Sie können Ihren Server auch mit dem Testtool in der AdMob-Benutzeroberfläche testen.

Vorbereitung

• Aktivieren Sie die serverseitige Überprüfung für Anzeigen mit Prämie in Ihrem Anzeigenblock.

RewardedAdsVerifier aus der Tink Java Apps-Bibliothek verwenden

Das Tink Java Apps GitHub-Repository enthält die RewardedAdsVerifier Hilfsklasse, um den Code zu reduzieren, der zum Überprüfen eines serverseitigen Überprüfungs-Callbacks für Anzeigen mit Prämie erforderlich ist. Mit dieser Klasse können Sie eine Callback-URL mit dem folgenden Code überprüfen.

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, wurde die Callback-URL erfolgreich überprüft. Im Abschnitt Nutzer belohnen finden Sie Best Practices dazu, wann Nutzer belohnt werden sollten. Eine Aufschlüsselung der Schritte, die von dieser Klasse zum Überprüfen serverseitiger Überprüfungs-Callbacks für Anzeigen mit Prämie ausgeführt werden, finden Sie im Abschnitt Manuelle Überprüfung serverseitiger Überprüfungs-Callbacks für Anzeigen mit Prämie.

Parameter für serverseitige Überprüfungs-Callbacks

Serverseitige Überprüfungs-Callbacks enthalten Abfrageparameter, die die Interaktion mit der Anzeige mit Prämie beschreiben. Parametername, Beschreibung und Beispielwerte sind unten aufgeführt. Parameter werden in alphabetischer Reihenfolge gesendet.

Anzeigenquellen-IDs

Nutzer belohnen

Bei der Entscheidung, wann ein Nutzer belohnt werden soll, ist es wichtig, ein Gleichgewicht zwischen Nutzerfreundlichkeit und Überprüfung der Prämie zu finden. Bei serverseitigen Überprüfungs-Callbacks kann es zu Verzögerungen kommen, bevor sie externe Systeme erreichen. Daher empfiehlt es sich, den clientseitigen Überprüfungs-Callback zu verwenden, um den Nutzer sofort zu belohnen, und gleichzeitig alle Prämien nach Erhalt serverseitiger Überprüfungs-Callbacks zu überprüfen. Dieser Ansatz bietet eine gute Nutzerfreundlichkeit und gewährleistet gleichzeitig die Gültigkeit der gewährten Prämien.

Bei Anwendungen, bei denen die Gültigkeit der Prämie entscheidend ist (z. B. wenn die Prämie die In-Game-Wirtschaft Ihrer App beeinflusst) und Verzögerungen bei der Gewährung von Prämien akzeptabel sind, kann es jedoch der beste Ansatz sein, auf den überprüften serverseitigen Überprüfungs-Callback zu warten.

Benutzerdefinierte Daten

Apps, die zusätzliche Daten in serverseitigen Überprüfungs-Callbacks benötigen, sollten die Funktion für benutzerdefinierte Daten von Anzeigen mit Prämie verwenden. Jeder Stringwert, der für ein Anzeigenobjekt mit Prämie festgelegt wurde, wird an den Abfrageparameter custom_data des serverseitigen Überprüfungs-Callbacks übergeben. Wenn kein benutzerdefinierter Datenwert festgelegt ist, ist der Abfrageparameterwert custom_data nicht im serverseitigen Überprüfungs-Callback vorhanden.

Im folgenden Beispiel werden die Optionen für die serverseitige Überprüfung festgelegt, nachdem die Anzeige mit Prämie geladen wurde:

RewardedAd.load(with:"AD_UNIT_ID",
                       request: request,
                       completionHandler: { [self] ad, error in
      if let error != error {
      rewardedAd = ad
      let options = ServerSideVerificationOptions()
      options.customRewardString = "SAMPLE_CUSTOM_DATA_STRING"
      rewardedAd.serverSideVerificationOptions = options
    }
})

GADRequest *request = [GADRequest request];
[GADRewardedAd loadWithAdUnitID:@"AD_UNIT_ID"
                        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 Überprüfung serverseitiger Überprüfungs-Callbacks für Anzeigen mit Prämie

Die Schritte, die von der Klasse RewardedAdsVerifier zum Überprüfen eines serverseitigen Überprüfungs-Callbacks für Anzeigen mit Prämie ausgeführt werden, sind unten aufgeführt. Obwohl die enthaltenen Code-Snippets in Java geschrieben sind und die Drittanbieterbibliothek Tink verwenden, können Sie diese Schritte in der Sprache Ihrer Wahl implementieren und dabei jede Drittanbieterbibliothek verwenden, die ECDSA unterstützt.

Öffentliche Schlüssel abrufen

Zum Überprüfen eines serverseitigen Überprüfungs-Callbacks für Anzeigen mit Prämie benötigen Sie einen öffentlichen Schlüssel, der von AdMob bereitgestellt wird.

Eine Liste der öffentlichen Schlüssel, die zum Überprüfen der serverseitigen Überprüfungs-Callbacks für Anzeigen mit Prämie verwendet werden sollen, kann vom AdMob-Schlüssel server abgerufen werden. Die Liste der öffentlichen Schlüssel wird als JSON-Darstellung mit einem ähnlichen Format wie das folgende 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=="
    },
  ],
}

Um die öffentlichen Schlüssel abzurufen, stellen Sie eine Verbindung zum AdMob-Schlüsselserver her und laden Sie die Schlüssel herunter. Mit dem folgenden Code wird diese Aufgabe ausgeführt und die JSON-Darstellung der Schlüssel in der Variablen data gespeichert.

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

Öffentliche Schlüssel werden regelmäßig rotiert. Sie erhalten eine E-Mail, um Sie über eine bevorstehende Rotation zu informieren. Wenn Sie öffentliche Schlüssel im Cache speichern, sollten Sie die Schlüssel nach Erhalt dieser E-Mail aktualisieren.

Nachdem die öffentlichen Schlüssel abgerufen wurden, müssen sie geparst werden. Die Methode parsePublicKeysJson unten verwendet einen JSON-String wie im obigen Beispiel als Eingabe 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;
}

Zu überprüfenden Inhalt abrufen

Die letzten beiden Abfrageparameter von serverseitigen Überprüfungs-Callbacks für Anzeigen mit Prämie sind immer signature und key_id, in dieser Reihenfolge. Die übrigen Abfrageparameter geben den zu überprüfenden Inhalt an. Angenommen, Sie haben AdMob so konfiguriert, dass Überprüfungs-Callbacks für Anzeigen mit Prämie an https://www.myserver.com/mypath gesendet werden. Das folgende Snippet zeigt ein Beispiel für einen serverseitigen Überprüfungs-Callback für Anzeigen mit Prämie, wobei der zu überprüfende Inhalt hervorgehoben ist.

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 aus einer Callback-URL als UTF-8-Byte-Array geparst wird.

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 der Callback-URL abrufen

Parsen Sie mit dem Wert queryString aus dem vorherigen Schritt die Abfrageparameter signature und key_id aus der Callback-URL, wie unten gezeigt:

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

Im letzten Schritt wird der Inhalt der Callback-URL mit dem entsprechenden öffentlichen Schlüssel überprüft. Nehmen Sie die Zuordnung, die von der Methode parsePublicKeysJson zurückgegeben wurde, und verwenden Sie den Parameter key_id aus der Callback-URL, um den öffentlichen Schlüssel aus dieser Zuordnung abzurufen. Überprüfen Sie dann die Signatur mit diesem öffentlichen Schlüssel. Diese Schritte werden unten in der Methode verify veranschaulicht.

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

Wenn die Methode ohne Ausnahme ausgeführt wird, wurde die Callback-URL erfolgreich überprüft.

FAQ

Kann ich den öffentlichen Schlüssel, der vom AdMob-Schlüsselserver bereitgestellt wird, im Cache speichern?

Wir empfehlen, den öffentlichen Schlüssel, der vom AdMob-Schlüsselserver bereitgestellt wird, im Cache zu speichern, um die Anzahl der Vorgänge zu reduzieren, die zum Überprüfen serverseitiger Überprüfungs-Callbacks erforderlich sind. Öffentliche Schlüssel werden jedoch regelmäßig rotiert und sollten nicht länger als 24 Stunden im Cache gespeichert werden.

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

Öffentliche Schlüssel, die vom AdMob-Schlüsselserver bereitgestellt werden, werden nach einem variablen Zeitplan rotiert. Damit die Überprüfung serverseitiger Überprüfungs-Callbacks weiterhin wie vorgesehen funktioniert, sollten öffentliche Schlüssel nicht länger als 24 Stunden im Cache gespeichert werden.

Was passiert, wenn mein Server nicht erreichbar ist?

Google erwartet für serverseitige Überprüfungs-Callbacks den Antwortcode HTTP 200 OK. Wenn Ihr Server nicht erreichbar ist oder nicht die erwartete Antwort liefert, versucht Google bis zu fünf Mal, serverseitige Überprüfungs-Callbacks in Abständen von einer Sekunde zu senden.

Wie kann ich überprüfen, ob serverseitige Überprüfungs-Callbacks von Google stammen?

Verwenden Sie den umgekehrten DNS-Lookup, um zu überprüfen, ob serverseitige Überprüfungs-Callbacks von Google stammen.