Objet Attributs d’utilisateur

Une requête API contenant des champs dans l’objet attributes crée ou met à jour un attribut de 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 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 ajoutez 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 externe
• Alias d’utilisateur

Remarque

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

Pour les tableaux d’objets (attributs personnalisés imbriqués), utilisez $add, $remove et $update dans les payloads de requête /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 à l’intérieur d’un tableau existant tout en préservant le reste de l’état du tableau. Pour des exemples de requêtes complets, consultez Exemple d’API pour les tableaux d’objets et Exemple SDK pour les tableaux d’objets.

Pour supprimer un attribut de profil, définissez-le sur null. Certains champs, comme 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 push, chaque objet d’attributs utilisateur doit contenir au moins un identifiant : external_id, user_alias, braze_id, email ou phone. Dans la mesure du possible, incluez un seul identifiant par objet afin d’éviter toute ambiguïté quant au profil utilisateur mis à jour ou créé.

Gardez les points suivants à l’esprit lors de l’utilisation des identifiants :

• external_id et user_alias sont mutuellement exclusifs. Inclure 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 a la priorité sur phone. Si email et phone sont tous deux inclus dans le même objet, Braze utilise email comme identifiant. Cela signifie que les attributs sont appliqués au profil utilisateur associé à cette adresse e-mail, même si le numéro de téléphone appartient à un profil différent.

Important

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

Mettre à jour uniquement les profils existants

Si vous souhaitez mettre à jour uniquement les profils utilisateur existants dans Braze, vous devez passer 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 si l’external_id n’existe pas déjà.

Remarque

Si vous créez un profil utilisateur de type 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 de type alias uniquement.

Importation de jetons push

Avant d’importer des jetons push vers Braze, vérifiez bien si cela est nécessaire. Lorsque les SDK Braze sont mis en place, ils gèrent les jetons push automatiquement sans qu’il soit nécessaire de les télécharger via l’API.

Si vous estimez devoir les télécharger via l’API, ils peuvent être téléchargés pour des utilisateurs identifiés ou des utilisateurs anonymes. Cela signifie qu’un external_id doit être présent, ou que les utilisateurs anonymes doivent avoir le flag push_token_import défini sur true.

Remarque

Lors de l’importation de jetons 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 jetons historiques pour les utilisateurs anonymes sans fournir d’external_id en spécifiant push_token_import comme true.

Lorsque vous spécifiez push_token_import comme true :

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

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

Braze vérifie une fois par mois s’il existe un profil anonyme avec le flag push_token_import qui ne possède pas de jeton push. Si le profil anonyme n’a plus de jeton push, Braze supprime le profil. Cependant, si le profil anonyme possède encore un jeton push, ce qui suggère que l’utilisateur réel ne s’est pas encore connecté à l’appareil avec ce jeton push, Braze ne fait rien.

Pour plus d’informations, consultez Migration des jetons 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 au sein des séjours, et de personnaliser vos messages en utilisant les données de chaque séjour avec les 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 Exemple d’API pour les tableaux d’objets et Exemple SDK pour les tableaux d’objets.

Champs du profil utilisateur Braze

Important

Les champs de profil utilisateur suivants sont sensibles à la casse, assurez-vous donc de les référencer en minuscules.

Conseil

Pour une référence destinée aux clients sur les attributs standard, organisée par catégorie et incluant des recommandations pour le SDK, l’API, le CSV et l’ingestion de données cloud, consultez Attributs standard.

Les valeurs de langue définies explicitement via cette API ont la priorité sur les informations de localisation 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 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 push

Si vous envoyiez des notifications push avant d’intégrer Braze, que ce soit par vos propres moyens ou via un autre fournisseur, la migration des jetons push vous permet de continuer à envoyer des notifications push à vos utilisateurs disposant de jetons push enregistrés.

Migration automatique via le SDK

Après avoir intégré le SDK Braze, les jetons push de vos utilisateurs ayant accepté les notifications sont automatiquement migrés lors de leur prochaine ouverture de votre application. Jusqu’alors, vous ne pouvez pas envoyer de notifications push à ces utilisateurs via Braze.

