Nutzer:innen erstellen und aktualisieren

Verwenden Sie diesen Endpunkt, um angepasste Events und Käufe aufzuzeichnen und die 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 zum Nennwert. Sie sollten nur Deltas (sich ändernde Daten) übergeben, 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.

Voraussetzungen

Um diesen Endpunkt zu verwenden, benötigen Sie einen API-Schlüssel mit der Berechtigung users.track.

Kund:innen, die die API für Server-zu-Server-Aufrufe verwenden, müssen möglicherweise rest.iad-01.braze.com auf die Zulassungsliste setzen, wenn sie sich hinter einer Firewall befinden.

Rate-Limit

Braze wendet auf diesen Endpunkt ein Basis-Rate-Limit von 3.000 Anfragen pro drei Sekunden an. Jede /users/track-Anfrage kann insgesamt bis zu 75 Objekte enthalten, verteilt auf attributes, events und purchases. Jedes Objekt kann eine:n Nutzer:in aktualisieren. Ein einzelnes Nutzerprofil kann durch mehrere Objekte aktualisiert werden.

Für Kund:innen, die Monthly Active Users CY 24-25, Universal MAU, Web MAU oder Mobile MAU erworben haben, gelten zusätzliche Rate-Limits. Weitere Informationen finden Sie unter Monthly Active Users CY 24-25 Limits.

Weitere Informationen finden Sie unter API-Rate-Limits. Bitte wenden Sie sich an Ihren Customer-Success-Manager, um eine Erhöhung anzufordern.

Anfragetext

1
2
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY

1
2
3
4
5
{
  "attributes": (optional, array of attributes object),
  "events": (optional, array of event object),
  "purchases": (optional, array of purchase object),
}

Anfrageparameter

Wichtig

Für jede in der folgenden Tabelle aufgeführte Anfragekomponente müssen Sie eines der folgenden Felder angeben: external_id, user_alias, braze_id, email oder phone.

Bezeichner-Auflösung

Jedes Anfrageobjekt muss mindestens einen Bezeichner enthalten. Die folgende Tabelle beschreibt, wie Braze bestimmt, welcher Bezeichner für die Suche nach dem Nutzerprofil verwendet wird.

Wenn ein primärer Bezeichner vorhanden ist, werden alle email- oder phone-Werte im selben Anfrageobjekt als Profilattribute behandelt – nicht als Bezeichner für die Nutzersuche. Wenn eine Anfrage beispielsweise sowohl eine external_id als auch eine email enthält:

• Braze sucht das Nutzerprofil anhand der external_id.
• Der email-Wert wird als Attribut im aufgelösten Profil gesetzt (oder aktualisiert).

Wichtig

Die Angabe eines primären Bezeichners, der keinem bestehenden Profil entspricht, kann ein doppeltes Profil erzeugen – selbst wenn email oder phone in derselben Anfrage mit einem bestehenden Profil übereinstimmen. Weitere Informationen finden Sie unter Wie vermeide ich die Erstellung doppelter Nutzerprofile?.

Beispiel-Anfragen

Ein Nutzerprofil über die E-Mail-Adresse aktualisieren

Über den Endpunkt /users/track können Sie ein Nutzerprofil per E-Mail-Adresse aktualisieren.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
    "attributes": [
        {
            "email": "[email protected]",
            "string_attribute": "fruit",
            "boolean_attribute_1": true,
            "integer_attribute": 26,
            "array_attribute": [
                "banana",
                "apple"
            ]
        }
    ],
    "events": [
        {
            "email": "[email protected]",
            "app_id": "your_app_identifier",
            "name": "rented_movie",
            "time": "2022-12-06T19:20:45+01:00",
            "properties": {
                "release": {
                    "studio": "FilmStudio",
                    "year": "2022"
                },
                "cast": [
                    {
                        "name": "Actor1"
                    },
                    {
                        "name": "Actor2"
                    }
                ]
            }
        },
        {
            "user_alias": {
                "alias_name": "device123",
                "alias_label": "my_device_identifier"
            },
            "app_id": "your_app_identifier",
            "name": "rented_movie",
            "time": "2013-07-16T19:20:50+01:00"
        }
    ],
    "purchases": [
        {
            "email": "[email protected]",
            "app_id": "your_app_identifier",
            "product_id": "product_name",
            "currency": "USD",
            "price": 12.12,
            "quantity": 6,
            "time": "2017-05-12T18:47:12Z",
            "properties": {
                "color": "red",
                "monogram": "ABC",
                "checkout_duration": 180,
                "size": "Large",
                "brand": "Backpack Locker"
            }
        }
    ]
}'

Ein Nutzerprofil nach Telefonnummer aktualisieren

Über den Endpunkt /users/track können Sie ein Nutzerprofil nach Telefonnummer aktualisieren. Dieser Endpunkt funktioniert nur, wenn Sie eine gültige Telefonnummer angeben.

Wichtig

