Acceso anticipadoSolo por invitación, y los SDK aún no están publicados.Pedir una invitación
Ir al contenido
Docs

Eventos verificados

Los eventos enviados con una clave de servidor, o por tu propia app de Apple o Android con la prueba del dispositivo, se marcan como verificados, para que los distingas de los que podría haber enviado cualquiera con la clave pública.

Una clave de ingesta va dentro de tu app o de tu página web, así que cualquiera puede copiarla y enviar eventos que parezcan de tu app. Lyrelog marca como verificados (verified) los eventos que sí puede distinguir de esos, de tres maneras:

  • los eventos enviados con una clave de servidor, un secreto que solo tienen tus servidores,
  • los eventos enviados por tu propia app de Apple en un dispositivo real, algo que Apple demuestra con App Attest, y
  • los eventos enviados por tu propia app de Android en un dispositivo real, algo que el hardware seguro del dispositivo demuestra con Key Attestation.

Qué significa verificado

Un evento verificado no puede haberlo enviado alguien que copió la clave pública de una app o de una página web. Con una clave de servidor, llegó con una clave que solo tienen los servidores del proyecto. Con App Attest, llegó desde la app auténtica del proyecto, firmada por su equipo, en un dispositivo Apple auténtico. Con Key Attestation, llegó desde la app de Android auténtica del proyecto, firmada con el certificado del proyecto, en un dispositivo Android real con su sistema original y bloqueado.

No demuestra que lo que dice el evento sea cierto. Un servidor puede enviar un valor erróneo, y alguien que use la app real en un dispositivo con jailbreak podría seguir haciendo que envíe eventos. Un evento verificado solo es tan fiable como el código que lo envió.

Los eventos enviados con la clave de ingesta pública y sin prueba de la app no están verificados: cualquiera con esa clave podría haber enviado eventos idénticos. Son la mayoría de los eventos de las páginas web y de las apps que no usan App Attest ni Key Attestation, y es lo esperado.

Quién verifica

RemitenteClaveSus eventosverified_by
Tu servidorSend events from a server, lyr_srv_Verificadosserver
Tu app de Apple en un iPhone, iPad o Apple Watch real, configurada para App AttestSend events, lyr_ing_Verificadosapp_attest
Tu app de Android en un dispositivo real, configurada para Key AttestationSend events, lyr_ing_Verificadoskey_attestation
Cualquier otra cosa con la clave de ingestaSend events, lyr_ing_No verificadosvacío
Cualquier cosa con una clave de acceso totalFull access, lyr_adm_No verificadosvacío

Lyrelog fija esto en cada evento durante la ingesta, a partir de la clave con la que llegó el lote y, para una clave de ingesta, del token de App Attest o de Key Attestation que lleva. Un cliente no puede fijarlo: una línea que envíe verified_by por su cuenta se rechaza con unknown fields: verified_by.

Una clave de servidor solo puede añadir eventos, como una clave de ingesta; no puede leerlos. Consulta Claves para ver cómo crear una.

En el panel

  • En la lista de eventos, un pequeño escudo junto al nombre del evento señala un evento verificado.
  • Un evento abierto muestra una insignia Verified en su cabecera. En Context, Sender dice Verified, server key, Verified, App Attest, Verified, Key Attestation o Not verified, public key.
  • En el explorador, el menú Filter tiene un campo Verified by con los valores Server key, App Attest, Key Attestation y Not verified (en la URL: server, app_attest, key_attestation y none). Elige todos menos Not verified para ver solo los eventos verificados, o Not verified para ver el resto.

La API de lectura devuelve verified_by en cada evento ("server", "app_attest", "key_attestation", o "" si no está verificado) y filtra por él con verified=server, verified=app_attest, verified=key_attestation o verified=none, o con varios a la vez (verified=server|app_attest|key_attestation).

Servidores