Vous pouvez également migrer vos jetons push manuellement, ce qui vous permet de réengager vos utilisateurs plus rapidement.

Considérations relatives aux jetons web

En raison de la nature des jetons push web, tenez compte des éléments suivants lors de l’implémentation du push pour le web :

Migration manuelle via l’API

La migration manuelle des jetons push consiste à importer ces clés précédemment créées dans votre plateforme Braze via l’API.

Migrez de manière programmatique les jetons iOS (APNs) et Android (FCM) vers votre plateforme en utilisant l’endpoint users/track. Vous pouvez migrer aussi bien les utilisateurs identifiés (utilisateurs associés à un ID externe) que les utilisateurs anonymes (utilisateurs sans ID externe).

Spécifiez l’app_id de votre application lors de la migration des jetons push pour associer le jeton push approprié à l’application correspondante. Chaque application (iOS, Android, etc.) dispose de son propre app_id, que vous pouvez trouver dans la section Identification de la page Clés API. Veillez à utiliser l’app_id de la plateforme correcte.

Important

Il n’est pas possible de migrer les jetons push web via l’API. En effet, les jetons push web ne respectent pas le même schéma que les autres plateformes.

Si vous tentez de migrer des jetons push web de manière programmatique, vous pourriez voir une erreur semblable à la suivante : Received '400: Invalid subscription auth' sending to 'https://fcm.googleapis.com/fcm/send

Comme alternative à la migration par 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 absent

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 push iOS

Lors de la migration de jetons push iOS avec /users/track, le champ gateway n’est pas défini sur le jeton push. Braze suppose que les jetons importés via l’API sont des jetons push de premier plan valides, mais ne peut pas déterminer à quel environnement APNs le jeton appartient.

Sans le champ gateway, Braze utilise le paramètre d’environnement de secours configuré pour votre application lors de l’envoi de notifications push. Cela peut entraîner des erreurs BadDeviceToken si l’environnement réel du jeton diffère du paramètre de secours configuré. Par exemple, un jeton de développement envoyé via le gateway de production échouera.

Pour éviter les problèmes de distribution :

• Assurez-vous 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 les jetons de production.
• Pour les environnements de test, vérifiez que la configuration de votre application et les jetons importés utilisent l’environnement de développement.

Remarque

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

Importer des jetons push Android

Important

La considération suivante s’applique uniquement aux applications Android. Les applications iOS ne nécessitent pas ces étapes car cette plateforme ne dispose que d’un seul framework pour l’affichage des notifications push, et les notifications push s’affichent immédiatement tant que Braze dispose des jetons push et des certificats nécessaires.

Si vous devez envoyer des notifications push Android à vos utilisateurs avant que l’intégration du SDK Braze ne soit terminée, utilisez des paires clé-valeur pour valider les notifications push.

Vous devez disposer d’un récepteur pour gérer et afficher les payloads push. Pour notifier le récepteur du payload push, ajoutez les paires clé-valeur nécessaires à la Campaign push. Les valeurs de ces paires dépendent du fournisseur de push spécifique que vous utilisiez avant Braze.

Remarque

Pour certains fournisseurs de notifications push, Braze doit aplatir les paires clé-valeur afin qu’elles puissent être correctement interprétées. Pour aplatir les paires clé-valeur d’une application Android spécifique, contactez votre gestionnaire du succès des clients.

Questions fréquentes

Comment trouver les utilisateurs traités comme spam ou bloqués pour la communication ?

Braze ne fournit pas de liste de spam dédiée dans le tableau de bord. Braze bloque les profils utilisateurs individuels (« utilisateurs fictifs ») ayant 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, et cesse d’ingérer toutes les données entrantes pour ce profil, aussi bien depuis les SDK que depuis la REST API. 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 Session Count défini sur more than 5,000,000, exportez le Segment au format CSV, puis vérifiez les champs du profil dans Engagement > Search users ou avec l’endpoint /users/export/ids. Il n’existe pas de filtre équivalent pour les noms d’événements personnalisés distincts ou les noms de produits, contactez donc votre gestionnaire de compte Braze pour identifier les profils bloqués pour ces raisons. Pour en savoir plus, consultez Blocage du spam.