Sunucu tarafı doğrulama (SSV) geri çağırmalarını doğrulama

Sunucu tarafı doğrulama geri çağırmaları, Google tarafından genişletilmiş sorgu parametreleri içeren URL istekleridir. Google, bu istekleri harici bir sisteme göndererek kullanıcıya ödüllü veya ödüllü geçiş reklamıyla etkileşimde bulunduğu için ödül verilmesi gerektiğini bildirir. Ödüllü SSV (sunucu tarafı doğrulama) geri çağırmaları, kullanıcıları ödüllendirmek için istemci tarafı geri çağırmalarının sahteciliğine karşı ek bir koruma katmanı sağlar.

Bu kılavuzda, geri çağırmadaki sorgu parametrelerinin geçerli değerler olduğundan emin olmak için Tink Java Apps adlı üçüncü taraf kriptografik kitaplığı kullanarak ödüllü SSV geri çağırmalarının nasıl doğrulanacağı gösterilmektedir. Bu kılavuzda Tink kullanılsa da ECDSA'yı destekleyen herhangi bir üçüncü taraf kitaplığını kullanabilirsiniz. Ayrıca, AdMob kullanıcı arayüzündeki test aracını kullanarak da sunucunuzu test edebilirsiniz.

Ön koşullar

• Reklam biriminizde ödül için sunucu tarafı doğrulama'yı etkinleştirin.

Tink Java Apps kitaplığındaki RewardedAdsVerifier'ı kullanma

Tink Java Apps GitHub deposunda, ödüllü bir SSV geri aramasını doğrulamak için gereken kodu azaltan bir RewardedAdsVerifier yardımcı sınıfı bulunur. Bu sınıfı kullanarak aşağıdaki kodla bir geri çağırma URL'sini doğrulayabilirsiniz.

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

verify() yöntemi istisna oluşturmadan yürütülürse geri çağırma URL'si başarıyla doğrulanmıştır. Kullanıcıyı ödüllendirme bölümünde, kullanıcıların ne zaman ödüllendirilmesi gerektiğiyle ilgili en iyi uygulamalar ayrıntılı olarak açıklanmaktadır. Bu sınıfın ödüllü SSV geri çağırmalarını doğrulamak için gerçekleştirdiği adımların dökümü için Ödüllü SSV'nin manuel doğrulanması bölümünü inceleyebilirsiniz.

SSV geri çağırma parametreleri

Sunucu tarafı doğrulama geri çağırmaları, ödüllü reklam etkileşimini açıklayan sorgu parametreleri içerir. Parametre adları, açıklamaları ve örnek değerleri aşağıda listelenmiştir. Parametreler alfabetik sırayla gönderilir.

Reklam kaynağı tanımlayıcıları

Kullanıcıyı ödüllendirme

Kullanıcıya ne zaman ödül verileceğine karar verirken kullanıcı deneyimi ile ödül doğrulama arasında denge kurmak önemlidir. Sunucu tarafı geri aramalar, harici sistemlere ulaşmadan önce gecikmeler yaşayabilir. Bu nedenle, sunucu tarafı geri aramaları alındığında tüm ödüller üzerinde doğrulama işlemi gerçekleştirilirken kullanıcıyı hemen ödüllendirmek için istemci tarafı geri aramanın kullanılması en iyi uygulama olarak önerilir. Bu yaklaşım, verilen ödüllerin geçerliliğini sağlarken iyi bir kullanıcı deneyimi sunar.

Ancak ödül geçerliliğinin kritik olduğu uygulamalarda (ör. ödül, uygulamanızın oyun içi ekonomisini etkiliyorsa) ve ödüllerin verilmesinde gecikmeler kabul edilebilir olduğunda, doğrulanmış sunucu tarafı geri araması için beklemek en iyi yaklaşım olabilir.

Özel veriler

Sunucu tarafı doğrulama geri çağırmalarında ek veri gerektiren uygulamalar, ödüllü reklamların özel veri özelliğini kullanmalıdır. Bir ödüllü reklam nesnesinde ayarlanan tüm dize değerleri, SSV geri çağırmasının custom_data sorgu parametresine iletilir. Özel veri değeri ayarlanmamışsa custom_data sorgu parametresi değeri SSV geri çağırmasında bulunmaz.

Aşağıdaki kod örneğinde, reklam isteğinde bulunmadan önce ödüllü reklam nesnesinde özel verilerin nasıl ayarlanacağı gösterilmektedir.

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

Özel ödül dizesini ayarlamak istiyorsanız bunu reklamı göstermeden önce yapmanız gerekir.

Ödüllü SSV'nin manuel olarak doğrulanması

