Skip to content
App

Alle Artikel

App Activity API v1

Emperor holt registrierte Nutzer und Tagesaktivität per gemeinsamem Vertrag aus Anwendungen. Jede Anwendung kann ihn umsetzen, nicht nur eigene. Die Anwendung bleibt die Quelle; spätere Syncs aktualisieren Daten. Derselbe Mensch aus mehreren Apps erzeugt keine doppelte Person.

Diese Seite richtet sich an Teams, die den Vertrag implementieren. Das maschinenlesbare OpenAPI-3.1-Dokument ist die App-Activity-API-Spezifikation.

v1 ist ein Entwurf und kann sich bis zur Finalisierung ändern. Nach der Finalisierung kommen inkompatible Änderungen als /v2.

Ressourcen

Die Anwendung stellt drei GET-Ressourcen unter /v1 bereit, relativ zur App-Activity-API-URL:

  • /v1/manifest — Vertragsversion (1), Anwendungsname, IANA-Zeitzone für Aktivitätstage und der Katalog der Aktivitätsschlüssel mit Labels.
  • /v1/users — Nutzer. Query: updatedSince, cursor, limit.
  • /v1/activity — Tagesaggregate, eine Zeile je Nutzer, Kalendertag und Schlüssel aus dem Katalog. Dieselben Query-Parameter wie bei users.

Ist contractVersion nicht 1, lehnt Emperor die Verbindung mit einem klaren Fehler ab.

Cursor und Überschreiben der Aktivität

updatedSince ist ein ISO-8601-DateTime mit Offset oder Z. Es kommen Datensätze mit updatedAt größer oder gleich diesem Wert. Ohne Parameter: voller Export. cursor ist ein undurchsichtiger String aus dem nextCursor der vorigen Seite. limit ist standardmäßig 100, höchstens 100.

Listenantworten sind { "data": [...], "nextCursor": null | string }. nextCursor ist null auf der letzten Seite.

Eine spätere Aktivitätszeile für dasselbe (externalUserId, day, metricKey) ersetzt den gespeicherten Zähler. Anwendungen senden Tagessummen, keine Rohereignisse.

E-Mail oder Telefon

Jeder Nutzer braucht email, phone (E.164, zum Beispiel +79991234567) oder beides. Ein Datensatz ohne beides wird vom Vertrag abgelehnt. Emperor zählt ihn im Sync als abgelehnt und legt keine Person an.

Wie Emperor Kontakte zuordnet

Ein Mensch im CRM ist Person. E-Mail und Telefon sind Kontakte. Die Anwendungsidentität liegt auf einem eigenen Link: eine Person, mehrere Apps.

  • E-Mail wird normalisiert (Trim und Kleinbuchstaben). Telefon steht in E.164.
  • Eine bereits verknüpfte Identität (LINKED) aktualisiert nur den Identitätsschnitt und die Aktivität. Der Name der Person bleibt unverändert.
  • Eine verworfene Identität wird nicht zugeordnet.
  • Eine neue Identität ohne Treffer erzeugt eine Person und E-Mail-/Telefon-Kontakte.
  • Jeder Treffer auf eine vorhandene Person, inklusive Konflikt bei E-Mail/Telefon oder einer zweiten App mit derselben E-Mail, landet in PENDING_REVIEW. Es gibt keine zweite Person und kein automatisches Zusammenführen.

Treffer prüfen

Öffnen Sie CRM → Treffer aus Anwendungen. Die Warteschlange sind Treffer, die auf Prüfung warten. Jede Zeile zeigt den Profilschnitt aus der App, E-Mail und Telefon, Kandidaten-Personen und den Grund (E-Mail, Telefon, beides oder Konflikt E-Mail/Telefon).

Vergleichen Sie die eingehenden Daten mit Kontakten und verknüpften Anwendungen jedes Kandidaten und wählen Sie eine Aktion:

  • Verknüpfen mit dem gewählten Kandidaten. Fehlende E-Mail und Telefon werden als Kontakte ergänzt. Die Identität wird LINKED. Es entsteht keine zweite Person, der Name bleibt.
  • Anlegen einer neuen Person, wie bei einer Synchronisation ohne Treffer. Die Identität wird LINKED.
  • Verwerfen. Die Identität wird DISCARDED. Die nächste Synchronisation setzt sie nicht erneut in die Warteschlange. Emperor speichert, wer entschieden hat und wann.

