Early AccessNur auf Einladung, und die SDKs sind noch nicht veröffentlicht.Einladung anfragen
Zum Inhalt springen
Docs

Verifizierte Events

Events, die mit einem Server-Schlüssel gesendet werden oder von deiner eigenen Apple- oder Android-App kommen und vom Gerät bestätigt sind, werden als verifiziert markiert. So unterscheidest du sie von Events, die jeder mit dem öffentlichen Schlüssel hätte senden können.

Ein Ingest-Schlüssel steckt in deiner App oder deiner Webseite, also kann ihn jeder kopieren und Events senden, die wie die deiner App aussehen. Lyrelog markiert die Events, die es davon unterscheiden kann, als verifiziert (verified), und zwar auf drei Wegen:

  • Events, die mit einem Server-Schlüssel gesendet werden, einem Geheimnis, das nur deine Server kennen,
  • Events, die deine eigene Apple-App auf einem echten Gerät sendet, was Apple mit App Attest bestätigt, und
  • Events, die deine eigene Android-App auf einem echten Gerät sendet, was die Sicherheitshardware des Geräts mit Key Attestation bestätigt.

Was verifiziert bedeutet

Ein verifiziertes Event kann nicht von jemandem stammen, der den öffentlichen Schlüssel aus einer App oder einer Webseite kopiert hat. Bei einem Server-Schlüssel kam es mit einem Schlüssel, den nur die Server des Projekts haben. Bei App Attest stammt es von der echten App des Projekts, signiert von ihrem Team, auf einem echten Apple-Gerät. Bei Key Attestation stammt es von der echten Android-App des Projekts, signiert mit dem Zertifikat des Projekts, auf einem echten Android-Gerät mit seinem originalen, gesperrten System.

Es beweist nicht, dass der Inhalt des Events stimmt. Ein Server kann einen falschen Wert senden, und wer die echte App auf einem Gerät mit Jailbreak benutzt, könnte sie trotzdem Events senden lassen. Ein verifiziertes Event ist nur so vertrauenswürdig wie der Code, der es gesendet hat.

Events, die mit dem öffentlichen Ingest-Schlüssel und ohne Nachweis der App gesendet werden, sind nicht verifiziert: Jeder mit diesem Schlüssel hätte genau solche Events senden können. Das betrifft die meisten Events von Webseiten und von Apps ohne App Attest oder Key Attestation, und das ist so gewollt.

Wer verifiziert

AbsenderSchlüsselSeine Eventsverified_by
Dein ServerSend events from a server, lyr_srv_Verifiziertserver
Deine Apple-App auf einem echten iPhone, iPad oder einer Apple Watch, für App Attest eingerichtetSend events, lyr_ing_Verifiziertapp_attest
Deine Android-App auf einem echten Gerät, für Key Attestation eingerichtetSend events, lyr_ing_Verifiziertkey_attestation
Alles andere mit dem Ingest-SchlüsselSend events, lyr_ing_Nicht verifiziertleer
Alles mit einem Full-Access-SchlüsselFull access, lyr_adm_Nicht verifiziertleer

Lyrelog setzt das beim Ingest für jedes Event, abhängig vom Schlüssel, mit dem der Batch kam, und bei einem Ingest-Schlüssel vom App-Attest- oder Key-Attestation-Token, den der Batch mitbringt. Ein Client kann es nicht setzen: Eine Zeile, die verified_by selbst mitschickt, wird mit unknown fields: verified_by abgewiesen.

Ein Server-Schlüssel kann wie ein Ingest-Schlüssel nur Events anhängen, aber nicht lesen. Wie du einen erstellst, steht unter Schlüssel.

Im Dashboard

  • In der Event-Liste markiert ein kleines Schild neben dem Event-Namen ein verifiziertes Event.
  • Ein geöffnetes Event zeigt in seinem Kopf ein Badge Verified. Unter Context steht bei Sender Verified, server key, Verified, App Attest, Verified, Key Attestation oder Not verified, public key.
  • Im Explorer hat das Menü Filter ein Feld Verified by mit den Werten Server key, App Attest, Key Attestation und Not verified (in der URL: server, app_attest, key_attestation und none). Wähle alle außer Not verified, um nur verifizierte Events zu sehen, oder Not verified für den Rest.

Die Read API gibt verified_by an jedem Event zurück ("server", "app_attest", "key_attestation" oder "", wenn nicht verifiziert) und filtert danach mit verified=server, verified=app_attest, verified=key_attestation oder verified=none, auch mit mehreren Werten auf einmal (verified=server|app_attest|key_attestation).