Un backend (Node, Python, Go, Java o Kotlin en la JVM, o curl desde un servidor) debería enviar con una clave de servidor, lyr_srv_...: sus eventos quedan verificados y no están sujetos a la cuota diaria de una dirección. Dale al SDK la clave de servidor donde los ejemplos ponen lyr_ing_...; nada más cambia.

Guárdala como cualquier secreto: en el entorno de tu servidor o en su almacén de secretos, nunca en una app, una página web o un repositorio. Si se filtra, revócala y crea otra.

Apps de Apple (App Attest)

App Attest de Apple permite que una app demuestre a un servidor que es la app auténtica, firmada por su equipo, ejecutándose en un dispositivo Apple auténtico. El SDK de Swift lo hace por ti, y también los SDK de React Native y Flutter en iOS, a través del SDK de Swift. Lyrelog guarda como verificados los eventos de una app que lo ha demostrado (verified_by es app_attest).

Configúralo

  1. Busca el App ID de tu app: tu Team ID, un punto y el bundle id, como ABCDE12345.com.example.app. El Team ID está en tu cuenta de Apple Developer, en Membership.
  2. En Lyrelog, abre Project settings. La sección Verified events from your Apple apps aparece cuando el proyecto tiene la plataforma de app de iOS. Añade el App ID con Add. Un propietario puede añadir hasta 10, uno por app (una app de iPhone y su app de reloj tienen bundle ids distintos).
  3. En Xcode, añade la capability App Attest al target de la app (Signing & Capabilities). Es el entitlement com.apple.developer.devicecheck.appattest-environment. Ponlo en production para las builds de la App Store y de TestFlight. Sin él, Apple usa su entorno de desarrollo, que también verifica.
  4. Usa el SDK de Swift. Su opción appAttest es true por defecto, así que no hay nada más que programar. Lo mismo vale para React Native y Flutter (su opción es attest): los ajustes del proyecto son los mismos, porque el trabajo lo hace el SDK de Swift que tienen debajo.

Para desactivarlo, quita los App ID (los eventos llegan sin verificar, como antes) o pon appAttest: false en la app.

Cómo funciona

  • Una vez por instalación, el SDK crea una clave en el Secure Enclave del dispositivo y Apple la certifica respondiendo a un desafío de un solo uso que envía Lyrelog. Lyrelog comprueba la cadena de certificados de Apple y que la app es uno de los App ID del proyecto, y guarda la mitad pública de la clave: una por instalación, que se borra tras 180 días sin usarse.
  • Después el SDK obtiene un token, válido durante un día, y lo envía con cada lote. Renueva el token con una firma de esa clave (una aserción), cuyo contador no se puede reutilizar.
  • El envío nunca espera a esto. Mientras la app no tiene token, y siempre que algo falla, los eventos se envían y se guardan sin verificar. Nunca se rechaza un lote por culpa de App Attest.

Dónde no se aplica

App Attest funciona en iPhones, iPads y Apple Watches reales. Estos envían eventos sin verificar, aunque todo esté configurado:

  • los Mac (Apple no ofrece App Attest en ellos),
  • el simulador,
  • la mayoría de las extensiones de app,
  • los dispositivos que no admiten App Attest.

Las rutas y el header están en la API HTTP.

Aceptar solo eventos verificados de la app de iOS

Desactivado por defecto. En la misma sección de ajustes, Accept only verified events from the iOS app hace que Lyrelog retenga todos los lotes sin verificar cuyos eventos digan platform: ios: responde 425 Too Early, y el SDK conserva el lote y lo vuelve a enviar más tarde. Los primeros eventos de una instalación nueva esperan unos segundos a su token y luego llegan verificados, así que ahí no se pierde nada.

Actívalo solo cuando todo el mundo tenga una versión de la app con App Attest configurado. Hasta entonces, los eventos de versiones anteriores, del simulador y de una app de iPad que se ejecute en un Mac no podrán verificarse nunca: esperan en el dispositivo, hasta lo que guarda el SDK (20 MB y 7 días), y nunca se guardan. Los eventos de otras plataformas, y los de una clave de servidor, se aceptan como antes.

Apps de Android (Key Attestation)

