Créer et mettre à jour des utilisateurs

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

Remarque

Chaque attribut personnalisé envoyé dans une requête à /users/track consomme un point de donnée. Pour plus d’informations, consultez Points de donnée.

Braze traite les données transmises par l’API telles quelles. Ne transmettez que les deltas (données modifiées) afin de limiter la consommation inutile de points de données.

Besoin de mettre à jour des utilisateurs en masse ?

Utilisez l’endpoint /users/track/bulk pour envoyer des lots plus importants et réduire le volume de requêtes.

Suivi de l’état de traitement des requêtes

Important

Le suivi de l’état de traitement des requêtes est en bêta. Si vous souhaitez participer à la bêta, contactez votre gestionnaire de compte Braze.

Braze traite les requêtes /users/track de manière asynchrone. Une réponse réussie signifie que Braze a reçu votre requête et l’a mise en file d’attente pour traitement, mais les données ne figurent peut-être pas encore sur le profil utilisateur. Pour confirmer la fin du traitement, ajoutez un group_id à vos requêtes et vérifiez l’état du groupe avec l’endpoint /users/track/status.

Utilisez le suivi de l’état de traitement des requêtes pour :

• Confirmer que les mises à jour d’attributs ou d’abonnements figurent sur un profil avant de déclencher un Canvas ou une Campaign qui en dépend
• Confirmer qu’un remplissage rétroactif ou une importation est terminé avant d’envoyer des messages aux utilisateurs concernés
• Conserver une trace attestant que les mises à jour hautement prioritaires, telles que les modifications de consentement, ont bien été traitées

Fonctionnement

1. Choisissez un group_id pour un ensemble de requêtes associées. Par exemple, utilisez un même group_id pour toutes les requêtes d’un remplissage rétroactif, ou un group_id unique pour une seule requête que vous souhaitez confirmer.
2. Incluez le group_id au niveau supérieur du corps de chaque requête /users/track. Braze comptabilise chaque requête acceptée dans le groupe.
3. Appelez l’endpoint /users/track/status avec le group_id. Lorsque le status du groupe est completed, Braze a terminé le traitement de toutes les requêtes du groupe.

Si vous envoyez une autre requête avec le même group_id après que le groupe est passé à completed, l’état du groupe repasse à processing jusqu’à ce que Braze ait terminé le traitement de la nouvelle requête.

Braze suit l’état de chaque groupe dans son ensemble. Un groupe est completed lorsque Braze a terminé le traitement de toutes les requêtes du groupe, y compris celles dont Braze a rejeté certains objets. Braze liste les objets rejetés dans le tableau errors de chaque réponse /users/track.

Le suivi de l’état n’est disponible que pour l’endpoint /users/track. Braze ne suit pas l’état des requêtes envoyées à l’endpoint /users/track/bulk ou à l’endpoint /users/track/sync.

Exigences relatives à l’identifiant de groupe

Un group_id doit contenir entre 1 et 128 caractères et ne peut inclure que des lettres, des chiffres, des points (.), des tirets bas (_), des tildes (~) et des tirets (-).

Les identifiants de groupe sont propres à un espace de travail. Le même group_id dans deux espaces de travail désigne deux groupes distincts.

Utilisez un nouveau group_id pour chaque ensemble de requêtes que vous souhaitez suivre. Réutiliser un group_id ajoute des requêtes au groupe existant sans prolonger sa période de rétention.

Limites et rétention

Erreurs de suivi de l’état

Dans certains cas, Braze ne peut pas suivre l’état d’une requête, par exemple lorsque votre espace de travail a atteint son nombre maximal de groupes actifs. La réponse /users/track reste alors réussie et Braze traite tout de même les attributs, événements et achats de la requête. La réponse inclut une entrée dans le tableau errors qui explique pourquoi Braze ne suit pas la requête :

1
2
3
4
5
6
7
8

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

Foire aux questions

