서버 측 인증 (SSV) 콜백 확인

서버 측 확인 콜백은 Google에서 외부 시스템으로 전송하여 Google에서 확장하는 쿼리 매개변수가 포함된 URL 요청입니다. 이를 통해 보상형 광고 또는 보상형 전면 광고와의 상호작용에 대해 사용자에게 보상해야 함을 알립니다. 보상형 SSV (서버 측 확인) 콜백은 클라이언트 측 콜백 스푸핑에 대한 추가 보호 계층을 제공하여 사용자에게 보상합니다.

이 가이드에는 Tink Java 앱 서드 파티 암호화 라이브러리를 사용해 보상형 SSV 콜백을 확인하여 콜백의 쿼리 매개변수가 올바른 값인지 확인하는 방법이 나와 있습니다. 이 가이드에서는 Tink를 사용하지만 ECDSA를 지원하는 서드 파티 라이브러리를 사용할 수 있습니다. AdMob UI에서 테스트 도구를 사용하여 서버를 테스트할 수도 있습니다.

자바 스프링 부팅을 사용하는 완전히 작동하는 예를 확인하세요.

기본 요건

Tink Java 앱 라이브러리에서 RewardedAdsVerifier 사용

Tink Java 앱 GitHub 저장소에는 RewardedAdsVerifier 도우미 클래스가 포함되어 있어 보상형 SSV 콜백을 확인하는 데 필요한 코드를 줄여줍니다. 이 클래스를 사용하면 다음 코드로 콜백 URL을 확인할 수 있습니다.

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

예외를 발생시키지 않고 verify() 메서드를 실행하여 콜백 URL을 성공적으로 확인했습니다. 사용자에 대한 보상 섹션에서는 사용자가 보상을 받는 경우에 대한 권장사항을 자세히 설명합니다. 보상형 SSV 콜백을 인증하기 위해 이 클래스에서 수행하는 단계를 자세히 알아보려면 보상형 SSV 수동 인증 섹션을 참고하세요.

SSV 콜백 매개변수

서버 측 인증 콜백에는 보상형 광고 상호작용을 설명하는 쿼리 매개변수가 포함됩니다. 매개변수 이름, 설명 및 예시 값은 다음과 같습니다. 매개변수는 알파벳순으로 전송됩니다.

매개변수 이름 설명 예시 값
ad_network 이 광고를 처리한 광고 소스의 광고 소스 식별자입니다. ID 값에 해당하는 광고 소스 이름이 광고 소스 식별자 섹션에 표시됩니다. 1953547073528090325
ad_unit 보상형 광고를 요청할 때 사용된 AdMob 광고 단위 ID입니다. 2747237135
custom_data 에서 제공한 맞춤 데이터 문자열입니다.

앱에서 맞춤 데이터 문자열을 제공하지 않으면 이 쿼리 매개변수 값이 SSV 콜백에 표시되지 않습니다.

 SAMPLE_CUSTOM_DATA_STRING
key_id SSV 콜백을 인증하는 데 사용되는 키입니다. 이 값은 AdMob 키 서버에서 제공하는 공개 키에 매핑됩니다. 1234567890
reward_amount 광고 단위 설정에 지정된 보상 금액입니다. 5
reward_item 광고 단위 설정에 지정된 대로 보상을 제공합니다. 동전
서명 AdMob에서 생성한 SSV 콜백 서명입니다. MEUCIQCLJS_s4ia_sN06HqzeW7Wc3nhZi4RlW3qV0oO-6AIYdQIgGJEh-rzKreO-paNDbSCzWGMtmgJHYYW9k2_icM9LFMY
timestamp 사용자가 보상을 받은 시간의 타임스탬프입니다(에포크 시간, 밀리초). 1507770365237823
transaction_id AdMob에서 생성된 각 보상 이벤트의 고유한 16진수 코드 식별자입니다. 18fa792de1bca816048293fc71035638
user_id SetUserId를 참조하세요.

앱에서 사용자 식별자를 제공하지 않으면 이 쿼리 매개변수는 SSV 콜백에 표시되지 않습니다.

 1234567

광고 소스 식별자

광고 소스 이름 및 ID

