Weryfikowanie wywołań zwrotnych po stronie serwera (SSV)

Wywołania zwrotne weryfikacji po stronie serwera to żądania adresów URL z parametrami zapytania rozszerzone przez Google, które są wysyłane przez Google do systemu zewnętrznego w celu powiadomić go, że użytkownik powinien być nagrodzony za interakcję z reklama pełnoekranowa z nagrodą. Wywołania zwrotne SSV (weryfikacja po stronie serwera) zapewniają dodatkową warstwę ochrony przed podszywaniem się w wywołaniach zwrotnych po stronie klienta; aby nagradzać użytkowników.

Z tego przewodnika dowiesz się, jak zweryfikować wywołania zwrotne SSV z nagrodą za pomocą Aplikacje w Javie Tink innych firm biblioteki kryptograficznej, by zapewnić, że parametry zapytania w wywołaniu zwrotnym będą prawidłowe wartości. Chociaż w tym przewodniku Tink jest używany, możesz korzystać z biblioteki innej firmy, która obsługuje ECDSA Serwer możesz też przetestować za pomocą testowania w interfejsie AdMob.

Zobacz w pełni działającą przykład za pomocą Sprężynowego rozruchu Java.

Wymagania wstępne

Korzystanie z narzędzia NagrodyAdsVerifier z biblioteki aplikacji Tink w języku Java

repozytorium Tink Java Apps na GitHubie. zawiera RewardedAdsVerifier. klasy pomocniczej, aby zmniejszyć kod wymagany do weryfikacji wywołania zwrotnego SSV z nagrodą. Użycie tej klasy umożliwia zweryfikowanie adresu URL wywołania zwrotnego za pomocą poniższego kodu.

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

Jeśli metoda verify() zostanie wykonana bez zgłaszania wyjątku, wywołanie zwrotne Adres URL został zweryfikowany. Pole Nagradzanie użytkowników zawiera szczegółowe informacje o sprawdzonych metodach dotyczących tego, kiedy użytkownicy powinni otrzymywać nagrody. Dla zestawienie czynności wykonywanych przez tę klasę w celu weryfikacji wywołań zwrotnych SSV z nagrodą przeczytaj artykuł Ręczna weryfikacja reklam z nagrodą SSV.

Parametry wywołania zwrotnego SSV

Wywołania zwrotne weryfikacji po stronie serwera zawierają parametry zapytania opisujące interakcji z reklamą z nagrodą. Nazwy parametrów, opisy i przykładowe wartości to wymienionych poniżej. Parametry są wysyłane w kolejności alfabetycznej.

Nazwa parametru Opis Przykładowa wartość
ad_network Identyfikator źródła reklam, które wyświetliło tę reklamę. Źródło reklam nazwy odpowiadające wartościom identyfikatora są wymienione na liście identyfikatory źródeł. 1953547073528090325
ad_unit Identyfikator jednostki reklamowej AdMob użytej do wysłania żądania reklamy z nagrodą. 2747237135
custom_data Niestandardowy ciąg danych dostarczony przez customRewardString .

Jeśli aplikacja nie podaje niestandardowego ciągu danych, ten parametr zapytania nie zostanie podana w wywołaniu zwrotnym SSV.

 SAMPLE_CUSTOM_DATA_STRING
key_id Klucz używany do weryfikacji wywołania zwrotnego SSV. Ta wartość jest mapowana na klucz publiczny dostarcza serwer kluczy AdMob. 1234567890
reward_amount Kwota nagrody określona w ustawieniach jednostki reklamowej. 5
reward_item Przedmiot nagrody zgodnie z ustawieniami jednostki reklamowej. monety
podpis Podpis wywołania zwrotnego SSV wygenerowany przez AdMob. MEUCIQCLJS_s4ia_sN06HqzeW7Wc3nhZi4RlW3qV0oO-6AIYdQIgGJEh-rzKreO-paNDbSCzWGMtmgJHYYW9k2_icM9LFMY
sygnatura czasowa Sygnatura czasowa momentu (w milisekundach) przyznania użytkownikowi nagrody w postaci czasu epoki. 1507770365237823
transaction_id Unikalny, zakodowany szesnastkowo identyfikator każdego zdarzenia przyznania nagrody wygenerowanego przez AdMob. 18fa792de1bca816048293fc71035638
user_id Identyfikator użytkownika podany przez userIdentifier

Jeśli aplikacja nie podaje identyfikatora użytkownika, ten parametr zapytania nie będzie w wywołaniu zwrotnym SSV.

 1234567

Identyfikatory źródeł reklam

Nazwy i identyfikatory źródeł reklam

