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

Sunucu tarafı doğrulama geri çağırmaları, Google tarafından genişletilen sorgu parametrelerine sahip URL isteklerinden oluşur. Google bu istekleri, kullanıcının ödüllü veya ödüllü geçiş reklamıyla etkileşime geçtiği için ödüllendirilmesi gerektiğini bildirmek üzere harici bir sisteme gönderir. Ödüllü SSV (sunucu tarafı doğrulaması) geri çağırmaları, kullanıcılara ödül vermek için istemci tarafı geri çağırmalarının taklit edilmesine 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 üçüncü taraf kriptografik kitaplığını 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. Sunucunuzu AdMob kullanıcı arayüzündeki test aracı ile de test edebilirsiniz.

Java spring-boot kullanan Ödüllü SSV Örneği'ne göz atın.

Ön koşullar

• Reklam biriminde ödüllü sunucu tarafı doğrulamayı etkinleştirin.

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

Tink Java Apps GitHub deposunda, ödüllü SSV geri çağırması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 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ıya ödül verme bölümünde, kullanıcılara ne zaman ödül verilmesi gerektiğiyle ilgili en iyi uygulamalar ayrıntılı olarak açıklanmaktadır. Ödüllü SSV geri çağırmalarını doğrulamak için bu sınıf tarafından gerçekleştirilen adımların dökümünü Ödüllü SSV'nin manuel olarak doğrulanması bölümünde bulabilirsiniz.

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 olarak 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ğrulaması arasında denge kurmak önemlidir. Sunucu tarafı geri çağırmalarda harici sistemlere ulaşmadan önce gecikmeler yaşanabilir. Bu nedenle, kullanıcıya hemen ödül vermek için istemci tarafı geri çağırma işlevini kullanmak ve sunucu tarafı geri çağırma işlevleri alındıktan sonra tüm ödüllerde doğrulama yapmak 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 (örneğin, ödül uygulamanızın oyun içi ekonomisini etkiliyorsa) ve ödül vermede gecikmelerin kabul edildiği uygulamalarda, doğrulanmış sunucu tarafı geri çağırma işlevini 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. Ödüllü reklam nesnesinde ayarlanan tüm dize değerleri, SSV geri çağırma işlevinin custom_data sorgu parametresine iletilir. Özel veri değeri ayarlanmazsa custom_data sorgu parametresi değeri SSV geri çağırma işlevinde yer almaz.

Aşağıdaki örnekte, ödüllü reklam yüklendikten sonra SSV seçenekleri ayarlanmaktadır:

RewardedAd.load(MainActivity.this, "AD_UNIT_ID",
    new AdRequest.Builder().build(),  new RewardedAdLoadCallback() {
  @Override
  public void onAdLoaded(RewardedAd ad) {
    Log.d(TAG, "Ad was loaded.");
    rewardedAd = ad;
    ServerSideVerificationOptions options = new ServerSideVerificationOptions
        .Builder()
        .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
        .build();
    rewardedAd.setServerSideVerificationOptions(options);
  }
  @Override
  public void onAdFailedToLoad(LoadAdError loadAdError) {
    Log.d(TAG, loadAdError.toString());
    rewardedAd = null;
  }
});

RewardedAd.load(this, "AD_UNIT_ID",
    AdRequest.Builder().build(), object : RewardedAdLoadCallback() {
  override fun onAdLoaded(ad: RewardedAd) {
    Log.d(TAG, "Ad was loaded.")
    rewardedInterstitialAd = ad
    val options = ServerSideVerificationOptions.Builder()
        .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
        .build()
    rewardedAd.setServerSideVerificationOptions(options)
  }

  override fun onAdFailedToLoad(adError: LoadAdError) {
    Log.d(TAG, adError?.toString())
    rewardedAd = null
  }
})

Ö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ü SSV'yi doğrulamak için RewardedAdsVerifier sınıfı tarafından gerçekleştirilen adımlar aşağıda açıklanmıştır. Eklenen kod snippet'leri Java'dadır ve Tink üçüncü taraf kitaplığından yararlanır. Ancak bu adımları, ECDSA'yı destekleyen herhangi bir üçüncü taraf kitaplığı kullanarak istediğiniz dilde uygulayabilirsiniz.

Ortak anahtarları getirme

Ödüllü SSV geri çağırmasını doğrulamak için AdMob tarafından sağlanan bir herkese açık 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ğıdakine benzer bir biçime sahip bir 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ın ve anahtarları indirin. Aşağıdaki kod bu görevi yerine getirir ve anahtarların JSON temsilini 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 değiştirildiğini 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, giriş olarak yukarıdaki örnek gibi bir JSON dizesi alır ve key_id değerlerini, Tink kitaplığındaki ECPublicKey nesneleri olarak kapsüllenen herkese açık anahtarlarla eşler.

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çeriği alma

Ödüllü SSV geri aramalarının son iki sorgu parametresi her zaman bu sırayla signature ve key_id, olur. 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ığı örnek bir ödüllü SSV geri çağırma işlevi 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 imza ve key_id'yi alma

Önceki adımdaki queryString değerini kullanarak geri arama 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 bu eşlemeden herkese açık anahtarı almak için geri çağırma URL'sindeki key_id parametresini kullanın. Ardından, bu ortak anahtarla imzası 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 vermeden yürütülüyorsa 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 çağırmalarının doğrulanması 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, herkese açık 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 programla döndürülür. SSV geri çağırmalarının doğrulamasının amaçlandığı 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ında HTTP 200 OK başarı durum yanıt kodu bekler. Sunucunuza erişilemezse veya beklenen yanıtı vermezse Google, SSV geri aramalarını bir saniyelik aralıklarla beş defaya kadar 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 geldiğini doğrulamak için ters DNS araması yapın.