Verificación del lado del servidor

Las retrollamadas de verificación del lado del servidor (retrollamadas de SSV) son solicitudes de URL con parámetros de consulta mostrados por Google y que Google envía a un sistema externo para notificarle que hay que recompensar a un usuario porque ha interactuado con un anuncio bonificado o un anuncio intersticial bonificado. Las retrollamadas bonificadas de verificación del lado del servidor proporcionan una capa adicional de protección contra el spoofing de retrollamadas del lado del cliente para recompensar a los usuarios.

En esta guía aprenderás a verificar retrollamadas de SSV de anuncios bonificados mediante la biblioteca criptográfica de terceros Tink Java Apps para comprobar la legitimidad de los parámetros de consulta de las retrollamadas. Si bien en esta guía utilizamos Tink, puedes emplear cualquier biblioteca de terceros que sea compatible con ECDSA. También puedes comprobar si tu servidor funciona correctamente con la herramienta de pruebas de la UI de AdMob.

Requisitos previos

• Habilitar en tu bloque de anuncios el sistema de verificación en el servidor para anuncios bonificados.

Usar RewardedAdsVerifier de la biblioteca Tink Java Apps

El repositorio GitHub de Tink Java Apps incluye la clase auxiliar RewardedAdsVerifier, con la que se reduce la cantidad de código necesario para verificar una retrollamada de SSV de anuncio bonificado. Al usar esta clase, puedes verificar una URL de retrollamada con el siguiente código.

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

Si el método verify() se ejecuta sin generar ninguna excepción, la URL de retrollamada se verifica correctamente. En la sección Recompensar a los usuarios puedes consultar las prácticas recomendadas a este respecto. Si prefieres ver un desglose de los pasos que sigue esta clase para verificar las retrollamadas de SSV de anuncios bonificados, consulta la sección Verificación manual de SSVs de anuncios bonificados.

Parámetros de la retrollamada de SSV

Las retrollamadas de verificación del lado del servidor contienen parámetros de consulta que describen la interacción con anuncio bonificado. A continuación se indican los nombres y las descripciones de estos parámetros, así como ejemplos de los valores que utilizan. Todos los parámetros se envían en orden alfabético.

Identificadores de fuentes publicitarias

Recompensar a los usuarios

A la hora de decidir cuándo recompensar a los usuarios, es importante equilibrar la experiencia que les ofreces con el proceso de validación de las bonificaciones. Las retrollamadas del servidor pueden tardar en llegar a los sistemas externos; por tanto, lo más recomendable es usar la retrollamada del cliente para recompensar al usuario de inmediato y validar todas las bonificaciones tras recibir una retrollamada del servidor. Esta estrategia mejora la experiencia de los usuarios, al tiempo que se asegura la validez de las bonificaciones concedidas.

Sin embargo, si la validez de la bonificación es importante (por ejemplo, porque afecta a la economía de tu aplicación durante el juego) y es aceptable que se produzcan ciertos retrasos en la concesión de las bonificaciones, puede que la mejor estrategia sea esperar a la retrollamada de SSV.

Datos personalizados

Las aplicaciones que requieren datos adicionales en las retrollamadas de verificación del lado del servidor deben usar la función de datos personalizados de los anuncios bonificados. Los valores de cadena asignados a un objeto de anuncio bonificado se envían al parámetro de consulta custom_data de la retrollamada de SSV. Si no se asigna ningún valor de datos personalizados, el valor del parámetro de consulta custom_data no estará presente en la retrollamada de SSV.

En el siguiente ejemplo se definen las opciones de SSV después de cargar el anuncio bonificado:

RewardedAd.load(with:"AD_UNIT_ID",
                       request: request,
                       completionHandler: { [self] ad, error in
      if let error != error {
      rewardedAd = ad
      let options = ServerSideVerificationOptions()
      options.customRewardString = "SAMPLE_CUSTOM_DATA_STRING"
      rewardedAd.serverSideVerificationOptions = options
    }
})

GADRequest *request = [GADRequest request];
[GADRewardedAd loadWithAdUnitID:@"AD_UNIT_ID"
                        request:request
              completionHandler:^(GADRewardedAd *ad, NSError *error) {
                if (error) {
                  // Handle Error
                  return;
                }
                self.rewardedAd = ad;
                GADServerSideVerificationOptions *options =
                    [[GADServerSideVerificationOptions alloc] init];
                options.customRewardString = @"SAMPLE_CUSTOM_DATA_STRING";
                ad.serverSideVerificationOptions = options;
              }];