Checkliste für den Anschluss

  1. /v1/manifest, /v1/users und /v1/activity in Production nur über HTTPS anbieten.
  2. Ein Bearer-Token mit hoher Entropie pro Projekt–Anwendung ausstellen, nur Leserechte für diese API. Kein dienstweiter Schlüssel.
  3. Token zeitkonstant vergleichen. Eine Anfrage ohne gültiges Bearer liefert 401 als RFC-7807 application/problem+json. Nicht unterscheiden, ob der Token fehlt oder falsch ist.
  4. User-Agent: Emperor-AppProvider/1.0 und X-Request-Id (UUID) annehmen. Dieselbe Id in Problem-Dokumenten bei Fehlern zurückgeben.
  5. Bei 429 Retry-After senden.
  6. Rotation: im Rotationsfenster aktuellen und vorherigen Token akzeptieren, danach den alten widerrufen.

Anwendung in Emperor verbinden

Im Development-Projekt Anwendungen öffnen (Schnellaktion oder Projekteinstellungen). Eine vorhandene Publikation mit App-Activity-API-Verbindung verknüpfen oder eine neue Publikation anlegen (Name, UID, Domain, Server, App-Activity-API-URL, Token). Das Token ist nur schreibbar: die UI zeigt danach nur den Fingerabdruck.

Auf den Bearbeitungs- und Ansichtsseiten der Publikation heißt der Block App-Aktivität. Die Ansicht zeigt die URL vollständig (nicht „Konfiguriert“) und den Token-Fingerabdruck.

Prüfen ruft GET {baseUrl}/v1/manifest auf. Synchronisieren in der Zeile oder Alle synchronisieren holt users und danach activity in derselben HTTP-Anfrage (höchstens fünf Minuten). Trennen löscht die Projektbindung und die Cursor; die Publikation bleibt.

Emperor speichert Verbindung, Synchronisationscursor und Laufverlauf. Derselbe Sync ordnet Identitäten zu: ohne Treffer entsteht eine Person; jeder bestehende Treffer geht in die Prüfliste.

Auf der Person-Karte listet Anwendungen verknüpfte Identitäten, Registrierung, zuletzt gesehen und Aktivität für Zeitraum und Metrik. Die CRM-Kontaktliste filtert Personen mit einer verknüpften Identität einer gewählten Anwendung.

Grenzen

  • Eine Sync-Anfrage, die länger als fünf Minuten läuft, wird beendet.
  • Bleibt ein Sync hängen und antwortet mit HTTP 409, beendet Sperre aufheben in der Zeile Anwendungen den Lauf als FAILED, ohne Cursor zu verschieben. Danach erneut Synchronisieren.
  • Aktivität eines wegen fehlender E-Mail und Telefonnummer abgelehnten Nutzers kommt nach einer Profilkorrektur erst zurück, wenn sich updatedAt dieser Aktivitätszeile ändert. Ein vollständiger Neuabzug erfordert Trennen und erneutes Verknüpfen.

Sicherheit und Audit-Log der Anwendung

v1 ist HTTPS plus Bearer-Token an der Bindung Projekt–Anwendung.

Empfohlen: jede App-Activity-API-Anfrage mit Zeit, Quell-IP, X-Request-Id, User-Agent, Ressource (manifest / users / activity), updatedSince, HTTP-Status und Anzahl gelieferter Datensätze loggen. Token, Authorization, E-Mail, Telefon und Antwortkörper nicht loggen.

Ebenfalls empfohlen: ein Token nur für diese API; Rate-Limit; Alarme bei einer 401-Serie, fremdem User-Agent, unerwarteter IP oder plötzlichem Mengensprung. Keine IP-Allowlist verlangen: die ausgehenden Adressen von Emperor sind keine einzelne feste IP.

Artikel