Important

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 envoyés en utilisant un numéro de téléphone et le domaine de passerelle du fournisseur (connu sous le nom de MM3) puissent être reçus 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 comptabilisés 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, Braze donne la priorité au profil le plus récemment mis à jour possédant un ID externe. Si l’external_id n’existe pas, Braze donne la priorité au profil le plus récemment mis à jour.

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

Braze crée un profil et un utilisateur e-mail uniquement, et définit le champ e-mail sur [email protected], comme indiqué dans l’exemple de requête de mise à jour d’un profil utilisateur par adresse e-mail. Braze ne crée pas d’alias.

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

Vous pouvez envoyer 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 postérieures à son identification via le SDK sont fusionnées avec le profil utilisateur existant que vous avez créé par l’appel API. Tout comportement utilisateur enregistré de manière anonyme par le SDK avant l’identification est perdu lors de la fusion avec le profil utilisateur existant généré par l’API.

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

Comment éviter la création de profils utilisateurs en double ?

Des profils en double peuvent apparaître lorsqu’une requête inclut un identifiant primaire (tel que external_id) qui ne correspond à aucun profil existant, accompagné d’une valeur email ou phone qui, elle, correspond à un profil existant. Comme les identifiants primaires servent à la recherche d’utilisateur, Braze crée un nouveau profil pour l’external_id non reconnu au lieu de mettre à jour le profil existant basé uniquement sur l’e-mail ou le téléphone.

Pour éviter les doublons :

• Lorsque vous faites passer des utilisateurs de profils basés uniquement sur l’e-mail ou le téléphone à des profils identifiés, utilisez l’endpoint /users/identify pour attribuer un external_id au profil existant, plutôt que d’envoyer les deux à /users/track.
• Si des doublons existent déjà, fusionnez-les à l’aide de l’endpoint /users/merge.

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

Chaque objet d’événement du tableau d’événements représente une occurrence unique d’un événement personnalisé réalisé par un utilisateur à un moment donné. Chaque événement ingéré dans Braze possède donc son propre ID d’événement : les événements « dupliqués » sont traités comme des événements distincts et uniques.

Comment /users/track gère-t-il les attributs personnalisés imbriqués non valides ?

Lorsqu’un attribut personnalisé imbriqué contient des valeurs non valides (telles que des formats d’heure incorrects ou des valeurs nulles), Braze écarte du traitement toutes les mises à jour d’attributs personnalisés imbriqués de la requête. Cela s’applique à toutes les structures imbriquées de cet attribut. Pour garantir un traitement réussi, vérifiez que toutes les valeurs des attributs personnalisés imbriqués sont valides avant l’envoi.

Les requêtes envoyées à /users/track sont-elles forcément traitées dans l’ordre ?

Lorsque vous effectuez plusieurs appels API distincts à /users/track en succession rapide, Braze ne peut pas garantir que les requêtes sont traitées dans l’ordre exact où elles ont été envoyées ou reçues. En effet, Braze utilise un traitement asynchrone pour maximiser la vitesse et la flexibilité.

Par exemple, si vous envoyez plusieurs requêtes de mise à jour pour le même utilisateur à quelques secondes d’intervalle (certaines avec des valeurs d’attribut nulles, d’autres avec des valeurs valides), les requêtes contenant des valeurs nulles peuvent être traitées après celles contenant des valeurs valides, même si elles ont été envoyées plus tôt. Les valeurs d’attribut peuvent alors sembler revenir en arrière ou ne pas refléter la dernière mise à jour envoyée.

Pour éviter les conditions de concurrence lors de la mise à jour des données utilisateur :

