Skip to content

Nutzer:innen erstellen und aktualisieren (synchron)

post

/users/track/sync

core endpoint

Verwenden Sie diesen Endpunkt, um angepasste Events und Käufe aufzuzeichnen und Nutzerprofilattribute synchron zu aktualisieren. Dieser Endpunkt funktioniert ähnlich wie der Endpunkt /users/track, der Nutzerprofile asynchron aktualisiert.

Synchrone und asynchrone API-Aufrufe

Bei einem asynchronen Aufruf gibt die API den Statuscode 201 zurück, der anzeigt, dass Ihre Anfrage erfolgreich empfangen, verstanden und akzeptiert wurde. Dies bedeutet jedoch nicht, dass Ihre Anfrage vollständig abgeschlossen wurde.

Bei einem synchronen Aufruf gibt die API den Statuscode 201 zurück, der anzeigt, dass Ihre Anfrage erfolgreich empfangen, verstanden, akzeptiert und abgeschlossen wurde. Die Antwort auf den Aufruf zeigt ausgewählte Felder des Nutzerprofils als Ergebnis der Operation an.

Dieser Endpunkt hat ein niedrigeres Rate-Limit als der Endpunkt /users/track (siehe Rate-Limit unten). Jede /users/track/sync-Anfrage kann nur ein Event-Objekt, ein Attribut-Objekt oder ein Kauf-Objekt enthalten. Dieser Endpunkt sollte für Nutzerprofil-Updates reserviert sein, bei denen ein synchroner Aufruf erforderlich ist. Für eine stabile Implementierung empfehlen wir, /users/track/sync und /users/track gemeinsam zu verwenden.

Wenn Sie beispielsweise innerhalb eines kurzen Zeitraums aufeinanderfolgende Anfragen für dieselbe Nutzer:in senden, sind Race-Conditions mit dem asynchronen Endpunkt /users/track möglich. Mit dem Endpunkt /users/track/sync können Sie diese Anfragen jedoch nacheinander senden, jeweils nach Erhalt einer 2XX-Antwort.

Voraussetzungen

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

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

Für diesen Endpunkt gilt für alle Kund:innen ein Basis-Rate-Limit von 500 Anfragen pro Minute. Jede /users/track/sync-Anfrage kann bis zu ein Event-Objekt, ein Attribut-Objekt oder ein Kauf-Objekt enthalten. Jedes Objekt (Event-, Attribut- und Kauf-Arrays) kann jeweils eine:n Nutzer:in aktualisieren.

Anfragetext

1
2

Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY

1
2
3
4
5

{
  "attributes": (optional, one attributes object),
  "events": (optional, one event object),
  "purchases": (optional, one purchase object),
}

Anfrageparameter

Parameter Erforderlich Datentyp Beschreibung
attributes Optional Ein Attribut-Objekt Siehe Nutzerattribut-Objekt
events Optional Ein Event-Objekt Siehe Event-Objekt
purchases Optional Ein Kauf-Objekt Siehe Kauf-Objekt

Antworten

Wenn Sie die Anfrageparameter dieses Endpunkts verwenden, sollten Sie eine der folgenden Antworten erhalten: eine Erfolgsmeldung oder eine Nachricht mit schwerwiegenden Fehlern.

Erfolgsmeldung

Erfolgsmeldungen geben die folgende Antwort zurück, die Informationen zu den von Braze aktualisierten Nutzerprofildaten enthält.

1
2
3
4
5
6
7

{
    "users": (optional, object), the identifier of the user in the request. May be empty if no users are found and _update_existing_only key is set to true,
        "custom_attributes": (optional, object), the custom attributes as a result of the request. Braze lists only custom attributes from the request,
        "custom_events": (optional, object), the custom events as a result of the request. Braze lists only custom events from the request,
        "purchase_events": (optional, object), the purchase events as a result of the request. Braze lists only purchase events from the request,
    },
    "message": "success"

Nachricht mit schwerwiegenden Fehlern

Wenn Ihre Nachricht einen schwerwiegenden Fehler enthält, erhalten Sie die folgende Antwort:

1
2
3
4
5
6
7
8

{
  "message": <fatal error message>,
  "errors": [
    {
      <fatal error message>
    }
  ]
}

Beispielanfragen und -antworten

Angepasstes Attribut anhand der externen ID aktualisieren

Anfrage

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/sync' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
    "attributes": [
        {
            "external_id": "xyz123",
            "string_attribute": "fruit",
            "boolean_attribute_1": true,
            "integer_attribute": 25,
            "array_attribute": [
                "banana",
                "apple"
            ]
        }
    ]
}'

