Objet Attributs d’utilisateur

Une requête API contenant des champs dans l’objet attributes crée ou met à jour un attribut portant ce nom avec la valeur indiquée dans le profil utilisateur spécifié.

Utilisez les noms de champs de profil utilisateur Braze (énumérés ci-après ou tout autre champ répertorié dans la section Champs de profil utilisateur Braze) pour mettre à jour ces valeurs spéciales sur le profil utilisateur dans le tableau de bord, ou pour ajouter vos propres données d’attributs personnalisés à l’utilisateur.

Corps de l’objet

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

{
  // One of "external_id" or "user_alias" or "braze_id" or "email" or "phone" is required
  "external_id" : (optional, string) see external user ID,
  "user_alias" : (optional, User alias object),
  "braze_id" : (optional, string) Braze user identifier,
  "email": (optional, string) User email address,
  "phone": (optional, string) User phone number,
  // Setting this flag to true puts the API in "Update Only" mode.
  // When using a "user_alias", "Update Only" defaults to true.
  "_update_existing_only" : (optional, boolean),
  // See note regarding anonymous push token imports
  "push_token_import" : (optional, boolean),
  // Braze User Profile Fields
  "first_name" : "Alex",
  "email" : "[email protected]",
  // Custom Attributes
  "my_custom_attribute" : value,
  "my_custom_attribute_2" : {"inc" : int_value},
  "my_array_custom_attribute":[ "Value1", "Value2" ],
  // Adding a new value to an array custom attribute
  "my_array_custom_attribute" : { "add" : ["Value3"] },
  // Removing a value from an array custom attribute
  "my_array_custom_attribute" : { "remove" : [ "Value1" ]},
  // Array of objects custom attribute
  "my_array_of_objects_attribute": [{"key": "value"}, {"key": "value"}],
  // Adding to an array of objects (nested custom attribute syntax)
  "my_array_of_objects_attribute": { "$add": [{"key": "value"}] },
  // Removing from an array of objects (nested custom attribute syntax)
  "my_array_of_objects_attribute": { "$remove": [{"$identifier_key": "key", "$identifier_value": "value"}] },
}

• ID utilisateur externe
• Alias d’utilisateur

Remarque

Pour les attributs personnalisés de type tableau classiques, utilisez add et remove (sans $).

Pour les tableaux d’objets (attributs personnalisés imbriqués), utilisez $add, $remove et $update dans les payloads des requêtes /users/track. Ces opérateurs appliquent des modifications au niveau de l’objet en faisant correspondre des identifiants ($identifier_key et $identifier_value) et prennent en charge les mises à jour sur place avec $new_object.

Utilisez ce format lorsque vous devez ajouter, supprimer ou mettre à jour des objets dans un tableau existant tout en conservant le reste du tableau. Pour des exemples de requêtes complètes, consultez l’exemple d’API pour les tableaux d’objets et l’exemple de SDK pour les tableaux d’objets.

Pour supprimer un attribut de profil, définissez-le sur null. Certains champs, tels que external_id et user_alias, ne peuvent pas être supprimés une fois ajoutés à un profil utilisateur.

Résolution des identifiants

Sauf si vous effectuez une importation anonyme de jetons de notification push, chaque objet d’attributs utilisateur doit inclure au moins un identifiant : external_id, user_alias, braze_id, email ou phone. Dans la mesure du possible, n’incluez qu’un seul identifiant par objet afin d’éviter toute ambiguïté sur le profil utilisateur mis à jour ou créé.

Gardez les points suivants à l’esprit lorsque vous utilisez des identifiants :

• external_id et user_alias s’excluent mutuellement. Les inclure tous les deux dans le même objet d’attributs utilisateur renvoie une erreur. Pour ajouter un alias à un utilisateur qui possède déjà un external_id, utilisez l’endpoint /users/alias/new.
• email est prioritaire sur phone. Si email et phone sont tous deux inclus dans le même objet, Braze utilise email comme identifiant. Les attributs sont donc appliqués au profil utilisateur associé à cette adresse e-mail, même si le numéro de téléphone appartient à un autre profil.

Important

Pour éviter tout comportement inattendu, utilisez un seul identifiant par objet d’attributs utilisateur. Fournir plusieurs identifiants faisant référence à des profils utilisateurs différents peut entraîner l’application des attributs au mauvais profil.