• Regroupez les mises à jour dans une seule requête : incluez toutes les mises à jour d’attributs d’un utilisateur dans un seul appel API plutôt que d’effectuer des appels consécutifs séparés.
• Ajoutez des délais entre les requêtes : si vous devez effectuer des appels séparés pour le même utilisateur, ajoutez un délai (quelques secondes) entre les requêtes pour laisser la première terminer son traitement avant l’envoi de la suivante.
• Évitez les mises à jour simultanées du même champ : si deux requêtes mettent à jour le même attribut avec des valeurs différentes, envoyez ces mises à jour dans une seule requête ou espacez-les d’un délai pour réduire le risque de résultats dans le désordre.
• Confirmez le traitement avant la requête suivante (bêta) : incluez un group_id dans la première requête, puis attendez que l’endpoint /users/track/status renvoie completed avant d’envoyer la requête dépendante. Pour plus d’informations, consultez Suivi de l’état de traitement des requêtes.

Pour plus d’informations sur les conditions de concurrence et les bonnes pratiques, consultez Conditions de concurrence.

Comment savoir quand Braze a terminé le traitement de ma requête ?

Incluez un group_id dans vos requêtes /users/track, puis appelez l’endpoint /users/track/status avec ce group_id. Lorsque le status du groupe est completed, Braze a terminé le traitement de toutes les requêtes du groupe. Cette fonctionnalité est en bêta. Pour plus d’informations, consultez Suivi de l’état de traitement des requêtes.

À quelle fréquence dois-je vérifier l’état d’un groupe ?

Interrogez l’endpoint /users/track/status à intervalle régulier, par exemple toutes les quelques secondes, et arrêtez lorsque le status du groupe est completed. Restez dans la limite de débit de l’endpoint, soit 1 500 requêtes par minute et par espace de travail.

Pourquoi mon groupe est-il toujours en cours de traitement ?

Un groupe reste en processing jusqu’à ce que Braze ait terminé le traitement de chaque requête acceptée dans le groupe. Si une requête échoue pendant le traitement, Braze la relance, et le groupe reste en processing jusqu’à ce que la relance aboutisse. Si vous ajoutez des requêtes à un groupe déjà completed, son état repasse à processing. Dans de rares cas, un groupe peut rester en processing jusqu’à la fin de sa période de rétention. Si un groupe reste en processing beaucoup plus longtemps que votre temps de traitement habituel, contactez l’assistance Braze.

Pourquoi /users/track/status renvoie-t-il un tableau results vide ?

Le tableau results est vide lorsque Braze ne trouve pas le groupe dans votre espace de travail. Cela se produit lorsque la période de rétention de 24 heures du groupe est terminée, lorsque le group_id ne correspond pas à celui de vos requêtes, ou lorsque vous avez envoyé les requêtes à un autre espace de travail. Cela se produit également lorsque Braze n’a suivi aucune requête pour ce group_id. Vérifiez chaque réponse /users/track à la recherche d’erreurs de suivi de l’état.

Pourquoi la réponse de /users/track est-elle plus lente que prévu ?

Les appels /users/track réussis sont généralement acceptés rapidement, mais Braze traite toujours les mises à jour d’attributs, d’événements et d’achats de manière asynchrone. La latence perçue peut augmenter lorsque les payloads sont volumineux ou lorsque le routage réseau vers votre endpoint REST est lent. Si vous avez besoin d’un accusé de réception synchrone par utilisateur ou d’un ordre plus strict entre les appels, consultez /users/track/sync (bêta limitée).

Pourquoi /users/track renvoie-t-il 429 Too Many Requests ?

Lorsque votre volume de requêtes dépasse la limite de débit, /users/track renvoie une réponse HTTP 429 Too Many Requests. Pour reprendre l’envoi de requêtes :

1. Suspendez les requêtes pendant le nombre de secondes indiqué dans l’en-tête de réponse X-RateLimit-Retry-After.
2. Reprenez les requêtes à un rythme plus faible pour réduire la probabilité d’une nouvelle réponse 429.
3. Regroupez les mises à jour lorsque c’est possible, et respectez la limite d’objets par requête de votre compte.
4. Utilisez le tableau de bord d’utilisation de l’API pour repérer les pics de requêtes et les tendances de réponses 429. Pour les valeurs par défaut de l’espace de travail et les limites des autres endpoints, consultez Limites de débit de l’API.