Server

Ein Backend (Node, Python, Go, Java oder Kotlin auf der JVM oder curl von einem Server) sollte mit einem Server-Schlüssel senden, lyr_srv_...: Seine Events sind dann verifiziert, und der Tagesanteil einer Adresse gilt dafür nicht. Gib dem SDK den Server-Schlüssel dort, wo die Beispiele lyr_ing_... zeigen; sonst ändert sich nichts.

Bewahre den Schlüssel auf wie jedes Geheimnis: in der Umgebung oder im Secret Store deines Servers, nie in einer App, einer Webseite oder einem Repository. Gelangt er nach außen, widerrufe ihn und erstelle einen neuen.

Apple-Apps (App Attest)

Mit App Attest von Apple kann eine App einem Server nachweisen, dass sie die echte App ist, signiert von ihrem Team und auf einem echten Apple-Gerät. Das Swift-SDK erledigt das für dich, ebenso die SDKs für React Native und Flutter auf iOS, über das Swift-SDK. Lyrelog speichert die Events einer bestätigten App als verifiziert (verified_by ist app_attest).

Einrichten

  1. Ermittle die App ID deiner App: deine Team ID, ein Punkt und die Bundle-ID, etwa ABCDE12345.com.example.app. Die Team ID findest du in deinem Apple-Developer-Konto unter Membership.
  2. Öffne in Lyrelog die Project settings. Der Abschnitt Verified events from your Apple apps erscheint, wenn das Projekt die Plattform iOS-App hat. Füge die App ID mit Add hinzu. Ein Inhaber kann bis zu 10 hinzufügen, eine pro App (eine iPhone-App und ihre Watch-App haben verschiedene Bundle-IDs).
  3. Füge in Xcode dem App-Target die Capability App Attest hinzu (Signing & Capabilities). Das ist das Entitlement com.apple.developer.devicecheck.appattest-environment. Setze es für App-Store- und TestFlight-Builds auf production. Ohne das nutzt Apple seine Entwicklungsumgebung, die ebenfalls verifiziert.
  4. Verwende das Swift-SDK. Seine Option appAttest ist standardmäßig true, du musst also nichts weiter programmieren. Dasselbe gilt für React Native und Flutter (dort heißt die Option attest): Die Einstellungen des Projekts sind dieselben, weil das Swift-SDK darunter die Arbeit macht.

Zum Abschalten entfernst du die App IDs (Events kommen wie vorher unverifiziert an) oder setzt appAttest: false in der App.

So funktioniert es

  • Einmal pro Installation erzeugt das SDK einen Schlüssel in der Secure Enclave des Geräts, und Apple attestiert ihn anhand einer einmaligen Challenge von Lyrelog. Lyrelog prüft die Zertifikatskette von Apple und dass die App zu den App IDs des Projekts gehört, und speichert die öffentliche Hälfte des Schlüssels: eine pro Installation, gelöscht nach 180 Tagen ohne Nutzung.
  • Danach bekommt das SDK einen Token, der einen Tag gültig ist, und sendet ihn mit jedem Batch. Es erneuert den Token mit einer Signatur dieses Schlüssels (einer Assertion), deren Zähler sich nicht wiederverwenden lässt.
  • Das Senden wartet nie darauf. Solange die App keinen Token hat und wann immer etwas fehlschlägt, werden Events unverifiziert gesendet und gespeichert. Ein Batch wird nie wegen App Attest abgelehnt.

Wo es nicht greift

App Attest funktioniert auf echten iPhones, iPads und Apple Watches. In diesen Fällen kommen trotzdem unverifizierte Events an, auch wenn alles eingerichtet ist:

  • Macs (Apple bietet App Attest dort nicht an),
  • der Simulator,
  • die meisten App Extensions,
  • Geräte, die App Attest nicht unterstützen.

Die Routen und der Header stehen in der HTTP API.

Nur verifizierte Events von der iOS-App annehmen

Standardmäßig aus. Im selben Abschnitt der Einstellungen sorgt Accept only verified events from the iOS app dafür, dass Lyrelog jeden unverifizierten Batch zurückhält, dessen Events platform: ios angeben: Es antwortet mit 425 Too Early, und das SDK behält den Batch und sendet ihn später erneut. Die ersten Events einer neuen Installation warten ein paar Sekunden auf deren Token und kommen dann verifiziert an, dabei geht also nichts verloren.