广告来源名称 广告来源 ID
Aarki（出价）5240798063227064260
Ad Generation（出价）1477265452970951479
AdColony 15586990674969969776
AdColony（非 SDK）（出价）4600416542059544716
AdColony（出价）6895345910719072481
AdFalcon3528208921554210682
AdMob 广告联盟5450213213286189855
AdMob 广告联盟广告瀑布流1215381445328257950
ADResult10593873382626181482
AMoAd17253994435944008978
AppLovin1063618907739174004
AppLovin（出价）1328079684332308356
Chartboost2873236629771172317
Chocolate Platform（出价）6432849193975106527
跨渠道 (MdotM)9372067028804390441
自定义事件18351550913290782395
DT Exchange*
* 在 2022 年 9 月 21 日之前，该广告联盟称为“Fyber Marketplace”。		2179455223494392917
EMX（出价）8497809869790333482
Fluct（出价）8419777862490735710
小风3376427960656545613
Fyber*
* 此广告来源用于生成历史报告。		4839637394546996422
i-mobile5208827440166355534
优化数字化（出价）159382223051638006
Index Exchange（出价）4100650709078789802
InMobi7681903010231960328
InMobi（出价）6325663098072678541
InMobi Exchange（出价）5264320421916134407
IronSource6925240245545091930
ironSource Ads（出价）1643326773739866623
Leadbolt2899150749497968595
LG U+AD18298738678491729107
LINE 广告联盟3025503711505004547
maio7505118203095108657
maio（出价）1343336733822567166
Media.net（出价）2127936450554446159
参与中介的自家广告6060308706800320801
Meta Audience Network*
* 在 2022 年 6 月 6 日之前，该广告联盟称为“Facebook Audience Network”。		10568273599589928883
Meta Audience Network（出价）*
* 在 2022 年 6 月 6 日之前，该广告联盟称为“Facebook Audience Network（出价）”。		11198165126854996598
Mintegral1357746574408896200
Mintegral（出价）6250601289653372374
MobFox8079529624516381459
MobFox（出价）3086513548163922365
MoPub（已弃用）10872986198578383917
myTarget8450873672465271579
Nend9383070032774777750
Nexxen（出价）*

* 在 2024 年 5 月 1 日之前，该广告联盟称为“UnrulyX”。

2831998725945605450
ONE by AOL (Millennial Media)6101072188699264581
ONE by AOL (Nexage)3224789793037044399
OneTag Exchange（出价）4873891452523427499
OpenX（出价）4918705482605678398
邦格尔4069896914521993236
Pangle（出价）3525379893916449117
PubMatic（出价）3841544486172445473
预订型广告系列7068401028668408324
RhythmOne（出价）2831998725945605450
Rubicon（出价）3993193775968767067
SK 星球734341340207269415
Sharethrough（出价）5247944089976324188
Smaato（出价）3362360112145450544
Equativ（出价）*

* 在 2023 年 1 月 12 日之前，该广告联盟称为“Smart Adserver”。

5970199210771591442
Sonobi（出价）3270984106996027150
Tapjoy7295217276740746030
Tapjoy（出价）4692500501762622178
Tencent GDT7007906637038700218
TripleLift（出价）8332676245392738510
Unity 广告4970775877303683148
Unity Ads（出价）7069338991535737586
Verizon Media7360851262951344112
Verve Group（出价）5013176581647059185
Vpon1940957084538325905
Liftoff Monetize*

* 在 2023 年 1 月 30 日之前，该广告联盟称为“Vungle”。

1953547073528090325
Liftoff Monetize（出价）*

* 在 2023 年 1 月 30 日之前，该广告联盟称为“Vungle（出价）”。

4692500501762622185
Yieldmo（出价）4193081836471107579
YieldOne（出价）3154533971590234104
Zucks5506531810221735863

Nagradzanie użytkownika

Ważne jest zachowanie równowagi między wygodą użytkowników a weryfikacją nagród i określić, kiedy należy nagradzać użytkownika. W przypadku wywołań zwrotnych po stronie serwera mogą wystąpić opóźnienia przed które docierają do systemów zewnętrznych. Dlatego zalecamy stosowanie wywołanie zwrotne po stronie klienta, by natychmiast nagrodzić użytkownika, weryfikacji wszystkich nagród po otrzymaniu wywołań zwrotnych po stronie serwera. Ten zapewnia wygodę użytkownikom, a jednocześnie zapewnienie prawidłowości nagrody.

Jednak w aplikacjach, w których ważność nagrody jest kluczowa (na przykład wpływa na ekonomię w grze), a opóźnienia w ich przyznawaniu są akceptowalne, najlepszym rozwiązaniem jest oczekiwanie na zweryfikowane wywołanie zwrotne po stronie serwera. jak ważna jest pokora.

Dane niestandardowe

W przypadku aplikacji, które wymagają dodatkowych danych w wywołaniach zwrotnych weryfikacji po stronie serwera, należy użyć parametru niestandardowe dane reklam z nagrodą. Dowolny ciąg znaków ustawiony w reklamie z nagrodą jest przekazywany do parametru zapytania custom_data w wywołaniu zwrotnym SSV. Jeśli nie niestandardowych wartości danych, wartość parametru zapytania custom_data nie będzie w wywołaniu zwrotnym SSV.

