Lotse, aufgerufen von deinem Server.Aus PHP, Node, Python oder mit curl.

Die andere Richtung: Webhooks

OpenAPI-3.1-Beschreibung

userId erreicht nur geprüfte Installationen

Ohne diese Regel könnte jeder in seiner Kopie deiner App identify("u_42") aufrufen und die Bestell-Pushes von u_42 bekommen. Deshalb geht ein Push an eine userId nur an Installationen, deren identify einen gültigen User-Hash trug. Hat der Nutzer keine, lautet die Antwort 422 identity_verification_required.

installId geht immer

Eine Install-ID kennt nur dein Backend, weil deine App sie ihm mit Lotse.instance.installId gemeldet hat. Nimm sie, wenn dein Projekt Identitäten nicht prüft.

Kein Gerät ist kein Fehler

Ist keine Installation des Ziels erreichbar, lautet die Antwort trotzdem 201, mit "status": "no_devices", und der Webhook message.failed folgt. GET /v1/messages/{id} zeigt die Zustellungen und ob der Push geöffnet wurde.

SDK 0.2.0 oder neuer

Ab 0.2.0 öffnet das SDK den targetPath einer angetippten Message und meldet push_open mit ihrer messageId. Mit einem älteren SDK erscheint die Benachrichtigung trotzdem, ein Tippen öffnet nur die App.

Sichtbar wie Kampagnen

Messages stehen in der Console unter Campaigns, Tab Messages, und push_sent und push_open landen im Event-Stream. Titel und Text werden nach 30 Tagen gelöscht, die Message nach 90.

import crypto from 'node:crypto';

// HMAC-SHA256 of the user id, trimmed as Lotse stores it, keyed with the
// whole identity secret (lt_is_…), as lower-case hex.
const userHash = crypto
  .createHmac('sha256', process.env.LOTSE_IDENTITY_SECRET)
  .update(userId.trim())
  .digest('hex');

await Lotse.instance.identify(userId, userHash: userHash);

Auf der zuletzt gesehenen Installation

Lotse löst den Nutzer beim Eingang auf: Das Event landet auf seiner zuletzt gesehenen Installation, unter denen, die es zur Zeit des Events schon gab. Funnels, Segmente, Auslöser und Ziele von Journeys und Kampagnen-Conversions zählen es wie ein Event aus der App.

Nutzer ohne Installation

Eine unbekannte userId legt einen Nutzer ohne Installation an, bis zu 100.000 je Projekt. Solche Events zählen im Event-Explorer, nicht in Segmenten oder Journeys, und eine später hinzukommende Installation übernimmt sie nicht.

Zeit

ts ist optional, ohne Angabe gilt jetzt. Es darf bis zu 30 Tage zurück und 5 Minuten vor der Serveruhr liegen. Außerhalb wird der Aufruf abgelehnt, damit eine falsche Uhr sofort auffällt.

Duplikate

Gib jedem Event eine id aus bis zu 128 sichtbaren ASCII-Zeichen, etwa order-1042. Eine id, die das Projekt schon gespeichert hat, wird übersprungen und kostet nichts; die Antwort zählt sie unter duplicates.

Namen und Props

Namen haben bis zu 100 Zeichen, props sind bis zu 20 Paare aus Strings mit bis zu 200 Zeichen, wie im SDK. Server-Events zählen gegen dieselben 500.000 Events je Projekt und Tag.

Namen, die Lotse und sein SDK selbst schreiben, sind reserviert:

• session_start
• identify
• push_sent
• push_open
• link_click
• attribution_match
• survey_answered
• feedback_submitted
• feature_voted
• feature_unvoted
• rage_tap

{
  "error": "forbidden",
  "message": "This server key lacks the scope messages:send. Scopes are fixed when a key is created: create a key with it in the Lotse console."
}

400invalid_input

Ein Feld fehlt, ist unbekannt oder hat einen falschen Typ oder Wert. Die Meldung nennt das Feld.

401unauthorized

Kein Key, oder einer, der unbekannt, widerrufen oder abgelaufen ist.

403forbidden

Dem Key fehlt der Scope der Route, und die Meldung nennt ihn. Oder die Anfrage kam aus einem Browser.

403project_suspended

Das Projekt ist gesperrt. Lesen und Löschen gehen weiter.

404not_found

Diesen Pfad gibt es nicht, oder nichts mit dieser ID in deinem Projekt.

405method_not_allowed

Der Pfad nimmt andere Methoden; der Header Allow nennt sie.

409conflict

Im aktuellen Zustand nicht möglich, etwa ein vergebener Slug, oder ein Idempotency-Key, der für eine andere Anfrage benutzt wurde.

413invalid_input

Der Body ist größer als 64 KiB, bei /v1/events größer als 256 KiB.

422identity_verification_required

Ein Push an eine userId ohne geprüfte Installation.

429quota_exceeded

Eine Quote des Projekts, dieselbe wie in der Console, etwa die Links seines Tarifs, in Free 5.000. Kommt ohne Retry-After.

429rate_limited

Ein Budget an Aufrufen oder Schreibaufrufen ist aufgebraucht. Retry-After nennt die Sekunden bis zum nächsten Versuch.

500internal_error

Ein Fehler auf dem Lotse-Server. Später erneut versuchen.

503unavailable

Arbeit, die gerade nicht fertig wurde, etwa der Start eines Versands. Dieselbe Anfrage nach Retry-After wiederholen: Sie erledigt, was fehlt, und nichts doppelt.

Jeder Aufruf mit gültigem Key ohne 2xx bleibt 7 Tage in der Console, unter Developers, Request log: Zeit, Key, Methode, Pfad, Status, Code und Dauer, nie Body oder Header. Ablehnungen durch ein Budget nur stichprobenartig. Eine Nutzer-ID im Pfad wird nicht gespeichert.