Schalte es erst ein, wenn alle eine Version der App mit eingerichtetem App Attest haben. Bis dahin können sich Events von älteren Versionen, vom Simulator und von einer iPad-App auf einem Mac nie ausweisen: Sie warten auf dem Gerät, bis zu dem, was das SDK vorhält (20 MB und 7 Tage), und werden nie gespeichert. Events von anderen Plattformen und von einem Server-Schlüssel werden wie bisher angenommen.

Android-Apps (Key Attestation)

Mit Key Attestation von Android kann eine App einen Schlüssel in der Sicherheitshardware des Smartphones erzeugen (seiner Trusted Execution Environment oder einem StrongBox-Chip) und vom Gerät eine bis zu Google hinauf signierte Zertifikatskette bekommen, die den Schlüssel, die App und den Zustand des Smartphones beschreibt. Lyrelog prüft diese Kette selbst: Du brauchst weder ein Google-Konto noch Play Integrity noch ein Google-Cloud-Projekt. Das Android-SDK erledigt das für dich, ebenso die SDKs für React Native und Flutter auf Android, über das Android-SDK. Lyrelog speichert die Events einer bestätigten App als verifiziert (verified_by ist key_attestation).

Einrichten

  1. Ermittle das Paket deiner App (ihre Application ID, etwa com.example.app) und den SHA-256-Fingerabdruck des Zertifikats, mit dem sie signiert ist:
    • Bei Builds, die über Google Play installiert werden, signiert Google die App: Öffne in der Play Console die App, dann Test and release, App integrity, und kopiere den SHA-256 des App signing key certificate.
    • Bei Builds, die du selbst signierst (mit einem Upload-Schlüssel oder in der Entwicklung mit dem Debug-Schlüssel), führe ./gradlew signingReport aus und kopiere den SHA-256 dieser Variante.
  2. Öffne in Lyrelog die Project settings. Der Abschnitt Verified events from your Android apps erscheint, wenn das Projekt die Plattform Android-App hat. Füge Paket und Fingerabdruck mit Add hinzu; füge dasselbe Paket mit einem weiteren Fingerabdruck für jedes Zertifikat hinzu, das Builds signiert, die Events senden (bis zu 5 pro Paket, 10 Pakete).
  3. Verwende das Android-SDK. Seine Option attest ist standardmäßig true, du musst also nichts weiter programmieren. Dasselbe gilt für React Native und Flutter: Die Einstellungen des Projekts sind dieselben, weil das Android-SDK darunter die Arbeit macht. In einem React-Native- oder Flutter-Projekt führst du ./gradlew signingReport im Ordner android der App aus.

Zum Abschalten entfernst du die Pakete (Events kommen wie vorher unverifiziert an) oder setzt attest = false in der App.

Was geprüft wird

  • Die Kette ist Zertifikat für Zertifikat bis zu einer der Attestation-Roots von Google signiert, und keines ihrer Zertifikate steht auf Googles Liste der widerrufenen.
  • Der Schlüssel liegt in der Sicherheitshardware des Smartphones, wurde dort erzeugt und beantwortet eine einmalige Challenge von Lyrelog.
  • Das Smartphone hat sein originales, verifiziertes System gebootet, und sein Bootloader ist gesperrt.
  • Die App ist eines der Pakete des Projekts, signiert mit einem seiner Zertifikate.

Lyrelog speichert dann die öffentliche Hälfte des Schlüssels (eine pro Installation, gelöscht nach 180 Tagen ohne Nutzung) und gibt der App einen Token, der einen Tag gültig ist und den sie mit jedem Batch sendet. Sie erneuert den Token, indem sie mit diesem Schlüssel eine neue einmalige Challenge signiert. Das Senden wartet nie darauf: Solange die App keinen Token hat und wann immer etwas fehlschlägt, werden Events unverifiziert gesendet und gespeichert. Ein Batch wird nie wegen Key Attestation abgelehnt.

Wo es nicht greift

In diesen Fällen kommen unverifizierte Events an, auch wenn alles eingerichtet ist:

  • Emulatoren (sie haben keine Sicherheitshardware, und ihre Ketten führen nicht zu Google),
  • gerootete Smartphones und Smartphones mit entsperrtem Bootloader oder einem Custom-System,
  • Smartphones ohne hardwaregestützte Schlüssel (seit Android 8 selten),
  • Builds, die mit einem Zertifikat signiert sind, das das Projekt nicht aufführt.

