Nutzer:innen erstellen und aktualisieren

Verwenden Sie diesen Endpunkt, um angepasste Events und Käufe aufzuzeichnen und Attribute des Nutzerprofils zu aktualisieren.

Hinweis

Jedes angepasste Attribut, das in einer Anfrage an /users/track gesendet wird, verbraucht einen Datenpunkt. Weitere Informationen finden Sie unter Datenpunkte.

Braze verarbeitet die über die API übergebenen Daten unverändert. Übergeben Sie nur Deltas (sich ändernde Daten), um die unnötige Protokollierung von Datenpunkten zu minimieren.

Müssen Sie Nutzer:innen in großen Mengen aktualisieren?

Verwenden Sie den /users/track/bulk-Endpunkt, um größere Batches zu senden und das Anfragevolumen zu reduzieren.

Verarbeitungsstatus von Anfragen verfolgen

Wichtig

Die Verfolgung des Verarbeitungsstatus von Anfragen befindet sich in der Beta-Phase. Wenn Sie an der Beta teilnehmen möchten, wenden Sie sich an Ihren Braze Account Manager.

Braze verarbeitet /users/track-Anfragen asynchron. Eine erfolgreiche Antwort bedeutet, dass Braze Ihre Anfrage empfangen und zur Verarbeitung in die Warteschlange gestellt hat. Die Daten sind aber möglicherweise noch nicht im Nutzerprofil vorhanden. Um zu bestätigen, wann die Verarbeitung abgeschlossen ist, fügen Sie Ihren Anfragen eine group_id hinzu und überprüfen Sie den Status der Gruppe mit dem /users/track/status-Endpunkt.

Mit dem Verarbeitungsstatus von Anfragen können Sie Folgendes tun:

• Bestätigen, dass Attribut- oder Abo-Updates in einem Profil vorhanden sind, bevor Sie ein Canvas oder eine Campaign triggern, die davon abhängt
• Bestätigen, dass ein Backfill oder Import abgeschlossen ist, bevor Sie Nachrichten an die betroffenen Nutzer:innen senden
• Nachweisen, dass hochpriorisierte Updates wie Änderungen der Einwilligung vollständig verarbeitet wurden

Funktionsweise

1. Wählen Sie eine group_id für eine Reihe zusammengehöriger Anfragen. Verwenden Sie beispielsweise eine group_id für alle Anfragen in einem Backfill oder eine eindeutige group_id für eine einzelne Anfrage, die Sie bestätigen möchten.
2. Fügen Sie die group_id auf der obersten Ebene jedes /users/track-Anfragetexts ein. Braze ordnet jede akzeptierte Anfrage der Gruppe zu.
3. Rufen Sie den /users/track/status-Endpunkt mit der group_id auf. Wenn der status der Gruppe completed ist, hat Braze die Verarbeitung aller Anfragen in der Gruppe abgeschlossen.

Wenn Sie eine weitere Anfrage mit derselben group_id senden, nachdem die Gruppe completed ist, wechselt der Status der Gruppe wieder zu processing, bis Braze die Verarbeitung der neuen Anfrage abgeschlossen hat.

Braze verfolgt den Status für jede Gruppe als Ganzes. Eine Gruppe ist completed, wenn Braze die Verarbeitung aller Anfragen in der Gruppe abgeschlossen hat – einschließlich Anfragen, bei denen Braze einige Objekte abgelehnt hat. Braze listet abgelehnte Objekte im Array errors der jeweiligen /users/track-Antwort auf.

Die Statusverfolgung ist nur für den /users/track-Endpunkt verfügbar. Für Anfragen an den /users/track/bulk-Endpunkt oder den /users/track/sync-Endpunkt verfolgt Braze keinen Status.

Anforderungen an die Gruppen-ID

Eine group_id muss 1 bis 128 Zeichen lang sein und darf nur Buchstaben, Ziffern, Punkte (.), Unterstriche (_), Tilden (~) und Bindestriche (-) enthalten.

Gruppen-IDs gelten jeweils für einen Workspace. Dieselbe group_id in zwei Workspaces bezieht sich auf zwei separate Gruppen.