Mettre à jour uniquement les profils existants

Si vous souhaitez uniquement mettre à jour des profils utilisateurs existants dans Braze, transmettez la clé _update_existing_only avec la valeur true dans le corps de votre requête. Si cette valeur est omise, Braze crée un nouveau profil utilisateur lorsque l’external_id n’existe pas encore.

Remarque

Si vous créez un profil utilisateur avec alias uniquement via l’endpoint /users/track, vous devez définir _update_existing_only sur false. Si vous omettez cette valeur, Braze ne crée pas le profil avec alias uniquement.

Importation de jetons de notification push

Avant d’importer des jetons de notification push dans Braze, vérifiez que c’est bien nécessaire. Une fois les SDK Braze en place, ils gèrent automatiquement les jetons de notification push, sans qu’il soit nécessaire de les téléverser via l’API.

Si vous devez malgré tout les téléverser via l’API, vous pouvez le faire pour des utilisateurs identifiés ou anonymes. Cela signifie qu’un external_id doit être présent, ou que les utilisateurs anonymes doivent avoir l’indicateur push_token_import défini sur true.

Remarque

Lorsque vous importez des jetons de notification push depuis d’autres systèmes, un external_id n’est pas toujours disponible. Pour maintenir la communication avec ces utilisateurs pendant votre transition vers Braze, vous pouvez importer les anciens jetons pour des utilisateurs anonymes sans fournir d’external_id, en définissant push_token_import sur true.

Lorsque vous définissez push_token_import sur true :

• external_id et braze_id ne doivent pas être spécifiés
• L’objet d’attributs doit contenir un jeton de notification push
• Si le jeton existe déjà dans Braze, la requête est ignorée ; sinon, Braze crée un profil utilisateur anonyme temporaire pour chaque jeton afin que vous puissiez continuer à envoyer des messages à ces personnes

Après l’importation, lorsque chaque utilisateur lance la version de votre application intégrant Braze, Braze déplace automatiquement son jeton de notification push importé vers son profil utilisateur Braze et supprime le profil temporaire.

Une fois par mois, Braze recherche les profils anonymes dotés de l’indicateur push_token_import qui n’ont pas de jeton de notification push. Si le profil anonyme n’a plus de jeton de notification push, Braze supprime le profil. En revanche, si le profil anonyme possède toujours un jeton de notification push, ce qui suggère que l’utilisateur réel ne s’est pas encore connecté sur l’appareil associé à ce jeton, Braze ne fait rien.

Pour plus d’informations, consultez Migrer des jetons de notification push.

Types de données des attributs personnalisés

Les types de données suivants peuvent être stockés en tant qu’attribut personnalisé :

Conseil

Pour savoir quand utiliser un événement personnalisé plutôt qu’un attribut personnalisé, consultez Événements personnalisés et Attributs personnalisés.

Exemple de tableau d’objets

Ce tableau d’objets vous permet de créer des Segments basés sur des critères spécifiques liés aux séjours, et de personnaliser vos messages à l’aide des données de chaque séjour grâce aux modèles Liquid.

1
2
3
4

{"hotel_stays": [
  { "hotel_name": "Ocean View Resort", "check_in_date": "2023-06-15", "nights_stayed": 5 },
  { "hotel_name": "Mountain Lodge", "check_in_date": "2023-09-10", "nights_stayed": 3 }
]}

Pour des exemples de tableaux d’objets utilisant $add, $remove et $update, consultez l’exemple d’API pour les tableaux d’objets et l’exemple de SDK pour les tableaux d’objets.

Champs du profil utilisateur de Braze

Important

Les champs du profil utilisateur suivants sont sensibles à la casse : veillez à les référencer en minuscules.

Conseil

Pour une référence des attributs standard destinée aux clients, organisée par catégorie et incluant des conseils pour le SDK, l’API, les fichiers CSV et Cloud Data Ingestion, consultez Attributs standard.

Les valeurs de langue définies explicitement via cette API sont prioritaires sur les informations de locale que Braze reçoit automatiquement de l’appareil.

Exemple de requête d’attributs utilisateur

Cet exemple contient quatre objets d’attributs utilisateur, sur un total de 75 objets d’attributs autorisés par appel d’API.

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

