Weryfikowanie wywołań zwrotnych weryfikacji po stronie serwera

Wywołania zwrotne weryfikacji po stronie serwera to żądania URL z parametrami zapytania rozwiniętymi przez Google, które Google wysyła do systemu zewnętrznego, aby powiadomić go, że użytkownik powinien otrzymać nagrodę za interakcję z reklamą z nagrodą lub reklamą pełnoekranową z nagrodą. Wywołania zwrotne SSV (weryfikacja po stronie serwera) w przypadku reklam z nagrodą zapewniają dodatkową ochronę przed podszywaniem się pod wywołania zwrotne po stronie klienta w celu nagradzania użytkowników.

Z tego przewodnika dowiesz się, jak weryfikować wywołania zwrotne SSV reklam z nagrodą za pomocą zewnętrznej biblioteki kryptograficznej Tink Java Apps, aby mieć pewność, że parametry zapytania w wywołaniu zwrotnym są prawidłowe. Chociaż w tym przewodniku używamy Tink, możesz użyć dowolnej biblioteki innej firmy, która obsługuje ECDSA. Możesz też przetestować serwer za pomocą narzędzia do testowania w interfejsie AdMob.

Wymagania wstępne

Używanie klasy RewardedAdsVerifier z biblioteki aplikacji Tink Java

Repozytorium GitHub Tink Java Apps zawiera klasę pomocniczą RewardedAdsVerifier, która zmniejsza ilość kodu wymaganego do weryfikacji wywołania zwrotnego SSV z nagrodą. Użycie tej klasy umożliwia zweryfikowanie adresu URL wywołania zwrotnego za pomocą tego 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, adres URL wywołania zwrotnego został pomyślnie zweryfikowany. W sekcji Nagradzanie użytkownika znajdziesz sprawdzone metody dotyczące tego, kiedy należy nagradzać użytkowników. Szczegółowe informacje o czynnościach wykonywanych przez tę klasę w celu weryfikacji wywołań zwrotnych SSV reklam z nagrodą znajdziesz w sekcji Ręczna weryfikacja SSV reklam z nagrodą.

Parametry wywołania zwrotnego SSV

Wywołania zwrotne w ramach weryfikacji po stronie serwera zawierają parametry zapytania, które opisują interakcję z reklamą z nagrodą. Nazwy parametrów, opisy i przykładowe wartości znajdziesz poniżej. Parametry są wysyłane w porządku alfabetycznym.

Nazwa parametru Opis Przykładowa wartość
ad_network Identyfikator źródła reklam, które wyświetliło tę reklamę. Nazwy źródeł reklam odpowiadające wartościom identyfikatorów są wymienione w sekcji Identyfikatory źródeł reklam. 1953547073528090325
ad_unit Identyfikator jednostki reklamowej AdMob, który został użyty do wysłania żądania reklamy z nagrodą. 2747237135
key_id Klucz używany do weryfikacji wywołania zwrotnego SSV. Ta wartość jest mapowana na klucz publiczny dostarczany przez serwer kluczy AdMob. 1234567890
reward_amount Wysokość nagrody określona w ustawieniach jednostki reklamowej. 5
reward_item Przedmiot nagrody określony w ustawieniach 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 którym użytkownik otrzymał nagrodę, w formacie czasu epoki w milisekundach. 1507770365237823
transaction_id Unikalny identyfikator zakodowany w systemie szesnastkowym dla każdego zdarzenia przyznania nagrody wygenerowanego przez AdMob. 18fa792de1bca816048293fc71035638
user_id Identyfikator użytkownika podany przez: SetUserId.

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

 1234567

Identyfikatory źródeł reklam

Nazwy i identyfikatory źródeł reklam

Nazwa źródła reklamy Identyfikator źródła reklam
Ad Generation (określanie stawek)1477265452970951479
Sieć AdMob5450213213286189855
Kaskada sieci AdMob1215381445328257950
AppLovin1063618907739174004
AppLovin (określanie stawek)1328079684332308356
Bidease (określanie stawek)3670825090829827805
BidMachine (określanie stawek)7943972370566394673
Chartboost2873236629771172317
Chocolate Platform (określanie stawek)6432849193975106527
Zdarzenie niestandardowe18351550913290782395
DT Exchange*

* Przed 21 września 2022 r. ta sieć nazywała się „Fyber Marketplace”.

2179455223494392917
DT Exchange (określanie stawek)8189833498765234879
Equativ (określanie stawek)*

* Przed 12 stycznia 2023 r. ta sieć nazywała się „Smart Adserver”.

5970199210771591442
Fluct (określanie stawek)8419777862490735710
i-mobile5208827440166355534
Improve Digital (określanie stawek)159382223051638006
Index Exchange (określanie stawek)4100650709078789802
InMobi7681903010231960328
InMobi (SDK) (określanie stawek)8468954295581492586
InMobi Exchange (określanie stawek)5264320421916134407
ironSource Ads6925240245545091930
ironSource Ads (określanie stawek)1643326773739866623
Liftoff Monetize*