Verwenden Sie für jede Reihe von Anfragen, die Sie verfolgen möchten, eine neue group_id. Wenn Sie eine group_id wiederverwenden, werden die Anfragen der bestehenden Gruppe hinzugefügt, ohne deren Aufbewahrungszeitraum zu verlängern.

Limits und Aufbewahrung

Fehler bei der Statusverfolgung

In manchen Fällen kann Braze den Status einer Anfrage nicht verfolgen, zum Beispiel wenn Ihr Workspace die maximale Anzahl aktiver Gruppen erreicht hat. In diesem Fall ist die /users/track-Antwort trotzdem erfolgreich, und Braze verarbeitet die Attribute, Events und Käufe der Anfrage weiterhin. Die Antwort enthält einen Eintrag im Array errors, der beschreibt, warum Braze die Anfrage nicht verfolgt:

1
2
3
4
5
6
7
8

{
  "message": "success",
  "errors": [
    {
      "type": "request_status_group_full"
    }
  ]
}

Häufig gestellte Fragen

Wichtig

Senden Sie keine gesetzlich vorgeschriebenen Transaktions-E-Mails an SMS-Gateways, da die Wahrscheinlichkeit groß ist, dass diese E-Mails nicht zugestellt werden.

Obwohl E-Mails, die Sie unter Verwendung einer Telefonnummer und der Gateway-Domain des Anbieters (bekannt als MM3) versenden, dazu führen können, dass die E-Mail als SMS empfangen wird, unterstützen einige unserer E-Mail-Anbieter dieses Verhalten nicht. Wenn Sie beispielsweise eine E-Mail an eine T-Mobile-Telefonnummer (wie „[email protected]“) senden, wird Ihre SMS-Nachricht an die Person gesendet, die diese Telefonnummer im T-Mobile-Netz besitzt.

Beachten Sie, dass diese E-Mails, auch wenn sie nicht an das SMS-Gateway zugestellt werden, dennoch für Ihre E-Mail-Abrechnung berücksichtigt werden. Um den Versand von E-Mails an nicht unterstützte Gateways zu vermeiden, sehen Sie sich die Liste der nicht unterstützten Gateway-Domainnamen an.

Was passiert, wenn mehrere Profile mit derselben E-Mail-Adresse gefunden werden?

Wenn die external_id existiert, priorisiert Braze für Updates das zuletzt aktualisierte Profil mit einer externen ID. Wenn die external_id nicht existiert, priorisiert Braze für Updates das zuletzt aktualisierte Profil.

Was passiert, wenn kein Profil mit der E-Mail-Adresse existiert?

Braze erstellt ein Profil und eine:n Nur-E-Mail-Nutzer:in und setzt das E-Mail-Feld auf [email protected], wie in der Beispiel-Anfrage für das Update eines Nutzerprofils über die E-Mail-Adresse angegeben. Braze erstellt keinen Alias.

Wie verwenden Sie /users/track, um alte Nutzerdaten zu importieren?

Sie können über die Braze API Daten für Nutzer:innen übermitteln, die Ihre mobile App noch nicht verwendet haben, um ein Nutzerprofil zu erstellen. Wenn die Person die Anwendung anschließend nutzt, werden alle Informationen nach ihrer Identifizierung über das SDK mit dem bestehenden Nutzerprofil zusammengeführt, das Sie über den API-Aufruf erstellt haben. Nutzerverhalten, das das SDK vor der Identifizierung anonym aufgezeichnet hat, geht beim Zusammenführen mit dem bestehenden, über die API erstellten Nutzerprofil verloren.

Das Segmentierungs-Tool berücksichtigt diese Nutzer:innen unabhängig davon, ob sie mit der App interagiert haben. Wenn Sie über die User API hochgeladene Nutzer:innen ausschließen möchten, die noch nicht mit der App interagiert haben, fügen Sie den Filter Session Count > 0 hinzu.

Wie vermeide ich die Erstellung doppelter Nutzerprofile?