Pour les réponses autres que 429 sur les contrats pris en charge, utilisez les en-têtes de réponse X-RateLimit-* décrits dans En-têtes de limite de débit pour les utilisateurs actifs mensuels CY 24-25, Universal MAU, Web MAU et Mobile MAU pour connaître le nombre de requêtes restantes dans la fenêtre en cours.

Pourquoi est-ce que je reçois une erreur 400 Bad Request avec une erreur de syntaxe ou d’analyse ?

Une erreur HTTP 400 accompagnée d’une erreur de syntaxe ou d’analyse signifie généralement que le corps de la requête n’est pas un JSON valide. Les causes courantes sont les virgules finales, les commentaires dans le JSON, les chaînes entre guillemets simples, une accolade ouvrante { en trop avant le payload, ou l’envoi d’un corps non JSON alors que l’en-tête Content-Type est application/json. Validez vos payloads avec un linter JSON avant l’envoi, vérifiez que votre client HTTP encode bien les objets en JSON (plutôt que de concaténer des chaînes brutes) et que le corps est encodé en UTF-8. Pour les autres réponses 400 (par exemple, la taille du payload et les limites d’objets par requête), reportez-vous à Erreurs fatales et réponses et au tableau Erreurs spécifiques à l’endpoint de cette page.

Utilisateurs actifs mensuels CY 24-25, Universal MAU, Web MAU et Mobile MAU

Pour les clients bénéficiant de la nouvelle tarification, les limites de débit sont appliquées au niveau de l’entreprise. Les clients peuvent définir des limites de débit horaires par espace de travail, mais les limites de rafale restent partagées entre tous les espaces de travail.

Pour les clients qui ont acheté des utilisateurs actifs mensuels CY 24-25, Universal MAU, Web MAU ou Mobile MAU, Braze applique des limites de débit différentes sur son endpoint /users/track :

• Les limites de débit horaires sont fixées en fonction de l’activité d’ingestion de données prévue sur votre compte, qui peut dépendre du nombre d’utilisateurs actifs par mois que vous avez achetés, de votre secteur d’activité, de la saisonnalité ou d’autres facteurs.
• En plus de la limite horaire, Braze applique une limite de rafale sur le nombre de requêtes pouvant être envoyées toutes les trois secondes.
• Chaque requête peut regrouper jusqu’à 75 mises à jour au total, réparties entre objets d’attributs, d’événements ou d’achats.

Les limites actuelles basées sur l’ingestion prévue sont disponibles 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 afin de protéger la stabilité du système ou de permettre un débit de données plus élevé sur votre compte. Pour toute question concernant la limite de requêtes horaire ou par seconde et les besoins de votre entreprise, contactez l’assistance Braze ou votre gestionnaire du succès des clients.

En-têtes de limite de débit pour les utilisateurs actifs mensuels CY 24-25, Universal MAU, Web MAU et Mobile MAU

Toutes les réponses non limitées par le débit (c’est-à-dire autres que 429) contiennent les en-têtes de réponse HTTP suivants, qui indiquent au client l’état de la fenêtre de limite de débit horaire. Utilisez ces en-têtes pour gérer votre rythme de requêtes :

Notez que les en-têtes RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset ne sont pas renvoyés lorsque vous rencontrez une erreur HTTP 429. Dans ce cas, ils sont remplacés par un en-tête X-RateLimit-Retry-After qui renvoie un nombre entier indiquant le nombre de secondes à attendre avant de pouvoir recommencer à envoyer des requêtes.

Vous pouvez télécharger le document OpenAPI et l’utiliser pour valider des schémas. Pour savoir comment procéder, consultez Utiliser les schémas OpenAPI pour valider les requêtes.