Wenn Sie eine Anfrage sowohl mit email als auch mit phone stellen, verwendet Braze die E-Mail als Bezeichner.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
    "attributes": [
        {
            "phone": "+15043277269",
            "string_attribute": "fruit",
            "boolean_attribute_1": true,
            "integer_attribute": 25,
            "array_attribute": [
                "banana",
                "apple"
            ]
        }
    ],
}'

Abo-Gruppen festlegen

Dieses Beispiel zeigt, wie Sie eine:n Nutzer:in anlegen und die Abo-Gruppe im Nutzer:innen-Attribut-Objekt festlegen.

Das Aktualisieren des Abo-Status mit diesem Endpunkt aktualisiert die durch ihre external_id angegebene Person (z. B. User1) und aktualisiert den Abo-Status aller Nutzer:innen mit derselben E-Mail wie diese Person (User1).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
  "attributes": [
  {
    "external_id": "user_identifier",
    "email": "[email protected]",
    "email_subscribe": "subscribed",
    "subscription_groups": [{
      "subscription_group_id": "subscription_group_identifier_1",
      "subscription_state": "unsubscribed"
      },
      {
        "subscription_group_id": "subscription_group_identifier_2",
        "subscription_state": "subscribed"
        },
        {
          "subscription_group_id": "subscription_group_identifier_3",
          "subscription_state": "subscribed",
          "use_double_opt_in_logic": true
        }
      ]
    }
  ]
}'

Hinweis

Wenn Sie bei SMS-Abo-Gruppen den subscription_state einer Gruppe auf subscribed setzen, können Sie den optionalen Parameter use_double_opt_in_logic innerhalb dieses Abo-Gruppen-Objekts auf true setzen, um die Person in den SMS-Double-Opt-in-Workflow aufzunehmen. Wenn dieser Parameter weggelassen oder auf false gesetzt wird, während subscription_state den Wert subscribed hat, wird die Person ohne den Double-Opt-in-Workflow abonniert. Dieser Parameter wird nicht angewendet, wenn subscription_state auf andere Werte wie unsubscribed gesetzt ist.

Beispiel-Anfrage zur Erstellung einer/eines Nur-Alias-Nutzer:in

Sie können den Endpunkt /users/track verwenden, um eine:n Nur-Alias-Nutzer:in zu erstellen, indem Sie den Schlüssel _update_existing_only mit dem Wert false im Anfragetext angeben. Wenn Sie diesen Wert weglassen, erstellt Braze kein Nur-Alias-Nutzerprofil. Die Verwendung einer/eines Nur-Alias-Nutzer:in stellt sicher, dass genau ein Profil mit diesem Alias existiert. Dies ist besonders hilfreich beim Aufbau einer Integration, da Braze so keine doppelten Nutzerprofile erstellt.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
    "attributes": [
        {
            "_update_existing_only": false,
            "user_alias": {
                "alias_name": "example_name",
                "alias_label": "example_label"
            },
            "email": "[email protected]"
        }
    ],
}'

Antworten

Bei Verwendung einer der oben genannten API-Anfragen sollten Sie eine der folgenden drei allgemeinen Antworten erhalten: eine erfolgreiche Nachricht, eine erfolgreiche Nachricht mit nicht schwerwiegenden Fehlern oder eine Nachricht mit schwerwiegenden Fehlern.

Erfolgreiche Nachricht

Erfolgreiche Nachrichten werden mit der folgenden Antwort zurückgegeben:

1
2
3
4
5
6
{
  "message": "success",
  "attributes_processed": (optional, integer), if attributes are included in the request, this returns an integer of the number of external_ids with attributes that Braze queued for processing,
  "events_processed": (optional, integer), if events are included in the request, this returns an integer of the number of events that Braze queued for processing,
  "purchases_processed": (optional, integer), if purchases are included in the request, this returns an integer of the number of purchases that Braze queued for processing,
}

Erfolgreiche Nachricht mit nicht schwerwiegenden Fehlern

Wenn Ihre Nachricht erfolgreich ist, aber nicht schwerwiegende Fehler aufweist – z. B. ein ungültiges Event-Objekt in einer langen Liste von Events –, erhalten Sie die folgende Antwort:

1
2
3
4
5
6
7
8
{
  "message": "success",
  "errors": [
    {
      <minor error message>
    }
  ]
}

Bei Erfolgsmeldungen verarbeitet Braze weiterhin alle Daten, die nicht von einem Fehler im Array errors betroffen sind.

Nachricht mit schwerwiegenden Fehlern

Wenn Ihre Nachricht einen schwerwiegenden Fehler aufweist, erhalten Sie die folgende Antwort:

1
2
3
4
5
6
7
8
{
  "message": <fatal error message>,
  "errors": [
    {
      <fatal error message>
    }
  ]
}

Antwortcodes für schwerwiegende Fehler

Informationen zu Statuscodes und zugehörigen Fehlermeldungen, die Braze zurückgibt, wenn Ihre Anfrage auf einen schwerwiegenden Fehler stößt, finden Sie unter Schwerwiegende Fehler und Antworten.

