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" : "Jon",
  "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 (REST API syntax)
  "my_array_of_objects_attribute": { "add": [{"key": "value"}] },
  // Removing from an array of objects (REST API syntax)
  "my_array_of_objects_attribute": { "remove": [{"$identifier_key": "key", "$identifier_value": "value"}] },
}

• ID utilisateur externe
• Alias d’utilisateurs

Remarque

Pour les requêtes REST API vers /users/track, utilisez les clés add, remove et update pour les opérations sur les tableaux. Les clés préfixées par $ (telles que $add) sont destinées aux payloads des méthodes SDK.

Lorsqu’une requête REST API utilise $add, $remove ou $update, Braze peut renvoyer success sans appliquer la mise à jour du tableau.

Pour plus de détails, consultez l’exemple d’API de tableau d’objets et l’exemple SDK de tableau 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 après avoir été ajoutés à un profil utilisateur.

Résolution des identifiants

À moins que vous n’effectuiez 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, 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 d’identifiants :

• external_id et user_alias sont mutuellement exclusifs. L’inclusion des 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 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

Afin d’éviter tout comportement inattendu, utilisez un seul identifiant par objet d’attributs utilisateur. Fournir plusieurs identifiants qui renvoient à différents profils utilisateurs peut entraîner l’application d’attributs au mauvais profil.

Mettre à jour les profils existants uniquement

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 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éera pas le profil contenant uniquement un alias.

Importation de jetons de notification push

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

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

Remarque

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

Lorsque vous indiquez 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 de notification push
• Si le jeton existe déjà dans Braze, la requête est ignorée ; dans le cas contraire, 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 transfère automatiquement son jeton de notification push importé vers son profil utilisateur Braze et supprime le profil temporaire.

Braze effectue une vérification mensuelle afin d’identifier tout profil anonyme marqué de l’indicateur push_token_import et ne disposant pas de jeton de notification push. Si le profil anonyme ne dispose plus d’un jeton de notification push, Braze supprime le profil. Toutefois, si le profil anonyme dispose toujours d’un jeton de notification push, ce qui indique que l’utilisateur réel ne s’est pas encore connecté à l’appareil avec ledit jeton, Braze ne prend aucune mesure.

Pour plus d’informations, consultez Migration 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 les sections Événements personnalisés et Attributs personnalisés.

Exemple de tableau d’objets

Ce tableau d’objets vous permet de créer des segments en fonction de critères spécifiques au sein des 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 d’API utilisant add, remove et update, consultez l’exemple d’API de tableau d’objets. Pour des exemples SDK utilisant $add, $remove et $update, consultez l’exemple SDK de tableau d’objets.

Champs de profil utilisateur Braze

Important

Les champs de 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 utilisateurs, organisée par catégorie et incluant des conseils pour le SDK, l’API, le CSV et l’Ingestion de données cloud, consultez la section Attributs standard.

Les paramètres linguistiques explicitement définis via cette API ont priorité sur les informations régionales 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" : "Jon",
      "has_profile_picture" : true,
      "dob": "1988-02-14",
      "music_videos_favorited" : { "add" : [ "calvinharris-summer" ], "remove" : ["nickiminaj-anaconda"] }
    },
    {
      "external_id" : "user2",
      "first_name" : "Jill",
      "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" : "Alice",
      "has_profile_picture" : false
    },
    {
      "external_id": "user3",
      "subscription_groups" : [{"subscription_group_id" : "subscription_group_identifier", "subscription_state" : "subscribed"}]
    }
  ]
}

Migration des jetons de notification push

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

Migration automatique via le SDK

Une fois le SDK Braze intégré, les jetons de notification push de vos utilisateurs abonnés sont automatiquement migrés lors de leur prochaine ouverture de l’application. Jusqu’à ce moment-là, il n’est pas possible d’envoyer des notifications push à ces utilisateurs via Braze.

Vous pouvez également migrer vos jetons de notification 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 de notification push pour le Web, tenez compte des éléments suivants lors de la mise en œuvre du push pour le Web :

Migration manuelle via l’API

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

Migrez par programmation les jetons iOS (APNs) et Android (FCM) vers votre plateforme en utilisant l’endpoint users/track. Vous pouvez migrer à la fois les utilisateurs identifiés (utilisateurs avec un ID externe associé) et les utilisateurs anonymes (utilisateurs sans ID externe).

Spécifiez l’app_id de votre application lors de la migration des jetons de notification push pour associer le jeton approprié à l’application correspondante. Chaque application (iOS, Android, etc.) possède son propre app_id, disponible dans la section Identification de la page Clés API. Assurez-vous d’utiliser le bon app_id pour chaque plateforme.

Important

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

Si vous tentez de migrer des jetons de notification push Web par programmation, une erreur semblable à celle-ci peut s’afficher : Received '400: Invalid subscription auth' sending to 'https://fcm.googleapis.com/fcm/send

En guise d’alternative à la migration via l’API, nous vous recommandons d’intégrer le SDK et de permettre à votre base de jetons de 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"}
      ]
    }
  ]
}'

Importation de jetons de notification push Android

Important

La remarque 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 celles-ci s’affichent immédiatement dès lors que Braze dispose des jetons et certificats de notification push 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 de notification push. Pour notifier le récepteur du payload, ajoutez les paires clé-valeur nécessaires à la campagne push. Les valeurs de ces paires dépendent du partenaire 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 de la satisfaction client.