Doppelte Profile können entstehen, wenn eine Anfrage einen primären Bezeichner (wie external_id) enthält, der keinem bestehenden Profil entspricht, zusammen mit einem email- oder phone-Wert, der mit einem bestehenden Profil übereinstimmt. Da primäre Bezeichner für die Nutzersuche verwendet werden, erstellt Braze ein neues Profil für die unbekannte external_id, anstatt das bestehende Nur-E-Mail- oder Nur-Telefon-Profil zu aktualisieren.

So vermeiden Sie Duplikate:

• Wenn Sie Nutzer:innen von Nur-E-Mail- oder Nur-Telefon-Profilen auf identifizierte Profile umstellen, verwenden Sie den /users/identify-Endpunkt, um dem bestehenden Profil eine external_id zuzuweisen, anstatt beides an /users/track zu senden.
• Wenn bereits Duplikate vorhanden sind, führen Sie diese mit dem /users/merge-Endpunkt zusammen.

Wie behandelt /users/track doppelte Events?

Jedes Event-Objekt im Events-Array steht für ein einzelnes Vorkommen eines angepassten Events durch eine:n Nutzer:in zu einem bestimmten Zeitpunkt. Das bedeutet, dass jedes in Braze aufgenommene Event eine eigene Event-ID hat, sodass „doppelte“ Events als separate, eindeutige Events behandelt werden.

Wie geht /users/track mit ungültigen verschachtelten angepassten Attributen um?

Wenn ein verschachteltes angepasstes Attribut ungültige Werte enthält (z. B. ungültige Zeitformate oder Null-Werte), schließt Braze alle Updates verschachtelter angepasster Attribute in der Anfrage von der Verarbeitung aus. Dies gilt für alle verschachtelten Strukturen innerhalb dieses Attributs. Um eine erfolgreiche Verarbeitung sicherzustellen, überprüfen Sie vor dem Senden, ob alle Werte in verschachtelten angepassten Attributen gültig sind.

Werden Anfragen an /users/track garantiert in der richtigen Reihenfolge verarbeitet?

Wenn Sie mehrere separate API-Aufrufe an /users/track in schneller Folge senden, kann Braze nicht garantieren, dass die Anfragen in genau der Reihenfolge verarbeitet werden, in der sie gesendet oder empfangen wurden. Das liegt daran, dass Braze eine asynchrone Verarbeitung nutzt, um Geschwindigkeit und Flexibilität zu maximieren.

Wenn Sie beispielsweise innerhalb weniger Sekunden mehrere Update-Anfragen für dieselbe Person senden – einige mit Null-Attributwerten und andere mit gültigen Werten –, können die Anfragen mit Null-Werten nach den Anfragen mit gültigen Werten verarbeitet werden, auch wenn sie früher gesendet wurden. Dadurch kann es so aussehen, als würden Attributwerte zurückgesetzt oder nicht das zuletzt gesendete Update widerspiegeln.

So vermeiden Sie Race-Conditions beim Aktualisieren von Nutzerdaten:

• Updates in einer einzigen Anfrage bündeln: Fassen Sie alle Attribut-Updates für eine:n Nutzer:in in einem API-Aufruf zusammen, anstatt separate, aufeinanderfolgende Aufrufe zu senden.
• Verzögerungen zwischen Anfragen einfügen: Wenn Sie separate Aufrufe für dieselbe Person senden müssen, fügen Sie zwischen den Anfragen eine Verzögerung (einige Sekunden) ein, damit die erste Anfrage vollständig verarbeitet werden kann, bevor die nächste gesendet wird.
• Überlappende Updates für dasselbe Feld vermeiden: Wenn zwei Anfragen dasselbe Attribut mit unterschiedlichen Werten aktualisieren, senden Sie diese Updates in einer Anfrage oder trennen Sie sie durch eine Verzögerung, um das Risiko von Ergebnissen in falscher Reihenfolge zu verringern.
• Verarbeitung vor der nächsten Anfrage bestätigen (Beta): Fügen Sie der ersten Anfrage eine group_id hinzu und warten Sie, bis der /users/track/status-Endpunkt completed zurückgibt, bevor Sie die abhängige Anfrage senden. Weitere Informationen finden Sie unter Verarbeitungsstatus von Anfragen verfolgen.

Weitere Informationen zu Race-Conditions und Best Practices finden Sie unter Race-Conditions.