Die Routen stehen in der HTTP API.

Nur verifizierte Events von der Android-App annehmen

Standardmäßig aus, und es funktioniert wie die iOS-Option: Ist sie eingeschaltet, bekommt jeder unverifizierte Batch, dessen Events platform: android angeben, 425 Too Early und wartet auf dem Gerät. Schalte sie erst ein, wenn alle eine Version mit Key Attestation haben: Events von älteren Versionen, Emulatoren und gerooteten oder entsperrten Smartphones können sich nie ausweisen und werden nie gespeichert.

Webseiten, über deinen eigenen Server

Eine Webseite kann keinen Server-Schlüssel geheim halten: Alles im Browser lässt sich auslesen. Um verifizierte Events von einer Seite zu bekommen, leite sie über dein eigenes Backend weiter. Die Seite sendet an eine Route auf deiner Website, und die Route reicht den Batch mit dem Server-Schlüssel an Lyrelog weiter.

Sei dir darüber im Klaren, was das beweist. Diese Events sind nur in dem Sinn verifiziert, dass sie durch deinen Server gelaufen sind. Jeder kann an eine Route auf deiner Website posten, deshalb sollte das Relay nur Events aus deinen eigenen angemeldeten Sessions annehmen und begrenzen, was eine Session sendet. Ein Relay, das alles von jedem annimmt, verifiziert gar nichts.

Lass auf der Seite den endpoint des JavaScript-SDK auf das Relay zeigen. Er ist eine Basis-URL: Das SDK postet an <endpoint>/v1/events:batch. apiKey darf nicht leer sein, aber das Relay ersetzt ihn, also geht jeder Platzhalter:

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

Das Relay als Next.js-Route-Handler (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 });
}

Gut zu wissen:

  • Gib den Status und Retry-After unverändert zurück: Daran entscheidet das SDK, ob es einen Batch erneut versucht oder verwirft.
  • Bei 401 oder 403 sendet das SDK nicht mehr, bis die Seite neu geladen wird. Starte den Client erst, wenn sich der Besucher angemeldet hat, nicht vorher.
  • Das Land ergibt sich aus der Adresse, die den Batch an Lyrelog sendet, und das ist jetzt die deines Servers. Weitergeleitete Events tragen das Land deines Servers, nicht das des Besuchers.
  • Füge die Adresse des Relays zu connect-src deiner Content Security Policy hinzu, falls du eine setzt ('self' deckt eine Route auf derselben Website ab).

Andere Apps und Webseiten

Events von Apple-Apps ohne App Attest, von Android-Apps ohne Key Attestation und von Webseiten, die direkt senden, nutzen den öffentlichen Ingest-Schlüssel ohne Nachweis der App und sind daher nicht verifiziert. Eine Webseite kann verifizierte Events über deinen eigenen Server bekommen. Zwei Limits sorgen dafür, dass ein kopierter Schlüssel nicht viel Schaden anrichtet:

  • die monatlichen Events des Plans, für die ganze Organisation, und
  • der Tagesanteil einer Adresse, siehe unten.

Der Tagesanteil einer Adresse

Mit einem öffentlichen Schlüssel (einem Ingest-Schlüssel oder einem Full-Access-Schlüssel) darf eine sendende Adresse an einem UTC-Tag höchstens ein Fünfzigstel der monatlichen Events des Plans senden, über alle Projekte der Organisation hinweg. IPv6-Adressen zählen pro /64. Es zählen nur Events, die nicht verifiziert sind.

PlanEvents pro Tag von einer Adresse
Free20.000
Pro200.000
Business4.000.000
UnlimitedKein Limit

Das ist weit mehr, als ein Gerät sendet. Es gibt diese Grenze, damit ein aus einer App kopierter Schlüssel nicht von einem einzigen Rechner aus den Monat der Organisation aufbrauchen kann. Verifizierte Events (von einem Server-Schlüssel, App Attest oder Key Attestation) zählen nicht dazu.

Darüber hinaus bekommt diese Adresse bis zum nächsten UTC-Tag 429 mit einem Retry-After von höchstens einer Stunde. Andere Adressen senden weiter. Die SDKs wiederholen es wie jedes 429 und behalten die Events im Rahmen ihrer Warteschlangenlimits. Der Body steht in der HTTP API.

Erreicht einer deiner Server diese Grenze, sollte er einen Server-Schlüssel verwenden.