Wenn Sie die Fehlermeldung „provided external_id is blacklisted and disallowed“ erhalten, hat Ihre Anfrage möglicherweise einen „Dummy-Nutzer“ enthalten. Weitere Informationen finden Sie unter Spam-Blockierung.

Endpunktspezifische Fehler

Die folgenden Fehler sind spezifisch für den Endpunkt /users/track und werden im Array errors der Antwort zurückgegeben. Verwenden Sie diese zur Fehlerbehebung bei einzelnen Objekten in einer Anfrage.

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 das zuletzt aktualisierte Profil mit einer externen ID für Updates. Wenn die external_id nicht existiert, priorisiert Braze das zuletzt aktualisierte Profil für Updates.

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 eine 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 eine:n Nutzer:in übermitteln, die/der Ihre mobile App noch nicht verwendet hat, um ein Nutzerprofil zu erstellen. Wenn die/der Nutzer:in die Anwendung anschließend nutzt, werden alle Informationen nach der Identifizierung über das SDK mit dem bestehenden Nutzerprofil zusammengeführt, das Sie über den API-Aufruf erstellt haben. Jegliches Nutzerverhalten, das vom SDK vor der Identifizierung anonym aufgezeichnet wurde, geht beim Zusammenführen mit dem bestehenden, über die API generierten Nutzerprofil verloren.

Das Segmentierungs-Tool berücksichtigt diese Nutzer:innen unabhängig davon, ob sie mit der App interagiert haben. Wenn Sie Nutzer:innen ausschließen möchten, die über die User API hochgeladen wurden und 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 zu identifizierten Profilen überführen, 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 repräsentiert ein einzelnes Vorkommen eines angepassten Events durch eine:n Nutzer:in zu einem bestimmten Zeitpunkt. Das bedeutet, dass jedes in Braze aufgenommene Event seine 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), verwirft Braze alle Updates verschachtelter angepasster Attribute in der Anfrage. Dies gilt für alle verschachtelten Strukturen innerhalb dieses spezifischen Attributs. Um eine erfolgreiche Verarbeitung sicherzustellen, überprüfen Sie vor dem Senden, ob alle Werte innerhalb der verschachtelten angepassten Attribute gültig sind.

Ist die Verarbeitung von Anfragen an /users/track in der Reihenfolge garantiert?

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

Wenn Sie beispielsweise mehrere Update-Anfragen für dieselbe:n Nutzer:in innerhalb von Sekunden 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, selbst wenn sie früher gesendet wurden. Dies kann dazu führen, dass Attributwerte scheinbar zurückgesetzt werden 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:n Nutzer:in senden müssen, fügen Sie eine Verzögerung (einige Sekunden) zwischen den Anfragen ein, damit die erste Anfrage die Verarbeitung abschließen 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 die Wahrscheinlichkeit von Ergebnissen in falscher Reihenfolge zu verringern.

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

Warum ist die Antwort von /users/track langsamer als erwartet?

Erfolgreiche /users/track-Aufrufe werden in der Regel schnell akzeptiert, aber Braze verarbeitet Attribut-, Event- und Kauf-Updates weiterhin asynchron. Die wahrgenommene Latenz kann steigen, wenn Payloads groß sind oder wenn 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).

Wie wirken sich Rate-Limits auf /users/track aus?

Wenn Sie sich Ihrem Rate-Limit nähern, erhalten Sie 429-Antworten. Bei Nicht-429-Antworten auf unterstützten Verträgen können Sie 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 zu sehen, wie viel von Ihrem aktuellen Fenster noch übrig ist.

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

Ein HTTP-400-Fehler 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 ist. 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 bestätigen Sie, dass der Body UTF-8-kodiert ist. Für andere 400-Antworten (z. B. Payload-Größe und Objektlimits pro Anfrage) lesen Sie Schwerwiegende Fehler und Antworten und die 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, aber Burst-Limits werden 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 verschiedene Rate-Limits auf dem Endpunkt /users/track:

• Die stündlichen Rate-Limits richten sich nach der erwarteten Datenaufnahme-Aktivität auf Ihrem Konto, die von der Anzahl der erworbenen monatlich aktiven Nutzer:innen, der Branche, der Saisonalität oder anderen Faktoren abhängen kann.
• 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 kombiniert über Attribut-, Event- oder Kauf-Objekte zusammenfassen.

Aktuelle Limits basierend auf der erwarteten Datenaufnahme finden Sie im Dashboard unter Einstellungen > APIs und Bezeichner > API-Nutzungs-Dashboard. Wir können Rate-Limits ändern, um die Systemstabilität zu schützen oder einen höheren Datendurchsatz auf Ihrem Konto zu ermöglichen. Bitte wenden Sie sich an den Braze Support oder Ihren Customer-Success-Manager, wenn Sie Fragen oder Bedenken bezüglich des stündlichen oder sekündlichen Anfragelimits und der Anforderungen Ihres Unternehmens haben.

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

Alle Antworten ohne Rate-Limit (z. B. nicht 429) 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 verwalten:

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 eine Ganzzahl zurückgibt, die die Anzahl der Sekunden angibt, bevor Sie wieder Anfragen stellen können.