Verificación manual de SSVs de anuncios bonificados

A continuación se describen los pasos que sigue la clase RewardedAdsVerifier para verificar en el servidor un anuncio bonificado. Aunque los fragmentos de código incluidos están en Java y se sirven de la biblioteca de terceros Tink, puedes implementar estos pasos en el lenguaje que prefieras y utilizar cualquier biblioteca de terceros compatible con ECDSA.

Obtener claves públicas

Para verificar una retrollamada de SSV de anuncios bonificados, necesitas una clave pública proporcionada por AdMob.

En el servidor de claves de AdMob hay una lista con las claves públicas que se usan para validar las retrollamadas de SSV de anuncios bonificados. Dicha lista se proporciona como una representación JSON, con un formato similar al siguiente:

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

Para obtener las claves públicas, conéctate al servidor de claves de AdMob y descárgalas. El siguiente código realiza esta tarea y guarda la representación JSON de las claves en la variable 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();
}

Ten en cuenta que las claves públicas rotan periódicamente. Cuando se aproxime una rotación, se te informará por correo electrónico. Si guardas las claves públicas en la caché, cuando recibas dicho mensaje deberás actualizarlas.

Después de obtener las claves públicas, es necesario analizarlas. El método parsePublicKeysJson que aparece a continuación utiliza una cadena JSON como entrada (igual que en el ejemplo anterior), y asigna valores key_id a claves públicas, que se encapsulan como objetos ECPublicKey de la biblioteca 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;
}

Obtener el contenido que hay que verificar

Los dos últimos parámetros de consulta de las retrollamadas de SSV de los anuncios bonificados son siempre signature y key_id,, en ese orden. El resto de los parámetros sirven para especificar qué contenido hay que verificar. Supongamos que has configurado AdMob para enviar retrollamadas de anuncios bonificados a https://www.myserver.com/mypath. En el siguiente fragmento de código se muestra un ejemplo de retrollamada de SSV correspondiente a un anuncio bonificado; el contenido que hay que verificar aparece resaltado.

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

En el siguiente código se muestra cómo analizar el contenido que hay que verificar desde una URL de retrollamada, como una matriz de bytes 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"));

Obtener la firma y el ID de clave de la URL de retrollamada

Usa el valor queryString del paso anterior para analizar los parámetros de consulta signature y key_id de la URL de retrollamada, tal como se muestra a continuació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()));

Realizar la verificación

El último paso es verificar el contenido de la URL de retrollamada mediante la clave pública correspondiente. Utiliza el parámetro key_id de la URL de retrollamada para obtener la clave pública a partir de la asignación que haya devuelto el método parsePublicKeysJson. A continuación, verifica la firma con esa clave pública. Estos pasos se muestran a continuación en el método 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);
  }
}

Si el método se ejecuta sin generar ninguna excepción, la URL de retrollamada se verifica correctamente.

Preguntas frecuentes

¿Puedo almacenar en caché la clave pública que proporciona el servidor de claves de AdMob?

Te recomendamos que lo hagas, ya que así se necesitarán menos operaciones para validar las retrollamadas de SSV. Sin embargo, ten en cuenta que las claves públicas rotan periódicamente y no deben almacenarse en caché durante más de 24 horas.

¿Con qué frecuencia rotan las claves públicas que proporciona el servidor de claves de AdMob?

Rotan con una programación variable. Para que la verificación de las retrollamadas de SSV siga funcionando correctamente, las claves públicas no deben almacenarse en caché durante más de 24 horas.

¿Qué ocurre si no se puede establecer la conexión con mi servidor?

Google espera obtener de las retrollamadas de SSV un código de respuesta de estado correcto (HTTP 200 OK). Si no se puede establecer la conexión con tu servidor o este no proporciona la respuesta esperada, Google intentará enviar de nuevo las retrollamadas de SSV hasta cinco veces, con intervalos de un segundo.

¿Cómo puedo verificar que las retrollamadas de SSV proceden de Google?

Utiliza la petición de DNS invertida para verificar que provienen de Google.