Suivi utilisateur

Utilisez cet endpoint pour enregistrer les événements et les achats personnalisés et mettre à jour les attributs du profil utilisateur.

Conditions préalables

Pour utiliser cet endpoint, vous aurez besoin d’une clé API avec l’autorisation users.track.

Les clients utilisant l’API pour les appels de serveur à serveur devront peut-être inscrire rest.iad-01.braze.com dans la liste des autorisations s’ils sont derrière un pare-feu.

Limite de débit

Starting on October 28th, 2024, we apply a base speed limit of 3,000 requests per three seconds to this endpoint for all customers. Each /users/track request can contain up to 75 event objects, 75 attribute objects, and 75 purchase objects. Each object (event, attribute, and purchase arrays) can update one user each. In total, this means a maximum of 225 users can be updated in a single call. In addition, a single user profile can be updated by multiple objects.

Different limits apply to customers who have purchased Monthly Active Users - CY 24-25. For details on these limits, see Monthly Active Users - CY 24-25 limits.

See our page on API rate limits for details, and reach out to your customer success manager if you need your limit increased.

Corps de la demande

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),
}

Paramètres de demande

Exemple de requêtes

Mise à jour d’un profil utilisateur par adresse e-mail

Vous pouvez mettre à jour un profil utilisateur par adresse e-mail en utilisant l’endpoint /users/track.

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"
            }
        }
    ]
}'

Mise à jour d’un profil utilisateur par numéro de téléphone

Vous pouvez mettre à jour un profil utilisateur par numéro de téléphone en utilisant l’endpoint /users/track. Cet endpoint ne fonctionne que si vous indiquez un numéro de téléphone valide.

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"
            ]
        }
    ],
}'

Définir les groupes d’abonnement

Cet exemple montre comment créer un utilisateur et définir son groupe d’abonnement dans l’objet attributs de l’utilisateur.

La mise à jour de l’état de l’abonnement avec cet endpoint mettra à jour l’utilisateur spécifié par son external_id (par exemple User1) et mettra à jour l’état de l’abonnement de tous les utilisateurs ayant le même e-mail que cet utilisateur (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
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"
        }
      ]
    }
  ]
}'

Exemple de requête pour créer un utilisateur alias uniquement.

Vous pouvez utiliser l’endpoint /users/track pour créer un nouvel utilisateur alias uniquement en définissant la clé _update_existing_only avec une valeur false dans le corps de la requête. Si cette valeur est omise, le profil utilisateur alias uniquement ne sera pas créé. Un utilisateur alias uniquement permet de s’assurer qu’un seul profil avec cet alias existe. C’est notamment utile lorsque vous construisez une nouvelle intégration, car cela empêche la création de doublons de profil utilisateur

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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]"
        }
    ],
}'

Réponses

Lorsque vous utilisez l’une des requêtes API susmentionnées, vous devriez recevoir l’une des trois réponses générales suivantes : un message de réussite, un message de réussite avec des erreurs non fatales ou un message avec des erreurs fatales.

Message réussi

Les messages réussis seront envoyés avec la réponse suivante :

1
2
3
4
5
6
{
  "message": "success",
  "attributes_processed": (optional, integer), if attributes are included in the request, this will return an integer of the number of external_ids with attributes that were queued to be processed,
  "events_processed": (optional, integer), if events are included in the request, this will return an integer of the number of events that were queued to be processed,
  "purchases_processed": (optional, integer), if purchases are included in the request, this will return an integer of the number of purchases that were queued to be processed,
}

Message réussi sans erreurs fatales

Si votre message est réussi, mais qu’il y a des erreurs non fatales, comme un objet Événement non valide hors d’une longue liste d’événements, vous recevrez la réponse suivante :

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

Pour les messages de réussite, toutes les données non affectées par une erreur dans le tableau errors continueront d’être traitées.

Message avec erreurs fatales

Si votre message contient une erreur fatale, vous recevrez la réponse suivante :

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

Codes de réponse des erreurs fatales

Pour connaître les codes d’état et les messages d’erreur associés qui seront renvoyés si votre demande rencontre une erreur fatale, reportez-vous à la section Erreurs fatales et réponses.

Si vous recevez le message d’erreur “provided external_id is blacklistted and disallowed”, il se peut que votre demande contienne un “utilisateur fictif”. Pour plus d’informations, reportez-vous à la section Blocage des spams.

Foire aux questions

Que se passe-t-il lorsque plusieurs profils avec la même adresse e-mail sont trouvés ?

Si l’external_id existe, le profil le plus récemment mis à jour avec un ID externe sera utilisé en priorité pour les mises à jour. Si l’external_id n’existe pas, le profil le plus récemment mis à jour sera utilisé en priorité pour les mises à jour.

Que se passe-t-il si aucun profil avec l’adresse e-mail n’existe actuellement ?

Un nouveau profil sera créé, ainsi qu’un utilisateur exclusivement par e-mail. Aucun alias ne sera créé. Le champ e-mail sera défini sur [email protected], comme indiqué dans l’exemple de demande de mise à jour d’un profil utilisateur par l’adresse e-mail.

Comment utiliser /users/track pour importer des données utilisateur héritées ?

Vous pouvez soumettre des données via l’API de Braze pour un utilisateur qui n’a pas encore utilisé votre application mobile afin de générer un profil utilisateur. Si l’utilisateur se sert ultérieurement de l’application, toutes les informations qui suivent son identification via le SDK seront fusionnées avec le profil utilisateur existant que vous avez créé via l’appel d’API. Tout comportement de l’utilisateur enregistré de manière anonyme par le SDK avant l’identification sera perdu lors de la fusion avec le profil utilisateur existant généré par l’API.

L’outil de segmentation inclura ces utilisateurs, qu’ils aient utilisé l’application ou pas. Si vous souhaitez exclure les utilisateurs téléchargés via l’API utilisateur qui n’ont pas encore utilisé l’application, ajoutez le filtre Session Count > 0.

Comment /users/track gère-t-il les événements en double ?

Chaque objet d’événement du tableau d’objets représente une occurrence unique d’un événement personnalisé par un utilisateur à un moment donné. Cela signifie que chaque événement intégré dans Braze possède son propre ID, de sorte que les événements “dupliqués” sont traités comme des événements distincts et uniques.

Utilisateurs actifs par mois CY 24-25

Pour les clients qui ont acheté Utilisateurs actifs par mois - CY 24-25, Braze gère différentes limites de débit sur son endpoint /users/track:

• Les limites de débit horaire sont fixées en fonction de l’activité d’ingestion de données prévue sur votre compte, qui peut correspondre au nombre d’utilisateurs actifs par mois que vous avez achetés, au secteur d’activité, à la saisonnalité ou à d’autres facteurs.
• En plus de la limite des demandes par heure, Braze impose également une limite de rafale sur le nombre de demandes autorisées par seconde.
• Chaque demande peut comporter jusqu’à 50 mises à jour combinées pour des attributs, des événements ou des objets d’achat.

Les limites actuelles basées sur l’ingestion prévue sont disponibles dans le tableau de bord sous Paramètres > API et identifiants > Limites de l’API. Nous pouvons modifier les limites de débit pour protéger la stabilité du système ou permettre une augmentation du débit de données sur votre compte. Veuillez contacter l’assistance Braze ou votre gestionnaire satisfaction client pour toute question ou préoccupation concernant la limite de demande horaire ou par seconde et les besoins de votre entreprise.