* Przed 30 stycznia 2023 r. ta sieć nazywała się „Vungle”.

1953547073528090325
Liftoff Monetize (określanie stawek)*

* Przed 30 stycznia 2023 r. ta sieć nazywała się „Vungle (określanie stawek)”.

4692500501762622185
LY Ads Network3025503711505004547
Sieć reklamowa LY (określanie stawek)2615812619460460513
Magnite DV+ (określanie stawek)3993193775968767067
maio7505118203095108657
Media.net (określanie stawek)2127936450554446159
Zapośredniczone autoreklamy6060308706800320801
Meta Audience Network*

* Przed 6 czerwca 2022 r. ta sieć nazywała się „Facebook Audience Network”.

10568273599589928883
Meta Audience Network (określanie stawek)*

* Przed 6 czerwca 2022 r. ta sieć nazywała się „Facebook Audience Network (określanie stawek)”.

11198165126854996598
Mintegral1357746574408896200
Mintegral (określanie stawek)6250601289653372374
Mobfox (określanie stawek)3086513548163922365
MobileFuse (określanie stawek)7303547408604090310
Moloco Ads SDK (określanie stawek)8267622065755668722
myTarget8450873672465271579
Nativo (określanie stawek)3240503836211327896
Nexxen (określanie stawek)*

* Przed 1 maja 2024 r. ta sieć nazywała się „UnrulyX”.

2831998725945605450
OneTag Exchange (określanie stawek)4873891452523427499
OpenX (określanie stawek)4918705482605678398
Pangle4069896914521993236
Pangle KR SDK (określanie stawek)12171279046073404914
Pangle ROW SDK (bidding)3525379893916449117
Pangle US SDK (określanie stawek)15999446638585856012
PubMatic (określanie stawek)3841544486172445473
PubMatic OpenWrap SDK7702975372504485373
PubMatic OpenWrap SDK (określanie stawek)1234567890123456789
Kampania z rezerwacją7068401028668408324
Wzrost (określanie stawek)6816468518946650043
Sharethrough (określanie stawek)5247944089976324188
Smaato (określanie stawek)3362360112145450544
Sonobi (określanie stawek)3270984106996027150
TripleLift (określanie stawek)8332676245392738510
Unity Ads4970775877303683148
Unity Ads (określanie stawek)7069338991535737586
Verve Group (określanie stawek)5013176581647059185
Vpon1940957084538325905
Yieldmo (określanie stawek)4193081836471107579
YieldOne (określanie stawek)3154533971590234104
Zucks5506531810221735863

Nagradzanie użytkownika

Podejmując decyzję o tym, kiedy przyznać użytkownikowi nagrodę, należy zachować równowagę między wygodą użytkownika a weryfikacją nagrody. Wywołania zwrotne po stronie serwera mogą docierać do systemów zewnętrznych z opóźnieniem. Dlatego zalecamy używanie wywołania zwrotnego po stronie klienta, aby natychmiast przyznać nagrodę użytkownikowi, a jednocześnie weryfikować wszystkie nagrody po otrzymaniu wywołań zwrotnych po stronie serwera. Takie podejście zapewnia użytkownikom dobre wrażenia, a jednocześnie gwarantuje, że przyznane nagrody są ważne.

Jeśli jednak ważność nagrody ma kluczowe znaczenie (np. nagroda wpływa na gospodarkę w grze), a opóźnienia w przyznawaniu nagród są akceptowalne, najlepszym rozwiązaniem może być oczekiwanie na zweryfikowane wywołanie zwrotne po stronie serwera.

Dane niestandardowe

Aplikacje, które wymagają dodatkowych danych w wywołaniach zwrotnych weryfikacji po stronie serwera, powinny korzystać z funkcji danych niestandardowych w reklamach z nagrodą. Każda wartość ciągu znaków ustawiona w obiekcie reklamy z nagrodą jest przekazywana do parametru zapytania custom_data wywołania zwrotnego SSV. Jeśli nie ustawiono wartości danych niestandardowych, wartość parametru zapytania custom_data nie będzie obecna w wywołaniu zwrotnym SSV.

Poniższy przykładowy kod pokazuje, jak ustawić opcje SSV po wczytaniu reklamy z nagrodą:

private void LoadRewardedAd(string adUnitId)
{
  // Send the request to load the ad.
  AdRequest adRequest = new AdRequest();
  RewardedAd.Load(adUnitId, adRequest, (RewardedAd rewardedAd, LoadAdError error) =>
  {
    // If the operation failed with a reason.
    if (error != null)
    {
        Debug.LogError("Rewarded ad failed to load an ad with error : " + error);
        return;
    }

    var options = new ServerSideVerificationOptions
                          .Builder()
                          .SetCustomData("SAMPLE_CUSTOM_DATA_STRING")
                          .Build()
    rewardedAd.SetServerSideVerificationOptions(options);
  });
}

