Sunucu tarafı doğrulama geri çağırmaları, sorgu parametreleri Google tarafından genişletilen ve Google tarafından harici bir sisteme gönderilen ve kullanıcının ödüllü veya ödüllü geçiş reklamıyla etkileşim kurduğu için kullanıcının ödüllendirilmesi gerektiğini bildirmek için gönderilen URL istekleridir. Ödüllü SSV (sunucu tarafı doğrulaması) geri çağırmaları, kullanıcıları ödüllendirmek için istemci tarafı geri çağırma adres 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 Uygulamaları üçüncü taraf kriptografi kitaplığını kullanarak ödüllü SSV geri çağırmalarının nasıl doğrulanacağı gösterilmektedir. Tink bu kılavuzun amaçları doğrultusunda kullanılmış olsa da ECDSA'yı destekleyen herhangi bir üçüncü taraf kitaplığı kullanabilirsiniz. Sunucunuzu, AdMob kullanıcı arayüzündeki test aracıyla da test edebilirsiniz.
Java bahar önyüklemesi kullanan bu tam olarak çalışan örneğe göz atın.
Ön koşullar
Google Mobile Ads SDK'sının 11.6.0 veya sonraki bir sürümünü kullanarak ödüllü reklamları mobil uygulamanıza entegre edin.
Reklam biriminizde ödüllü sunucu tarafı doğrulamayı etkinleştirin.
Tink Java Uygulamaları kitaplığından RewardedAdsVerifier'ı kullanın
Tink Java Uygulamaları GitHub deposu, ödüllü SSV geri çağırmasını doğrulamak için gereken kodu azaltmak amacıyla bir RewardedAdsVerifier
yardımcı sınıfı içerir.
Bu sınıfı kullanmak, bir geri çağırma URL'sini aşağıdaki kodla doğrulayabilmenizi sağlar.
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 açıklanır. Ödüllü SSV geri aramalarını doğrulamak amacıyla bu sınıf tarafından gerçekleştirilen adımların dökümünü Ödüllü SSV için manuel doğrulama bölümünden 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.
Parametre Adı | Açıklama | Örnek değer |
---|---|---|
ad_network | Bu reklamı karşılayan reklam kaynağının reklam kaynağı tanımlayıcısı. Kimlik değerlerine karşılık gelen reklam kaynağı adları, Reklam kaynağı tanımlayıcıları bölümünde listelenir. | 1953547073528090325 |
ad_unit | Ödüllü reklam istemek için kullanılan AdMob reklam birimi kimliği. | 2747237135 |
custom_data | Sağladığı özel veri dizesi:
setCustomData
.
Uygulama tarafından herhangi bir özel veri dizesi sağlanmazsa bu sorgu parametresi değeri SSV geri çağırmasında bulunmaz. |
SAMPLE_CUSTOM_DATA_STRING |
key_id | SSV geri aramasını doğrulamak için kullanılacak anahtar. Bu değer, AdMob anahtar sunucusu tarafından sağlanan bir ortak anahtarla eşlenir. | 1234567890 |
reward_amount | Reklam birimi ayarlarında belirtildiği şekilde ödül tutarı. | 5 |
reward_item | Reklam birimi ayarlarında belirtildiği şekilde ödül öğesi. | paralar |
signature | AdMob tarafından oluşturulan SSV geri araması için imza. | MEUCIQCLJS_s4ia_sN06HqzeW7Wc3nhZi4RlW3qV0oO-6AIYdQIgGJEh-rzKreO-paNDbSCzWGMtmgJHYYW9k2_icM9LFMY |
timestamp | Kullanıcının ms cinsinden Dönem zamanı olarak ödüllendirildiği zaman damgası. | 1507770365237823 |
transaction_id | AdMob tarafından oluşturulan her ödül hibesi etkinliği için benzersiz on altılı tanımlayıcı. | 18fa792de1bca816048293fc71035638 |
user_id |
setUserId tarafından sağlanan kullanıcı tanımlayıcısı.
Uygulama tarafından herhangi bir kullanıcı tanımlayıcısı sağlanmazsa bu sorgu parametresi SSV geri çağırmasında yer almaz. |
1234567 |
Reklam kaynağı tanımlayıcıları
Reklam kaynağı adları ve kimlikleri
Reklam kaynağı adı | Reklam kaynağı kimliği |
---|---|
Aarki (teklifli sistem) | 5240798063227064260 |
Reklam oluşturma (teklifli sistem) | 1477265452970951479 |
AdColony | 15586990674969969776 |
AdColony (SDK dışı) (teklifli sistem) | 4600416542059544716 |
AdColony (teklifli sistem) | 6895345910719072481 |
AdFalcon | 3528208921554210682 |
AdMob Ağı | 5450213213286189855 |
ADResult | 10593873382626181482 |
AMoAd | 17253994435944008978 |
Applovin | 1063618907739174004 |
Applovin (teklifli sistem) | 1328079684332308356 |
Chartboost | 2873236629771172317 |
Çikolata Platformu (teklifli sistem) | 6432849193975106527 |
Çapraz Kanal (MdotM) | 9372067028804390441 |
Özel Etkinlik | 18351550913290782395 |
DT Exchange* * Bu ağ, 21 Eylül 2022'den önce "Fyber Pazar Yeri" olarak adlandırılıyordu. | 2179455223494392917 |
EMX (teklifli sistem) | 8497809869790333482 |
Dalgalanma (teklifli sistem) | 8419777862490735710 |
Hafif kar yağışı | 3376427960656545613 |
Fyber* * Bu reklam kaynağı, geçmiş raporlar için kullanılır. | 4839637394546996422 |
i-mobile | 5208827440166355534 |
İyileştirme Dijital (teklifli sistem) | 159382223051638006 |
Dizin Borsası (teklifli sistem) | 4100650709078789802 |
InMobi | 7681903010231960328 |
InMobi (teklifli sistem) | 6325663098072678541 |
IronSource | 6925240245545091930 |
ironSource Reklamları (teklifli sistem) | 1643326773739866623 |
Leadbolt | 2899150749497968595 |
LG U+REKLAM | 18298738678491729107 |
LINE Reklamlar Ağı | 3025503711505004547 |
Maio | 7505118203095108657 |
maio (teklifli sistem) | 1343336733822567166 |
Media.net (teklifli sistem) | 2127936450554446159 |
Uyumlulaştırılmış kurum reklamları | 6060308706800320801 |
Meta Audience Network* * Bu ağ, 6 Haziran 2022'den önce "Facebook Audience Network" olarak adlandırılıyordu. | 10568273599589928883 |
Meta Audience Network (teklifli sistem)* * Bu ağ, 6 Haziran 2022'den önce "Facebook Audience Network (teklifli sistem)" olarak adlandırılıyordu. | 11198165126854996598 |
Mintegral | 1357746574408896200 |
Mintegral (teklifli sistem) | 6250601289653372374 |
MobFox | 8079529624516381459 |
MobFox (teklifli sistem) | 3086513548163922365 |
MoPub (desteği sonlandırılmış) | 10872986198578383917 |
myTarget | 8450873672465271579 |
Nend | 9383070032774777750 |
Nexxen (teklifli sistem)* * Bu ağ, 1 Mayıs 2024'ten önce "UnrulyX" olarak adlandırılıyordu. | 2831998725945605450 |
AOL'den ONE (Millennial Media) | 6101072188699264581 |
AOL'den ONE (Nexage) | 3224789793037044399 |
OneTag Exchange (teklifli sistem) | 4873891452523427499 |
OpenX (teklifli sistem) | 4918705482605678398 |
Pangle (teklifli sistem) | 3525379893916449117 |
PubMatic (teklifli sistem) | 3841544486172445473 |
Rezervasyon kampanyası | 7068401028668408324 |
RhythmOne (teklifli sistem) | 2831998725945605450 |
Rubicon (teklifli sistem) | 3993193775968767067 |
SK gezegeni | 734341340207269415 |
Paylaşım (teklifli sistem) | 5247944089976324188 |
Smaato (teklifli sistem) | 3362360112145450544 |
Equativ (teklifli sistem)* * Bu ağ, 12 Ocak 2023'ten önce "Smart Adserver" olarak adlandırılıyordu. | 5970199210771591442 |
Sonobi (teklifli sistem) | 3270984106996027150 |
Tapjoy | 7295217276740746030 |
Tapjoy (teklifli sistem) | 4692500501762622178 |
Tencent GDT | 7007906637038700218 |
TripleLift (teklifli sistem) | 8332676245392738510 |
Unity Reklamları | 4970775877303683148 |
Unity Reklamları (teklifli sistem) | 7069338991535737586 |
Verizon Media | 7360851262951344112 |
Verve Group (teklifli sistem) | 5013176581647059185 |
Vpon | 1940957084538325905 |
Liftoff Para Kazanma* * Bu ağ, 30 Ocak 2023'ten önce "Vungle" olarak adlandırılıyordu. | 1953547073528090325 |
Liftoff Para Kazanma (teklifli sistem)* * Bu ağ, 30 Ocak 2023'ten önce "Vungle (teklifli sistem)" olarak adlandırılıyordu. | 4692500501762622185 |
Yieldmo (teklifli sistem) | 4193081836471107579 |
YieldOne (teklifli sistem) | 3154533971590234104 |
Zucks | 5506531810221735863 |
Kullanıcıyı ödüllendirme
Kullanıcıyı ne zaman ödüllendireceğinize karar verirken kullanıcı deneyimi ile doğrulamayı dengelemek önemlidir. Sunucu tarafı geri çağırma işlemleri, harici sistemlere ulaşmadan önce gecikmeler yaşayabilir. Bu nedenle, önerilen en iyi uygulama, sunucu tarafı geri çağırmalar alındığında tüm ödüller için doğrulama gerçekleştirirken kullanıcıyı hemen ödüllendirmek için istemci taraflı geri çağırmanın kullanılmasıdır. Bu yaklaşım, verilen ödüllerin geçerliliğini sağlarken iyi bir kullanıcı deneyimi sağlar.
Bununla birlikte, ödül geçerliliğinin kritik olduğu (örneğin, ödül, uygulamanızın oyun içi ekonomisini etkileyen) ve ödül vermede gecikmelerin kabul edilebilir olduğu uygulamalar için doğrulanmış sunucu tarafının geri aranmasını 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 herhangi bir dize değeri, SSV geri çağırmasının custom_data
sorgu parametresine iletilir. Herhangi bir özel veri değeri ayarlanmazsa custom_data
sorgu parametresi değeri SSV geri çağırmasında yer almaz.
Aşağıdaki kod örneğinde, ödüllü reklam yüklendikten sonra SSV seçeneklerinin nasıl ayarlanacağı gösterilmektedir.
Java
RewardedAd.load(MainActivity.this, "ca-app-pub-3940256099942544/5354046379", 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; } });
Kotlin
RewardedAd.load(this, "ca-app-pub-3940256099942544/5354046379", 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 doğrulaması
Ödüllü SSV'yi doğrulamak için RewardedAdsVerifier
sınıfı tarafından gerçekleştirilen adımlar aşağıda özetlenmiştir. Dahil edilen kod snippet'leri Java'da olsa ve Tink üçüncü taraf kitaplığından yararlansa da bu adımları ECDSA'yı destekleyen herhangi bir üçüncü taraf kitaplığı kullanarak istediğiniz dilde uygulayabilirsiniz.
Ortak anahtarları getir
Ödüllü SSV geri çağırması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 genel anahtarların listesi, AdMob anahtar sunucusundan alınabilir. Ortak anahtarların listesi, aşağıdakine benzer bir biçimde 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 tamamlar 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();
}
Ortak anahtarların düzenli olarak döndürüldüğünü unutmayın. Rotasyon tarihi belli olan bir e-posta alacaksınız. Ortak anahtarları önbelleğe alıyorsanız bu e-postayı aldıktan sonra anahtarları güncellemeniz gerekir.
Ortak anahtarlar getirildikten sonra ayrıştırılmaları gerekir. Aşağıdaki parsePublicKeysJson
yöntemi, yukarıdaki örnekte olduğu gibi bir JSON dizesini giriş olarak alır ve key_id
değerlerinden ortak anahtarlara eşleme oluşturur. Bunlar Tink kitaplığından ECPublicKey
nesneleri olarak kapsüllenir.
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;
}
İçeriğin doğrulanmasını sağlayın
Ödüllü SSV geri çağırmaları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 https://www.myserver.com/mypath
adresine ödül geri çağırmaları gönderecek şekilde yapılandırdığınızı varsayalım. Aşağıdaki snippet'te, doğrulanacak içeriğin vurgulandığı bir ödüllü SSV geri çağırma örneği gösterilmektedir.
https://www.myserver.com/path?ad_network=54...55&ad_unit=12345678&reward_amount=10&reward_item=coins ×tamp=150777823&transaction_id=12...DEF&user_id=1234567&signature=ME...Z1c&key_id=1268887
Aşağıdaki kod, geri çağırma URL'sinden UTF-8 bayt dizisi olarak doğrulanacak içeriğin nasıl ayrıştırılacağını gösterir.
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 değerini alma
Önceki adımda yer alan queryString
değerini kullanarak, geri çağırma URL'sindeki signature
ve key_id
sorgu parametrelerini aşağıda gösterildiği 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 gerçekleştirme
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 ortak anahtarı almak için geri çağırma URL'sindeki key_id
parametresini kullanın. Ardından imzayı bu ortak anahtarla doğrulayın. Bu adımlar, aşağıda verify
yönteminde gösterilmiştir.
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 bildirilmeden 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. Bununla birlikte, ortak anahtarların düzenli olarak döndürüldüğünü ve 24 saatten uzun süre önbellekte tutulmaması gerektiğini unutmayın.
- AdMob anahtar sunucusu tarafından sağlanan ortak anahtarlar ne sıklıkta döndürülüyor?
- AdMob anahtar sunucusu tarafından sağlanan ortak anahtarlar, değişken bir plana göre dönüşümlü olarak yayınlanır. SSV geri aramalarının doğrulanmasının istenen şekilde çalışmaya devam etmesini sağlamak için ortak anahtarlar, 24 saatten uzun süre önbelleğe alınmamalıdır.
- Sunucuma erişilemiyorsa ne olur?
- Google, SSV geri çağırmaları için
HTTP 200 OK
başarı durumu yanıt kodu bekler. Sunucunuza ulaşılamazsa veya beklenen yanıtı sağlamazsa Google, SSV geri aramalarını bir saniyelik aralıklarla beş kereye kadar göndermeyi tekrar dener. - SSV geri aramalarının Google'dan geldiğini nasıl doğrulayabilirim?
- SSV geri aramalarının Google kaynaklı olduğunu doğrulamak için ters DNS aramasını kullanın.