광고 소스 이름 광고 소스 ID
Aarki (입찰)5240798063227064260
광고 생성 (입찰)1477265452970951479
AdColony15586990674969969776
AdColony (비 SDK) (입찰)4600416542059544716
AdColony (입찰)6895345910719072481
AdFalcon3528208921554210682
AdMob 네트워크5450213213286189855
ADResult10593873382626181482
AMoAd17253994435944008978
아플로빈1063618907739174004
Applovin (입찰)1328079684332308356
차트부스트2873236629771172317
Chocolate Platform (입찰)6432849193975106527
CrossChannel (MdotM)9372067028804390441
맞춤 이벤트18351550913290782395
DT Exchange*
* 2022년 9월 21일 이전에는 이 네트워크를 'Fyber Marketplace'라고 했습니다.		2179455223494392917
EMX (입찰)8497809869790333482
Fluct (입찰)8419777862490735710
Flurry3376427960656545613
Fyber*
* 이 광고 소스는 이전 보고서에 사용됩니다.		4839637394546996422
i-mobile5208827440166355534
Enhanced Digital (입찰)159382223051638006
Index Exchange (입찰)4100650709078789802
InMobi7681903010231960328
InMobi (입찰)6325663098072678541
IronSource6925240245545091930
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
민테그랄1357746574408896200
Mintegral (입찰)6250601289653372374
MobFox8079529624516381459
MobFox (입찰)3086513548163922365
MoPub (지원 중단됨)10872986198578383917
myTarget8450873672465271579
Nend9383070032774777750
ONE by AOL (Millennial Media)6101072188699264581
ONE by AOL (Nexage)3224789793037044399
OneTag Exchange (입찰)4873891452523427499
OpenX (입찰)4918705482605678398
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
UnrulyX (입찰)2831998725945605450
버라이즌 미디어7360851262951344112
Verve Group (입찰)5013176581647059185
폰1940957084538325905
Liftoff 수익 창출*

* 2023년 1월 30일 이전에는 이 네트워크를 'Vungle'이라 했습니다.

1953547073528090325
Liftoff Monetize (입찰)*

* 2023년 1월 30일 이전에는 이 네트워크를 'Vungle (입찰)'이라고 했습니다.

4692500501762622185
Yieldmo (입찰)4193081836471107579
YieldOne (입찰)3154533971590234104
Zucks5506531810221735863

사용자 보상

사용자에게 보상을 제공할 시점을 결정할 때는 사용자 경험과 보상 검증의 균형을 유지하는 것이 중요합니다. 서버 측 콜백은 외부 시스템에 도달하기 전에 지연이 발생할 수 있습니다. 따라서 클라이언트 측 콜백을 사용하여 사용자에게 즉시 보상하고, 서버 측 콜백을 수신하는 즉시 모든 보상에 대해 유효성 검사를 실행하는 것이 좋습니다. 이 접근 방식은 제공된 리워드의 유효성을 보장하는 동시에 우수한 사용자 환경을 제공합니다.

그러나 리워드의 유효성이 중요하고 (예: 리워드가 앱의 게임 내 경제에 영향을 미치는 경우) 리워드 제공 지연이 허용되는 애플리케이션의 경우 인증된 서버 측 콜백을 기다리는 것이 가장 좋은 방법일 수 있습니다.

맞춤 데이터

서버 측 확인 콜백에서 추가 데이터가 필요한 앱은 보상형 광고의 맞춤 데이터 기능을 사용해야 합니다. 보상형 광고 객체에 설정된 모든 문자열 값은 SSV 콜백의 custom_data 쿼리 매개변수에 전달됩니다. 맞춤 데이터 값이 설정되지 않은 경우 custom_data 쿼리 매개변수 값은 SSV 콜백에 표시되지 않습니다.

다음 코드 샘플은 보상형 광고가 로드된 후 SSV 옵션을 설정하는 방법을 보여줍니다.

void HandleRewardedAdLoaded(RewardedAd ad, AdFailedToLoadEventArgs error)
{
    // Create and pass the SSV options to the rewarded ad.
    var options = new ServerSideVerificationOptions
                          .Builder()
                          .SetCustomData("SAMPLE_CUSTOM_DATA_STRING")
                          .Build()
    ad.SetServerSideVerificationOptions(options);
}

광고를 게재하기 전에 맞춤 보상 문자열을 설정해야 합니다.