Key Attestation de Android permite que una app cree una clave dentro del hardware seguro del teléfono (su entorno de ejecución de confianza, o un chip StrongBox) y obtenga del dispositivo una cadena de certificados, firmada hasta llegar a Google, que describe la clave, la app y el estado del teléfono. Lyrelog comprueba esa cadena por su cuenta: no hace falta cuenta de Google, Play Integrity ni proyecto de Google Cloud. El SDK de Android lo hace por ti, y también los SDK de React Native y Flutter en Android, a través del SDK de Android. Lyrelog guarda como verificados los eventos de una app que lo ha demostrado (verified_by es key_attestation).

Configúralo

  1. Busca el paquete de tu app (su application id, como com.example.app) y la huella SHA-256 del certificado con el que está firmada:
    • En las builds instaladas desde Google Play, Google firma la app: en Play Console, abre la app, luego Test and release, App integrity, y copia el SHA-256 de App signing key certificate.
    • En las builds que firmas tú (con una clave de subida, o la clave de depuración en desarrollo), ejecuta ./gradlew signingReport y copia el SHA-256 de esa variante.
  2. En Lyrelog, abre Project settings. La sección Verified events from your Android apps aparece cuando el proyecto tiene la plataforma de app de Android. Añade el paquete y la huella con Add; vuelve a añadir el mismo paquete con otra huella por cada certificado que firme builds que envían eventos (hasta 5 por paquete, 10 paquetes).
  3. Usa el SDK de Android. Su opción attest es true por defecto, así que no hay nada más que programar. Lo mismo vale para React Native y Flutter: los ajustes del proyecto son los mismos, porque el trabajo lo hace el SDK de Android que tienen debajo. En un proyecto de React Native o Flutter, ./gradlew signingReport se ejecuta en la carpeta android de la app.

Para desactivarlo, quita los paquetes (los eventos llegan sin verificar, como antes) o pon attest = false en la app.

Qué se comprueba

  • La cadena está firmada, certificado a certificado, hasta una de las raíces de atestación de Google, y ninguno de sus certificados está en la lista de revocados de Google.
  • La clave vive en el hardware seguro del teléfono, se creó ahí y responde a un desafío de un solo uso de Lyrelog.
  • El teléfono arrancó su sistema original y verificado, y su bootloader está bloqueado.
  • La app es uno de los paquetes del proyecto, firmada con uno de sus certificados.

Después Lyrelog guarda la mitad pública de la clave (una por instalación, que se borra tras 180 días sin usarse) y le da a la app un token, válido durante un día, que envía con cada lote. Renueva el token firmando con esa clave un nuevo desafío de un solo uso. El envío nunca espera a esto: mientras la app no tiene token, y siempre que algo falla, los eventos se envían y se guardan sin verificar. Nunca se rechaza un lote por culpa de Key Attestation.

Dónde no se aplica

Estos envían eventos sin verificar, aunque todo esté configurado:

  • los emuladores (no tienen hardware seguro y sus cadenas no llevan a Google),
  • los teléfonos rooteados, con el bootloader desbloqueado o con un sistema personalizado,
  • los teléfonos sin claves respaldadas por hardware (raros desde Android 8),
  • las builds firmadas con un certificado que el proyecto no tiene en su lista.

Las rutas están en la API HTTP.

Aceptar solo eventos verificados de la app de Android

Desactivado por defecto, y funciona como el de iOS: si está activado, todos los lotes sin verificar cuyos eventos digan platform: android reciben 425 Too Early y esperan en el dispositivo. Actívalo solo cuando todo el mundo tenga una versión con Key Attestation: los eventos de versiones anteriores, de emuladores y de teléfonos rooteados o desbloqueados no podrán verificarse nunca y no se guardan.

Páginas web, a través de tu propio servidor

Una página web no puede guardar una clave de servidor: todo lo que está en el navegador se puede leer. Para obtener eventos verificados desde una página, reenvíalos a través de tu propio backend. La página envía a una ruta de tu sitio, y la ruta reenvía el lote a Lyrelog con la clave de servidor.