Jeśli chcesz ustawić niestandardowy ciąg znaków nagrody, musisz to zrobić przed wyświetleniem reklamy.

Ręczna weryfikacja SSV reklam z nagrodą

Poniżej opisano czynności wykonywane przez klasę RewardedAdsVerifier w celu zweryfikowania SSV z nagrodą. Dołączone fragmenty kodu są napisane w języku Java i wykorzystują zewnętrzną bibliotekę Tink, ale możesz wykonać te czynności w wybranym przez siebie języku, używając dowolnej biblioteki zewnętrznej, która obsługuje ECDSA.

Pobierz klucze publiczne

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

Listę kluczy publicznych, które mają być używane do weryfikowania wywołań zwrotnych SSV z nagrodą, można pobrać z serwera kluczy AdMob. Lista kluczy publicznych jest podawana w formacie JSON, który wygląda mniej więcej tak:

{
 "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 klucze. Poniższy kod wykonuje to zadanie i zapisuje reprezentację kluczy w formacie JSON w 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 zmieniane. Otrzymasz e-maila z powiadomieniem o nadchodzącej rotacji. Jeśli przechowujesz klucze publiczne w pamięci podręcznej, po otrzymaniu tego e-maila zaktualizuj je.

Po pobraniu kluczy publicznych należy je przeanalizować. Metoda parsePublicKeysJson poniżej przyjmuje ciąg znaków JSON, taki jak w przykładzie powyżej, jako dane wejściowe i tworzy mapowanie z wartości key_id na klucze publiczne, które są hermetyzowane 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 weryfikacji

Ostatnie 2 parametry zapytania wywołań zwrotnych SSV z nagrodą to zawsze signature i key_id, (w tej kolejności). Pozostałe parametry zapytania określają treści do zweryfikowania. Załóżmy, że usługa AdMob została skonfigurowana tak, aby wysyłać wywołania zwrotne dotyczące nagród na adres https://www.myserver.com/mypath. Poniższy fragment kodu pokazuje przykładowe wywołanie zwrotne SSV reklamy z nagrodą 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ść do zweryfikowania z adresu URL wywołania zwrotnego jako tablicę bajtów 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 klucza z adresu URL wywołania zwrotnego

Używając wartości queryString z poprzedniego kroku, przeanalizuj parametry zapytania signature i 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 zweryfikowanie zawartości adresu URL wywołania zwrotnego za pomocą odpowiedniego klucza publicznego. Weź mapowanie zwrócone przez metodę parsePublicKeysJson i użyj parametru key_id z adresu URL wywołania zwrotnego, aby uzyskać klucz publiczny z tego mapowania. Następnie zweryfikuj podpis za pomocą tego klucza publicznego. Te kroki są przedstawione 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 zostanie wykonana bez zgłaszania wyjątku, adres URL wywołania zwrotnego został pomyślnie zweryfikowany.

Najczęstsze pytania

Czy mogę zapisać w pamięci podręcznej klucz publiczny udostępniany przez serwer kluczy AdMob?
Zalecamy zapisanie w pamięci podręcznej klucza publicznego dostarczonego przez serwer kluczy AdMob, aby zmniejszyć liczbę operacji wymaganych do weryfikacji wywołań zwrotnych SSV. Pamiętaj jednak, że klucze publiczne są regularnie zmieniane i nie powinny być przechowywane w pamięci podręcznej dłużej niż 24 godziny.
Jak często klucze publiczne udostępniane przez serwer kluczy AdMob są zmieniane?
Klucze publiczne udostępniane przez serwer kluczy AdMob są zmieniane według zmiennego harmonogramu. Aby mieć pewność, że weryfikacja wywołań zwrotnych SSV będzie nadal działać zgodnie z oczekiwaniami, klucze publiczne nie powinny być przechowywane w pamięci podręcznej dłużej niż przez 24 godziny.
Co się stanie, jeśli nie będzie można połączyć się z moim serwerem?
Google oczekuje kodu odpowiedzi HTTP 200 OK oznaczającego powodzenie w przypadku wywołań zwrotnych SSV. Jeśli nie uda się połączyć z Twoim serwerem lub nie zwróci on oczekiwanej odpowiedzi, Google spróbuje ponownie wysłać wywołania zwrotne SSV maksymalnie 5 razy w odstępach 1-sekundowych.
Jak mogę sprawdzić, czy wywołania zwrotne SSV pochodzą od Google?
Użyj odwrotnego wyszukiwania DNS, aby sprawdzić, czy wywołania zwrotne SSV pochodzą od Google.