Poniższy przykładowy kod pokazuje, jak ustawić opcje SSV po tagu reklama z nagrodą została wczytana.

Swift

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
    }

Objective-C

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

Ręczna weryfikacja reklamy SSV z nagrodą

Czynności wykonywane przez klasę RewardedAdsVerifier w celu zweryfikowania reklamy z nagrodą Poniżej znajdziesz opis usługi SSV. Mimo że dołączone fragmenty kodu są w języku Java jeśli korzystasz z biblioteki zewnętrznej Tink, możesz wykonać te czynności w wybranym języku, używając do tego dowolnej biblioteki zewnętrznej, która obsługuje ECDSA

Pobierz klucze publiczne

Aby zweryfikować wywołanie zwrotne SSV z nagrodą, potrzebujesz klucza publicznego dostarczonego przez AdMob.

Lista kluczy publicznych używanych do weryfikacji wywołań zwrotnych SSV z nagrodą może być pobrane z klucza AdMob Lista kluczy publicznych jest podana w postaci reprezentacji JSON w formacie podobnym do tego:

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

Aby pobrać klucze publiczne, połącz się z serwerem kluczy AdMob i pobierz plik klawiszy. Następujący kod wykonuje to zadanie i zapisuje JSON reprezentacja kluczy do zmiennej 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();
}

Pamiętaj, że klucze publiczne są regularnie poddawane rotacji. Otrzymasz e-maila z informacjami o nadchodzącej rotacji. Jeśli buforujesz klucze publiczne, musisz zaktualizować klucze.

Po pobraniu kluczy publicznych należy je przeanalizować. Poniższa metoda parsePublicKeysJson pobiera ciąg znaków JSON, jak w przykładzie. powyżej jako danych wejściowych i tworzy mapowanie z wartości key_id na klucze publiczne, zapakowane jako obiekty ECPublicKey z biblioteki 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;
}

Pobieranie treści do zweryfikowania

Ostatnie 2 parametry zapytania wywołań zwrotnych SSV z nagrodą mają zawsze wartość signature i key_id, w tej kolejności. Pozostałe parametry zapytania określają treść do weryfikacji. Załóżmy, że skonfigurujesz w AdMob wysyłanie wywołań zwrotnych do nagrody https://www.myserver.com/mypath Fragment kodu poniżej zawiera przykład reklamy z nagrodą Wywołanie zwrotne SSV z wyróżnioną treścią do zweryfikowania.

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

Poniższy kod pokazuje, jak przeanalizować treść, która ma zostać zweryfikowana adresu URL wywołania zwrotnego jako tablicy 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"));

Pobieranie podpisu i identyfikatora key_id z adresu URL wywołania zwrotnego

Korzystając z wartości queryString z poprzedniego kroku, przeanalizuj analizy signature i Parametry zapytania key_id z adresu URL wywołania zwrotnego, jak pokazano poniżej:

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

Przeprowadź weryfikację

Ostatnim krokiem jest weryfikacja treści adresu URL wywołania zwrotnego za pomocą atrybutu odpowiedni klucz publiczny. Użyj mapowania zwróconego z metody parsePublicKeysJson i użyj parametru key_id z wywołania zwrotnego Adres URL do pobrania klucza publicznego z tego mapowania. Następnie zweryfikuj podpis, używając taki klucz publiczny. Kroki te zostały opisane poniżej w metodzie 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);
  }
}

Jeśli metoda jest wykonywana bez zgłaszania wyjątku, adres URL wywołania zwrotnego miał postać zweryfikowano.

Najczęstsze pytania

Czy mogę zapisać w pamięci podręcznej klucz publiczny udostępniony przez serwer kluczy AdMob?
Zalecamy zapisywanie w pamięci podręcznej klucza publicznego dostarczonego przez klucz AdMob serwera, aby zmniejszyć liczbę operacji wymaganych do weryfikacji SSV . Pamiętaj jednak, że klucze publiczne są regularnie poddawane rotacji i nie należy ich mogą być przechowywane w pamięci podręcznej dłużej niż 24 godziny.
Jak często poddawana jest rotacja kluczy publicznych dostarczanych przez serwer kluczy AdMob?
Klucze publiczne przekazane przez serwer kluczy AdMob są poddawane rotacji na zmiennej harmonogram. Aby weryfikacja wywołań zwrotnych SSV nadal działała kluczy publicznych nie należy przechowywać w pamięci podręcznej dłużej niż przez 24 godziny.
Co się stanie, jeśli mój serwer będzie nieosiągalny?
Google oczekuje kodu odpowiedzi stanu powodzenia HTTP 200 OK w przypadku SSV . Jeśli serwer jest nieosiągalny lub nie zapewnia , Google spróbuje ponownie wysłać wywołania zwrotne SSV maksymalnie 5 razy jednosekundowych odstępach.
Jak sprawdzić, czy wywołania zwrotne SSV pochodzą z Google?
Użyj wstecznego wyszukiwania DNS, by sprawdzić, czy wywołania zwrotne SSV pochodzą z Google.