보상형 SSV의 수동 인증

RewardedAdsVerifier 클래스가 보상형 SSV를 인증하기 위해 수행하는 단계는 다음과 같습니다. 포함된 코드 스니펫이 자바로 되어 있고 Tink 제3자 라이브러리를 활용해도 이 단계는 ECDSA를 지원하는 서드 파티 라이브러리를 통해 원하는 언어로 구현할 수 있습니다.

공개 키 가져오기

보상형 SSV 콜백을 인증하려면 AdMob에서 제공하는 공개 키가 필요합니다.

보상형 SSV 콜백을 확인하는 데 사용되는 공개 키의 목록은 AdMob 키 서버에서 가져올 수 있습니다. 공개 키 목록은 다음과 비슷한 형식의 JSON 표현으로 제공됩니다.

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

공개 키를 검색하려면 AdMob 키 서버에 연결하고 키를 다운로드하세요. 다음 코드에서는 이 작업을 처리하고 키의 JSON 표현을 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();
}

공개 키는 정기적으로 순환됩니다. 예정된 순환을 알리는 이메일이 전송됩니다. 공개 키를 캐시하는 경우 이 이메일을 받으면 키를 업데이트해야 합니다.

가져온 공개 키는 파싱해야 합니다. 아래의 parsePublicKeysJson 메서드는 위의 예시와 같은 JSON 문자열을 입력으로 사용하여 key_id 값을 공개 키로 매핑합니다. 이 공개 키는 Tink 라이브러리의 ECPublicKey 객체로 캡슐화됩니다.

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

인증할 콘텐츠 받기

보상형 SSV 콜백의 마지막 두 쿼리 매개변수는 항상 signature와 key_id, 순서입니다. 나머지 쿼리 매개변수는 확인할 콘텐츠를 지정합니다. 보상 콜백을 https://www.myserver.com/mypath로 보내도록 AdMob을 구성했다고 가정해 보겠습니다. 아래 스니펫은 인증할 콘텐츠가 강조표시된 보상형 SSV 콜백의 예를 보여줍니다.

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

아래 코드는 인증할 콘텐츠를 UTF-8 바이트 배열로 콜백 URL에서 파싱하는 방법을 보여줍니다.

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

콜백 URL에서 서명 및 키 ID 가져오기

이전 단계의 queryString 값을 사용하여 아래와 같이 콜백 URL의 signature 및 key_id 쿼리 매개변수를 파싱합니다.

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

인증 실행

마지막 단계는 적절한 공개 키로 콜백 URL의 콘텐츠를 확인하는 것입니다. parsePublicKeysJson 메서드에서 반환된 매핑을 가져와서 콜백 URL의 key_id 매개변수를 사용하여 해당 매핑에서 공개 키를 가져옵니다. 그런 다음 이 공개 키로 서명을 확인합니다. 이 단계는 아래의 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);
  }
}

메서드가 예외 없이 실행되면 콜백 URL이 성공적으로 인증된 것입니다.

FAQ

AdMob 키 서버에서 제공하는 공개 키를 캐시할 수 있나요?
SSV 콜백을 검증하는 데 필요한 작업 수를 줄이려면 AdMob 키 서버에서 제공하는 공개 키를 캐시하는 것이 좋습니다. 그러나 공개 키는 정기적으로 순환되며 24시간 이상 캐시해서는 안 됩니다.
AdMob 키 서버에서 제공하는 공개 키는 얼마나 자주 순환되나요?
AdMob 키 서버에서 제공하는 공개 키는 다양한 일정으로 순환됩니다. SSV 콜백 확인이 의도한 대로 계속 작동하도록 하려면 공개 키를 24시간 이상 캐시해서는 안 됩니다.
서버에 연결할 수 없으면 어떻게 되나요?
Google은 SSV 콜백에 대한 HTTP 200 OK 성공 상태 응답 코드를 예상합니다. 서버에 연결할 수 없거나 예상 응답을 제공하지 않는 경우 Google은 1초 간격으로 최대 5회 SSV 콜백을 전송하려고 다시 시도합니다.
SSV 콜백이 Google에서 전송되는지 확인하려면 어떻게 해야 하나요?
SSV 콜백이 Google에서 전송되는지 확인하려면 역방향 DNS 조회를 사용합니다.