Antwort

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
    "users": [
        {
            "external_id": "xyz123",
            "custom_attributes": {
                "string_attribute": "fruit",
                "boolean_attribute_1": true,
                "integer_attribute": 25,
                "array_attribute": [
                    "banana",
                    "apple",
                ]
            }
        }
    ],
    "message": "success"
}

Angepasstes Event per E-Mail aktualisieren

Anfrage

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

curl --location --request POST 'https://rest.iad-01.braze.com/users/track/sync' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
    "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"
                    }
                ]
            }
        }
    ]
}'

Antwort

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{
    "users": [
        {
            "email": "[email protected]",
            "custom_events": [
                {
                "name": "rented_movie",
                "first": "2022-01-001T00:00:00.000Z",
                "last": "2022-12-06T18:20:45.000Z",
                "count": 10
                }
            ]
        }
    ],
    "message": "success"
}

Kauf-Event anhand des Nutzer-Alias aktualisieren

Anfrage

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

curl --location --request POST 'https://rest.iad-01.braze.com/users/track/sync' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
  "purchases" : [
    {
      "user_alias" : {
          "alias_name" : "device123",
          "alias_label" : "my_device_identifier"
      }
      "app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
      "product_id" : "Completed Order",
      "currency" : "USD",
      "price" : 219.98,
      "time" : "2022-12-06T19:20:45+01:00",
      "properties" : {
          "products" : [
            {
              "name": "Monitor",
              "category": "Gaming",
              "product_amount": 19.99
            },
            {
              "name": "Gaming Keyboard",
              "category": "Gaming ",
              "product_amount": 199.99
            }
          ]
      }
   }
  ]
}'

Antwort

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

{
    "users": [
        {
          "user_alias" : {
            "alias_name" : "device123",
            "alias_label" : "my_device_identifier"
          },
          "purchase_events": [
                {
                "product_id": "Completed Order",
                "first": "2013-07-16T19:20:30+01:00",
                "last": "2022-12-06T18:20:45.000Z",
                "count": 3
                }
            ]
        }
    ],
    "message": "success"
}

Häufig gestellte Fragen

Sollte ich den asynchronen oder den synchronen Endpunkt verwenden?

Für die meisten Profil-Updates eignet sich der Endpunkt /users/track am besten, da er höhere Rate-Limits und die Flexibilität bietet, Anfragen gebündelt zu senden. Der Endpunkt /users/track/sync ist jedoch nützlich, wenn Sie Race-Conditions aufgrund von schnellen, aufeinanderfolgenden Anfragen für dieselbe Nutzer:in erleben.

Unterscheidet sich die Antwortzeit vom Endpunkt /users/track?

Bei einem synchronen Aufruf wartet die API, bis Braze die Anfrage abgeschlossen hat, bevor eine Antwort zurückgegeben wird. Infolgedessen dauern synchrone Anfragen im Durchschnitt länger als asynchrone Anfragen an /users/track. Für die meisten Anfragen können Sie eine Antwort innerhalb von Sekunden erwarten.

Kann ich mehrere Anfragen gleichzeitig senden?

Ja, solange die Anfragen für verschiedene Nutzer:innen bestimmt sind oder jede Anfrage unterschiedliche Attribute, Events oder Käufe für eine:n Nutzer:in aktualisiert.

Wenn Sie mehrere Anfragen für eine:n Nutzer:in für dasselbe Attribut, Event oder denselben Kauf senden, empfiehlt Braze, zwischen den einzelnen Anfragen auf eine erfolgreiche Antwort zu warten, um Race-Conditions zu vermeiden.

Warum stimmt der Antwortwert nicht mit dem in meiner ursprünglichen Anfrage überein?

Obwohl Ihre Anfrage abgeschlossen wurde, ist es möglich, dass der Wert Ihres angepassten Attributs nicht aktualisiert wurde. Dies kann passieren, wenn Ihr Update des angepassten Attributs die maximale Zeichenanzahl überschreitet, Array-Grenzen überschreitet oder wenn die Nutzer:in nicht in Braze existiert und Sie _update_existing_only = true gesetzt haben.

In diesen Fällen sollten Sie die Antwort als Hinweis darauf betrachten, dass Ihre Anfrage zwar abgeschlossen, das gewünschte Update jedoch nicht durchgeführt wurde. Prüfen Sie die oben genannten Gründe, um die Ursache zu ermitteln.
New Stuff!