POST https://YOUR_REST_API_URL/users/track
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
{
  "attributes" : [
    {
      "external_id" : "user1",
      "first_name" : "Alex",
      "has_profile_picture" : true,
      "dob": "1988-02-14",
      "music_videos_favorited" : { "add" : [ "calvinharris-summer" ], "remove" : ["nickiminaj-anaconda"] }
    },
    {
      "external_id" : "user2",
      "first_name" : "Lee",
      "has_profile_picture" : false,
      "push_tokens": [{"app_id": "Your App Identifier", "token": "abcd", "device_id": "optional_field_value"}]

    },
    {
      "user_alias" : { "alias_name" : "device123", "alias_label" : "my_device_identifier"},
      "first_name" : "Yuri",
      "has_profile_picture" : false
    },
    {
      "external_id": "user3",
      "subscription_groups" : [{"subscription_group_id" : "subscription_group_identifier", "subscription_state" : "subscribed"}]
    }
  ]
}

Migrer les jetons de notification push

Vous envoyiez peut-être déjà des notifications push avant d’intégrer Braze, par vous-même ou via un autre fournisseur. La migration des jetons de notification push vous permet alors de continuer à envoyer des notifications push aux utilisateurs dont les jetons sont enregistrés.

Migration automatique via le SDK

Une fois le SDK de Braze intégré, les jetons de notification push de vos utilisateurs abonnés migrent automatiquement à leur prochaine ouverture de l’application. D’ici là, vous ne pouvez pas leur envoyer de notifications push via Braze.

Pour réengager vos utilisateurs plus rapidement, vous pouvez aussi migrer vos jetons de notification push manuellement.

Points à considérer pour les jetons Web

Les jetons de notification push Web ont des particularités. Tenez compte des points suivants lorsque vous mettez en place les notifications push pour le Web :

Migration manuelle via l’API

La migration manuelle des jetons de notification push consiste à importer ces clés déjà créées dans votre plateforme Braze au moyen de l’API.

Utilisez l’endpoint users/track pour migrer par programmation les jetons iOS (APNs) et Android (FCM) vers votre plateforme. Vous pouvez migrer les utilisateurs identifiés (associés à un ID externe) comme les utilisateurs anonymes (sans ID externe).

Remarque

Braze considère que les jetons de notification push importés sont des jetons de notification push de premier plan valides pour votre application et votre environnement.

Lorsque vous importez des jetons iOS, Braze ne stocke pas de passerelle Apple Push Notification service (APNs) (development ou production) pour ceux-ci. Braze envoie ces jetons via la passerelle configurée de votre application. Si un jeton a été généré pour l’autre environnement, APNs le rejette avec BadDeviceToken, et l’envoi échoue.

Braze ne stocke une passerelle pour le jeton que si le SDK enregistre ultérieurement le même jeton et signale une passerelle.

Pendant la migration, indiquez l’app_id de votre application pour que chaque jeton de notification push soit associé à la bonne application. Chaque application (iOS, Android, etc.) possède son propre app_id. Vous le trouverez dans la section Identification de la page Clés API. Veillez à utiliser l’app_id de la bonne plateforme.

Important

L’API ne permet pas de migrer les jetons de notification push Web, car ils ne suivent pas le même schéma que ceux des autres plateformes.

Si vous essayez de migrer des jetons de notification push Web par programmation, une erreur de ce type peut s’afficher : Received '400: Invalid subscription auth' sending to 'https://fcm.googleapis.com/fcm/send

Plutôt que de passer par l’API, nous vous recommandons d’intégrer le SDK et de laisser votre base de jetons se reconstituer naturellement.

• id externe présent
• id externe manquant

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-API-KEY-HERE' \
--data-raw '{
  "attributes" : [
    {
      "push_token_import" : false,
      "external_id": "example_external_id",
      "country": "US",
      "language": "en",
      "YOUR_CUSTOM_ATTRIBUTE": "YOUR_VALUE",
      "push_tokens": [
        {"app_id": "APP_ID_OF_OS", "token": "PUSH_TOKEN_STRING"}
      ]
    }
  ]
}'

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

curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-API-KEY-HERE' \
--data-raw '{
  "attributes": [
    {
      "push_token_import" : true,
      "email": "[email protected]",
      "country": "US",
      "language": "en",
      "YOUR_CUSTOM_ATTRIBUTE": "YOUR_VALUE",
      "push_tokens": [
        {"app_id": "APP_ID_OF_OS", "token": "PUSH_TOKEN_STRING", "device_id": "DEVICE_ID"}
      ]
    },

    {
      "push_token_import" : true,
      "email": "[email protected]",
      "country": "US",
      "language": "en",
      "YOUR_CUSTOM_ATTRIBUTE_1": "YOUR_VALUE",
      "YOUR_CUSTOM_ATTRIBUTE_2": "YOUR_VALUE",
      "push_tokens": [
        {"app_id": "APP_ID_OF_OS", "token": "PUSH_TOKEN_STRING", "device_id": "DEVICE_ID"}
      ]
    }
  ]
}'

Importer des jetons de notification push iOS

Lorsque vous migrez des jetons de notification push iOS avec /users/track, le champ gateway n’est pas défini sur le jeton. Braze considère que les jetons importés via l’API sont des jetons de notification push au premier plan valides. En revanche, Braze ne peut pas déterminer à quel environnement APNs chaque jeton appartient.

Sans ce champ, Braze utilise le paramètre d’environnement de repli configuré pour votre application lors de l’envoi des notifications push. Des erreurs BadDeviceToken peuvent donc survenir si l’environnement réel du jeton diffère de cet environnement de repli. Par exemple, l’envoi d’un jeton de développement via la passerelle de production échouera.

Pour éviter les problèmes de distribution :

• Vérifiez que le paramètre d’environnement de votre application dans le tableau de bord de Braze correspond aux jetons que vous importez.
• Pour les applications en production, importez uniquement des jetons de production.
• Pour les environnements de test, vérifiez que la configuration de votre application et les jetons importés utilisent tous deux l’environnement de développement.

Remarque

Les jetons enregistrés via le SDK de Braze incluent automatiquement le champ gateway, car le SDK détecte l’environnement à partir des droits (entitlements) de votre application.

Importer des jetons de notification push Android

Important

Ce point ne concerne que les applications Android. Les applications iOS n’ont pas besoin de ces étapes, car cette plateforme ne dispose que d’un seul framework d’affichage des notifications push. Les notifications push s’y affichent immédiatement, tant que Braze dispose des jetons et des certificats nécessaires.

Si vous devez envoyer des notifications push Android à vos utilisateurs avant la fin de l’intégration du SDK de Braze, utilisez des paires clé-valeur pour valider les notifications push.

Vous devez disposer d’un récepteur capable de traiter et d’afficher les payloads push. Pour signaler le payload push au récepteur, ajoutez les paires clé-valeur nécessaires à la Campaign de notification push. Les valeurs de ces paires dépendent du partenaire push que vous utilisiez avant Braze.

Remarque

Pour certains fournisseurs de notifications push, Braze doit aplatir les paires clé-valeur afin qu’elles soient correctement interprétées. Pour aplatir les paires clé-valeur d’une application Android donnée, contactez votre gestionnaire de la satisfaction client.

Foire aux questions

Comment trouver les utilisateurs considérés comme du spam ou bloqués pour l’envoi de messages ?

Braze ne propose pas de liste de spam dédiée dans le tableau de bord. Braze bloque les profils utilisateurs individuels (« utilisateurs fictifs ») qui comptent plus de cinq millions de sessions, plus de 20 000 noms d’événements personnalisés distincts ou plus de 20 000 noms de produits distincts dans les achats. Toutes les données entrantes pour ce profil cessent alors d’être ingérées, qu’elles proviennent des SDK ou de l’API REST. Si un identifiant est bloqué, /users/track peut renvoyer l’erreur "provided external_id is blacklisted and disallowed". Ce libellé est repris tel quel de la réponse de l’API.

Pour trouver les profils bloqués en raison d’un nombre excessif de sessions, créez un Segment avec le filtre Nombre de sessions défini sur plus de 5 000 000. Exportez ensuite le Segment au format CSV, puis vérifiez les champs des profils dans Engagement > Rechercher des utilisateurs ou avec l’endpoint /users/export/ids.

Il n’existe pas de filtre équivalent pour les noms d’événements personnalisés ou les noms de produits distincts. Pour identifier les profils bloqués pour ces raisons, contactez votre gestionnaire de compte Braze. Pour en savoir plus, consultez la page Blocage des spams.