Проверка на стороне сервера

Обратные вызовы проверки на стороне сервера – это запросы URL с параметрами запроса, которые расширяются Google и отправляются Google во внешнюю систему, чтобы уведомить ее о том, что пользователь должен получить вознаграждение за взаимодействие с объявлением с вознаграждением или межстраничным объявлением с вознаграждением. Обратные вызовы для проверки на стороне сервера (SSV) объявлений с вознаграждением обеспечивают дополнительную защиту от подделки обратных вызовов на стороне клиента, предназначенных для выдачи вознаграждения пользователям.

В этом руководстве рассказывается, как проверять обратные вызовы SSV для объявлений с вознаграждением с помощью сторонней криптографической библиотеки Tink Java Apps, чтобы убедиться, что параметры запроса в обратном вызове являются действительными. В этом руководстве используется библиотека Tink, но вы можете выбрать любую стороннюю библиотеку, которая поддерживает ECDSA. Вы также можете протестировать свой сервер с помощью инструмента тестирования в интерфейсе AdMob.

Требования

• Включите проверку на стороне сервера для объявлений с вознаграждением в рекламном блоке.

Как использовать RewardedAdsVerifier из библиотеки Tink Java Apps

В репозитории GitHub Tink Java Apps есть вспомогательный класс 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

Обратные вызовы проверки на стороне сервера содержат параметры запроса, описывающие взаимодействие с объявлением с вознаграждением. Ниже приведены названия, описания и примеры значений параметров. Параметры отправляются в алфавитном порядке.

Идентификаторы источников объявлений

Вознаграждение для пользователя

При определении момента, когда пользователь должен получить вознаграждение, важно соблюдать баланс между удобством и проверкой. При использовании обратных вызовов на стороне сервера возможны задержки при передаче данных во внешние системы. Поэтому мы рекомендуем использовать клиентский обратный вызов, чтобы сразу же начислять пользователю вознаграждение, и выполнять проверку всех вознаграждений при получении серверных обратных вызовов. Такой подход позволяет обеспечить удобство для пользователей и гарантировать действительность полученных вознаграждений.

Однако если срок действия награды критически важен (например, она влияет на экономику игры) и задержка в ее предоставлении допустима, то лучше дождаться подтвержденного обратного вызова на стороне сервера.

Специальные данные

Если приложению требуются дополнительные данные в обратных вызовах для проверки на стороне сервера, используйте функцию пользовательских данных в объявлениях с вознаграждением. Любое строковое значение, заданное в объекте объявления с вознаграждением, передается в параметр запроса custom_data обратного вызова SSV. Если значение специальных данных не задано, значение параметра запроса custom_data не будет присутствовать в обратном вызове SSV.

В примере ниже показано, как задать параметры SSV после загрузки объявления с вознаграждением:

RewardedAd.load(
  adUnitId: "_adUnitId",
  request: AdRequest(),
  rewardedAdLoadCallback: RewardedAdLoadCallback(
    onAdLoaded: (ad) {
      ServerSideVerificationOptions _options =
          ServerSideVerificationOptions(
            customData: 'SAMPLE_CUSTOM_DATA_STRING',
          );
      ad.setServerSideOptions(_options);
      _rewardedAd = ad;
    },
    onAdFailedToLoad: (error) {},
  ),
);
rewarded_ad_snippets.dart

Замените SAMPLE_CUSTOM_DATA_STRING собственными данными.

Если вы хотите задать строку для специальной награды, это нужно сделать до показа объявления.

Проверка SSV для объявлений с вознаграждением вручную

Ниже описаны действия, которые выполняет класс RewardedAdsVerifier для проверки SSV с вознаграждением. Хотя приведенные фрагменты кода написаны на языке Java и используют стороннюю библиотеку Tink, вы можете выполнить эти действия на любом языке программирования, используя любую стороннюю библиотеку, которая поддерживает 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 с открытыми ключами, которые инкапсулируются как объекты ECPublicKey из библиотеки 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;
}

Как получить контент для проверки

Последние два параметра запроса в обратных вызовах SSV для объявлений с вознаграждением всегда имеют значения signature и key_id, (в указанном порядке). Остальные параметры запроса указывают на контент, который нужно проверить. Предположим, вы настроили AdMob так, чтобы обратные вызовы с информацией о вознаграждении отправлялись в https://www.myserver.com/mypath. Во фрагменте кода ниже показан пример обратного вызова 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

В приведенном ниже коде показано, как проанализировать контент, который нужно проверить, из URL обратного вызова в виде массива байтов 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"));

Как получить подпись и key_id из URL обратного вызова

Используя значение queryString из предыдущего шага, извлеките параметры запроса signature и key_id из URL обратного вызова, как показано ниже.

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, и используйте параметр key_id из URL обратного вызова, чтобы получить открытый ключ из этого сопоставления. Затем проверьте подпись с помощью этого открытого ключа. Ниже описаны шаги для метода 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 обратного вызова успешно проверен.

Часто задаваемые вопросы

Можно ли кешировать открытый ключ, предоставленный сервером ключей AdMob?

Рекомендуем кешировать открытый ключ, предоставленный сервером ключей AdMob, чтобы уменьшить количество операций, необходимых для проверки обратных вызовов SSV. Однако обратите внимание, что открытые ключи регулярно меняются, поэтому их не следует кешировать более чем на 24 часа.

Как часто меняются открытые ключи, предоставляемые сервером ключей AdMob?

Открытые ключи, предоставленные сервером ключей AdMob, меняются по переменному расписанию. Чтобы проверка обратных вызовов SSV работала корректно, не кешируйте открытые ключи дольше 24 часов.

Что произойдет, если сервер будет недоступен?

Google ожидает, что в ответ на обратные вызовы SSV будет возвращаться код статуса HTTP 200 OK. Если сервер недоступен или не предоставляет ожидаемый ответ, Google повторит попытку отправить обратные вызовы SSV до пяти раз с интервалом в одну секунду.

Как проверить, что обратные вызовы SSV приходят от Google?

Используйте обратный DNS-запрос, чтобы убедиться, что обратные вызовы SSV поступают от Google.