Woher weiß ich, wann Braze die Verarbeitung meiner Anfrage abgeschlossen hat?

Fügen Sie Ihren /users/track-Anfragen eine group_id hinzu und rufen Sie dann den /users/track/status-Endpunkt mit dieser group_id auf. Wenn der status der Gruppe completed ist, hat Braze die Verarbeitung aller Anfragen in der Gruppe abgeschlossen. Dieses Feature befindet sich in der Beta-Phase. Weitere Informationen finden Sie unter Verarbeitungsstatus von Anfragen verfolgen.

Wie oft sollte ich den Status einer Gruppe überprüfen?

Fragen Sie den /users/track/status-Endpunkt in regelmäßigen Abständen ab, z. B. alle paar Sekunden, und beenden Sie die Abfrage, sobald der status der Gruppe completed ist. Bleiben Sie mit Ihren Abfragen innerhalb des Rate-Limits des Endpunkts von 1.500 Anfragen pro Minute pro Workspace.

Warum befindet sich meine Gruppe noch in Verarbeitung?

Eine Gruppe bleibt im Status processing, bis Braze alle akzeptierten Anfragen in der Gruppe verarbeitet hat. Wenn eine Anfrage bei der Verarbeitung fehlschlägt, versucht Braze es erneut, und die Gruppe bleibt im Status processing, bis der erneute Versuch erfolgreich ist. Wenn Sie einer Gruppe Anfragen hinzufügen, nachdem sie completed ist, wechselt ihr Status wieder zu processing. In seltenen Fällen kann eine Gruppe im Status processing bleiben, bis ihr Aufbewahrungszeitraum endet. Wenn eine Gruppe deutlich länger als Ihre übliche Verarbeitungszeit im Status processing bleibt, wenden Sie sich an den Braze Support.

Warum gibt /users/track/status ein leeres results-Array zurück?

Das results-Array ist leer, wenn Braze die Gruppe in Ihrem Workspace nicht findet. Das ist der Fall, wenn der 24-stündige Aufbewahrungszeitraum der Gruppe abgelaufen ist, die group_id nicht mit der in Ihren Anfragen übereinstimmt oder Sie die Anfragen an einen anderen Workspace gesendet haben. Es kommt auch vor, wenn Braze für diese group_id keine Anfragen verfolgt hat. Überprüfen Sie jede /users/track-Antwort auf Fehler bei der Statusverfolgung.

Warum ist meine /users/track-Antwort langsamer als erwartet?

Erfolgreiche /users/track-Aufrufe werden in der Regel schnell akzeptiert, aber Braze verarbeitet Attribut-, Event- und Kauf-Updates trotzdem asynchron. Die wahrgenommene Latenz kann steigen, wenn Payloads groß sind oder das Netzwerk-Routing zu Ihrem REST-Endpunkt langsam ist. Wenn Sie eine synchrone Bestätigung pro Nutzer:in oder eine strengere Reihenfolge zwischen Aufrufen benötigen, lesen Sie /users/track/sync (eingeschränkte Beta).

Warum gibt /users/track 429 Too Many Requests zurück?

Wenn Ihr Anfragevolumen das Rate-Limit überschreitet, gibt /users/track eine HTTP-Antwort 429 Too Many Requests zurück. So nehmen Sie das Senden von Anfragen wieder auf:

1. Pausieren Sie Anfragen für die im Antwort-Header X-RateLimit-Retry-After angegebene Anzahl von Sekunden.
2. Nehmen Sie Anfragen mit einer niedrigeren Rate wieder auf, um die Wahrscheinlichkeit einer weiteren 429-Antwort zu verringern.
3. Fassen Sie Updates nach Möglichkeit zusammen und beachten Sie das Limit für Anfrageobjekte Ihres Kontos.
4. Verwenden Sie das API-Nutzungs-Dashboard, um Anfragespitzen und Trends bei 429-Antworten zu erkennen. Informationen zu Workspace-Standardwerten und Limits anderer Endpunkte finden Sie unter API-Rate-Limits.

