Suivi utilisateur
Utilisez cet endpoint pour enregistrer les événements et les achats personnalisés et mettre à jour les attributs du profil utilisateur.
Braze traite les données transmises par l’API à leur valeur nominale, et les clients ne doivent transmettre que des deltas (données changeantes) afin de minimiser la consommation inutile de points de données. Pour en savoir plus, consultez la rubrique Points de données.
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
À partir du 28 octobre 2024, nous appliquons une limite de vitesse de base de 3 000 requêtes par trois secondes à cet endpoint pour tous les clients. Chaque demande /users/track
peut contenir jusqu’à 75 objets d’événement, 75 objets d’attributs et 75 objets d’achats. Chaque objet (événement, attribut et tableau d’achat) peut mettre à jour un utilisateur chacun. Au total, cela signifie qu’un maximum de 225 utilisateurs peuvent être mis à jour en un seul appel. En outre, un profil utilisateur unique peut être mis à jour par plusieurs objets.
Des limites différentes s’appliquent aux clients qui ont acheté le service Utilisateurs actifs par mois - CY 24-25. Pour plus de détails sur ces limites, voir Utilisateurs actifs par mois - Limites CY 24-25.
Consultez notre page sur les Limites de débit de l’API pour plus de détails, et contactez votre gestionnaire du succès des clients si vous avez besoin d’élever votre limite.
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
Pour chaque composant de requête répertorié dans le tableau suivant, l’un des éléments suivants est requis : external_id
, user_alias
, braze_id
, email
ou phone
.
Paramètre | Requis | Type de données | Description |
---|---|---|---|
attributes |
Facultatif | Tableau d’objets Attributs | Voir objet attributs de l’utilisateur |
events |
Facultatif | Tableau d’objets Événement | Voir l’objet “événements”. |
purchases |
Facultatif | Tableau d’objets Achat | Voir les achats d’objets |
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.
Si vous incluez une demande avec email
et phone
, Braze utilisera l’e-mail comme identifiant.
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
N’envoyez pas d’e-mails transactionnels légalement obligatoires aux passerelles SMS, car il y a de fortes chances que ces e-mails ne soient pas délivrés.
Bien que les e-mails que vous envoyez en utilisant un numéro de téléphone et le domaine de passerelle du fournisseur (connu sous le nom de MM3) puissent entraîner la réception de l’e-mail sous forme de message SMS (texte), certains de nos fournisseurs d’e-mail ne prennent pas en charge ce comportement. Par exemple, si vous envoyez un e-mail à un numéro de téléphone T-Mobile (tel que “[email protected]”), votre message SMS sera envoyé à la personne qui possède ce numéro de téléphone sur le réseau T-Mobile.
Gardez à l’esprit que même si ces e-mails ne sont pas délivrés à la passerelle SMS, ils seront tout de même pris en compte dans votre facturation d’e-mails. Pour éviter d’envoyer des e-mails à des passerelles non prises en charge, consultez la liste des noms de domaine des passerelles non prises en charge.
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 utilise ensuite l’application, toutes les informations relatives à son identification à l’aide du SDK seront fusionnées avec le profil utilisateur existant que vous avez créé à l’aide de l’appel 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 à l’aide de 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 horaire, Braze applique une limite de rafale sur le nombre de demandes qui peuvent être envoyées toutes les trois secondes.
- 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 peuvent être trouvées dans le tableau de bord sous Paramètres > API et identifiants > Tableau de bord de l’utilisation 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.