Ödüllü bir SSV'yi doğrulamak için RewardedAdsVerifier sınıfının gerçekleştirdiği adımlar aşağıda açıklanmıştır. Dahil edilen kod snippet'leri Java dilinde olsa ve Tink üçüncü taraf kitaplığını kullansa da bu adımlar, ECDSA'yı destekleyen herhangi bir üçüncü taraf kitaplığı kullanılarak istediğiniz dilde uygulanabilir.

Ortak anahtarları getirme

Ödüllü SSV geri aramasını doğrulamak için AdMob tarafından sağlanan bir ortak anahtara ihtiyacınız vardır.

Ödüllü SSV geri çağırmalarını doğrulamak için kullanılacak ortak anahtarların listesi AdMob anahtar sunucusundan alınabilir. Herkese açık anahtarların listesi, aşağıdaki gibi bir biçime sahip JSON gösterimi olarak sağlanır:

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

Ortak anahtarları almak için AdMob anahtar sunucusuna bağlanıp anahtarları indirin. Aşağıdaki kod bu görevi yerine getirir ve anahtarların JSON gösterimini data değişkenine kaydeder.

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

Genel anahtarların düzenli olarak döndürüldüğünü unutmayın. Yaklaşan bir rotasyon hakkında sizi bilgilendiren bir e-posta alırsınız. Herkese açık anahtarları önbelleğe alıyorsanız bu e-postayı aldıktan sonra anahtarları güncellemeniz gerekir.

Ortak anahtarlar getirildikten sonra ayrıştırılmalıdır. Aşağıdaki parsePublicKeysJson yöntemi, yukarıdaki örnek gibi bir JSON dizesini giriş olarak alır ve key_id değerlerinden Tink kitaplığındaki ECPublicKey nesneleri olarak kapsüllenmiş genel anahtarlara bir eşleme oluşturur.

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

Doğrulanacak içerik alma

Ödüllü SSV geri çağırmalarının son iki sorgu parametresi her zaman signature ve key_id, şeklindedir. Kalan sorgu parametreleri, doğrulanacak içeriği belirtir. AdMob'u ödül geri çağırmalarını https://www.myserver.com/mypath adresine gönderecek şekilde yapılandırdığınızı varsayalım. Aşağıdaki snippet'te, doğrulanacak içeriğin vurgulandığı bir örnek ödüllü SSV geri çağırması gösterilmektedir.

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

Aşağıdaki kodda, doğrulanacak içeriğin bir geri çağırma URL'sinden UTF-8 bayt dizisi olarak nasıl ayrıştırılacağı gösterilmektedir.

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

Geri çağırma URL'sinden imzayı ve key_id değerini alma

Önceki adımdaki queryString değerini kullanarak geri çağırma URL'sindeki signature ve key_id sorgu parametrelerini aşağıdaki gibi ayrıştırın:

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

Doğrulama yapma

Son adım, geri çağırma URL'sinin içeriğini uygun ortak anahtarla doğrulamaktır. parsePublicKeysJson yönteminden döndürülen eşlemeyi alın ve geri çağırma URL'sindeki key_id parametresini kullanarak bu eşlemeden ortak anahtarı alın. Ardından, imzayı bu ortak anahtarla doğrulayın. Bu adımlar aşağıda verify yönteminde gösterilmektedir.

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

Yöntem, istisna hatası vermeden yürütülürse geri çağırma URL'si başarıyla doğrulanmıştır.

SSS

AdMob anahtar sunucusu tarafından sağlanan ortak anahtarı önbelleğe alabilir miyim?

SSV geri aramalarını doğrulamak için gereken işlem sayısını azaltmak amacıyla AdMob anahtar sunucusu tarafından sağlanan ortak anahtarı önbelleğe almanızı öneririz. Ancak ortak anahtarların düzenli olarak döndürüldüğünü ve 24 saatten uzun süre önbelleğe alınmaması gerektiğini unutmayın.

AdMob anahtar sunucusu tarafından sağlanan ortak anahtarlar ne sıklıkta döndürülür?

AdMob anahtar sunucusu tarafından sağlanan ortak anahtarlar, değişken bir takvime göre döndürülür. SSV geri çağırma doğrulamasının beklendiği gibi çalışmaya devam etmesini sağlamak için ortak anahtarlar 24 saatten uzun süre önbelleğe alınmamalıdır.

Sunucuma ulaşılamazsa ne olur?

Google, SSV geri çağırmaları için HTTP 200 OK başarı durumu yanıt kodu bekler. Sunucunuza ulaşılamıyorsa veya beklenen yanıtı vermiyorsa Google, bir saniyelik aralıklarla beş kez SSV geri aramaları göndermeyi yeniden dener.

SSV geri aramalarının Google'dan geldiğini nasıl doğrulayabilirim?

SSV geri çağırmalarının Google'dan kaynaklandığını doğrulamak için ters DNS araması kullanın.