Bei Antworten, die nicht 429 sind, können Sie bei unterstützten Verträgen die X-RateLimit-*-Antwort-Header verwenden, die unter Rate-Limit-Header für monatlich aktive Nutzer:innen CY 24-25, Universal MAU, Web MAU und Mobile MAU beschrieben sind, um die verbleibenden Anfragen im aktuellen Fenster zu überprüfen.

Warum erhalte ich 400 Bad Request mit einem Syntax- oder Parse-Fehler?

Ein HTTP-400 mit einem Syntax- oder Parse-Fehler bedeutet in der Regel, dass der Anfragetext kein gültiges JSON ist. Häufige Ursachen sind nachgestellte Kommas, Kommentare innerhalb von JSON, Strings in einfachen Anführungszeichen, eine zusätzliche öffnende { vor dem Payload oder das Senden eines Nicht-JSON-Bodys, während der Content-Type-Header application/json lautet. Validieren Sie Payloads vor dem Senden mit einem JSON-Linter, stellen Sie sicher, dass Ihr HTTP-Client Objekte als JSON kodiert (anstatt Roh-Strings zu verketten), und prüfen Sie, ob der Body UTF-8-kodiert ist. Informationen zu anderen 400-Antworten (z. B. zur Payload-Größe und zu Objektlimits pro Anfrage) finden Sie unter Schwerwiegende Fehler und Antworten und in der Tabelle Endpunktspezifische Fehler auf dieser Seite.

Monatlich aktive Nutzer:innen CY 24-25, Universal MAU, Web MAU und Mobile MAU

Für Kund:innen mit neuen Preismodellen werden Rate-Limits auf Unternehmensebene durchgesetzt. Kund:innen können Workspace-Rate-Limits für stündliche Limits festlegen, Burst-Limits werden jedoch weiterhin von allen Workspaces gemeinsam genutzt.

Für Kund:innen, die monatlich aktive Nutzer:innen CY 24-25, Universal MAU, Web MAU oder Mobile MAU erworben haben, verwaltet Braze unterschiedliche Rate-Limits für den Endpunkt /users/track:

• Stündliche Rate-Limits richten sich nach der erwarteten Datenaufnahme-Aktivität in Ihrem Konto. Diese kann von der Anzahl der erworbenen monatlich aktiven Nutzer:innen, der Branche, saisonalen Schwankungen oder anderen Faktoren abhängen.
• Zusätzlich zum stündlichen Limit setzt Braze ein Burst-Limit für die Anzahl der Anfragen durch, die alle drei Sekunden gesendet werden können.
• Jede Anfrage kann bis zu 75 Updates über Attribut-, Event- oder Kauf-Objekte hinweg bündeln.

Die aktuellen Limits auf Basis der erwarteten Datenaufnahme finden Sie im Dashboard unter Einstellungen > APIs und Bezeichner > API-Nutzungs-Dashboard. Wir können Rate-Limits anpassen, um die Systemstabilität zu schützen oder einen höheren Datendurchsatz für Ihr Konto zu ermöglichen. Wenden Sie sich bei Fragen oder Bedenken zum stündlichen oder sekündlichen Anfragelimit und zu den Anforderungen Ihres Unternehmens an den Braze Support oder Ihren Customer-Success-Manager.

Rate-Limit-Header für monatlich aktive Nutzer:innen CY 24-25, Universal MAU, Web MAU und Mobile MAU

Alle Antworten ohne Rate-Limiting (z. B. Antworten, die nicht 429 sind) enthalten die folgenden HTTP-Antwort-Header, die dem Client den Status des stündlichen Rate-Limit-Fensters anzeigen. Verwenden Sie diese Header, um Ihre Anfragerate zu steuern:

Beachten Sie, dass die Header RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset nicht zurückgegeben werden, wenn ein HTTP-429-Fehler auftritt. In diesem Fall werden diese Header durch einen X-RateLimit-Retry-After-Header ersetzt, der als Ganzzahl die Anzahl der Sekunden angibt, bis Sie wieder Anfragen stellen können.

Sie können das OpenAPI-Dokument herunterladen und damit Schemas validieren. Wie das geht, erfahren Sie unter OpenAPI-Schemas zur Validierung von Anfragen verwenden.