Ten claro qué demuestra eso. Estos eventos están verificados solo en el sentido de que pasaron por tu servidor. Cualquiera puede hacer un POST a una ruta de tu sitio, así que el relay debería aceptar eventos solo de tus propias sesiones autenticadas, y limitar lo que envía cada sesión. Un relay que acepta cualquier cosa de cualquiera no verifica nada.

En la página, apunta el endpoint del SDK de JavaScript al relay. Es una URL base: el SDK hace POST a <endpoint>/v1/events:batch. apiKey no puede estar vacío, pero el relay lo sustituye, así que sirve cualquier marcador:

export const log = Lyrelog.init({
  endpoint: "https://example.com/api/lyrelog", // posts to /api/lyrelog/v1/events:batch
  apiKey: "relay", // replaced by the server key on your server
});

El relay, como route handler de Next.js (app/api/lyrelog/[...path]/route.ts):

import { getSession } from "@/lib/auth"; // your own sign-in

export async function POST(request: Request) {
  const session = await getSession(request);
  if (!session) return new Response(null, { status: 401 });

  const encoding = request.headers.get("Content-Encoding");
  const upstream = await fetch("https://ingest.lyrelog.com/v1/events:batch", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.LYRELOG_SERVER_KEY}`, // lyr_srv_..., server only
      "Content-Type": request.headers.get("Content-Type") ?? "application/x-ndjson",
      ...(encoding ? { "Content-Encoding": encoding } : {}),
    },
    body: await request.arrayBuffer(),
  });

  const headers = new Headers({ "Content-Type": "application/json" });
  const retryAfter = upstream.headers.get("Retry-After");
  if (retryAfter) headers.set("Retry-After", retryAfter);
  return new Response(await upstream.text(), { status: upstream.status, headers });
}

Conviene saber:

  • Devuelve el código de estado y Retry-After sin cambios: el SDK decide con ellos si reintenta un lote o lo descarta.
  • Un 401 o 403 hace que el SDK deje de enviar hasta que la página se recarga. Inicia el cliente cuando el visitante haya iniciado sesión, no antes.
  • El país sale de la dirección que envía el lote a Lyrelog, que ahora es la de tu servidor. Los eventos reenviados llevan el país de tu servidor, no el del visitante.
  • Añade la dirección del relay al connect-src de tu Content Security Policy si tienes una ('self' cubre una ruta del mismo sitio).

Otras apps y páginas web

Los eventos de apps de Apple sin App Attest, de apps de Android sin Key Attestation y de páginas web que envían directamente usan la clave de ingesta pública sin prueba de la app, así que no están verificados. Una página web puede obtener eventos verificados a través de tu propio servidor. Dos límites impiden que una clave copiada haga mucho daño:

  • los eventos mensuales del plan, para toda la organización, y
  • la cuota diaria de una dirección, que se explica abajo.

La cuota diaria de una dirección

Con una clave pública (una clave de ingesta o una de acceso total), una dirección remitente puede enviar como máximo una cincuentava parte de los eventos mensuales del plan en un día UTC, sumando los proyectos de la organización. Las direcciones IPv6 cuentan por /64. Solo cuentan los eventos que no están verificados.

PlanEventos al día desde una dirección
Free20.000
Pro200.000
Business4.000.000
UnlimitedSin límite

Es mucho más de lo que envía un dispositivo. Existe para que una clave copiada de una app no pueda gastar el mes de la organización desde una sola máquina. Los eventos verificados (de una clave de servidor, App Attest o Key Attestation) no cuentan para ella.

Superada esa cuota, esa dirección recibe 429 con un Retry-After de como mucho una hora, hasta el siguiente día UTC. Las demás direcciones siguen enviando. Los SDK lo reintentan como cualquier 429, conservando los eventos dentro de los límites de su cola. El cuerpo está en la API HTTP.

Si uno de tus servidores la alcanza, debería estar usando una clave de servidor.