Importation CSV
Découvrez comment enregistrer et mettre à jour les attributs utilisateur, les événements personnalisés et les événements recommandés à l’aide de l’importation CSV.
À propos de l’importation CSV
Vous pouvez utiliser l’importation CSV pour enregistrer et mettre à jour les attributs utilisateur, les événements personnalisés et les événements recommandés suivants. Braze accepte ces données sous forme de fichiers CSV standard, dans la limite des tailles maximales indiquées dans le tableau suivant.
| Type | Définition | Exemple | Taille maximale du fichier |
|---|---|---|---|
| Attributs par défaut | Attributs utilisateur réservés reconnus par Braze. | first_name, email |
500 Mo |
| Attributs personnalisés | Attributs utilisateur propres à votre entreprise. | last_destination_searched |
500 Mo |
| Événements personnalisés | Événements propres à votre entreprise qui représentent des actions des utilisateurs. | trip_booked |
50 Mo |
| Événements recommandés | Événements personnalisés standardisés avec des schémas définis et un traitement spécialisé. | order_placed |
50 Mo |
Utilisation de l’importation CSV
Étape 1 : Accéder à l’importation CSV
Pour accéder à l’importation CSV, allez dans Audiences > Importer des utilisateurs. Vous y trouverez un tableau qui répertorie les détails des importations les plus récentes : date de téléversement, nom de la personne ayant effectué le téléversement, nom du fichier, disponibilité pour le ciblage, nombre d’enregistrements importés et statut de l’importation.
Pour commencer, sélectionnez Attributs, Événements personnalisés ou Événements recommandés dans le menu déroulant Importer des utilisateurs. Si vous utilisez l’outil de mappage des données ou si vous disposez déjà d’un fichier, vous pouvez téléverser votre fichier et passer directement à l’étape 5 : Mapper vos champs. Vous pouvez également télécharger le modèle correspondant pour vous aider à créer votre fichier CSV, mais cette étape est facultative si vous utilisez l’outil de mappage des données.

Les événements recommandés utilisant un schéma défini, consultez l’onglet Événements recommandés de l’étape 3 : Créer votre fichier CSV avant votre premier téléversement.
Étape 2 : Choisir un identifiant
Le fichier CSV que vous importez doit comporter un identifiant dédié. Choisissez l’un des types d’identifiants suivants pour votre importation :
Lorsque vous importez vos données clients, vous pouvez utiliser un external_id comme identifiant unique de chaque client. Lorsque vous fournissez un external_id dans votre importation, Braze met à jour tout utilisateur existant ayant le même external_id, ou crée un nouvel utilisateur identifié avec cet external_id s’il n’en trouve aucun.
- Télécharger : Modèle d’importation CSV d’attributs : ID externe
- Télécharger : Modèle d’importation CSV d’événements : ID externe

Si vous téléversez à la fois des utilisateurs avec un external_id et des utilisateurs sans, vous devez créer un fichier CSV pour chaque importation. Un même fichier CSV ne peut pas contenir à la fois des external_id et des alias d’utilisateur.
Pour cibler des utilisateurs qui n’ont pas d’external_id, vous pouvez importer une liste d’utilisateurs avec des alias d’utilisateur. Un alias sert d’identifiant unique alternatif et peut s’avérer utile si vous souhaitez cibler des utilisateurs anonymes qui ne se sont pas inscrits ou n’ont pas créé de compte dans votre application.
Si vous téléversez ou mettez à jour des profils utilisateur disposant uniquement d’un alias, votre fichier CSV doit contenir les deux colonnes suivantes :
user_alias_name: un identifiant utilisateur unique, alternative à l’external_iduser_alias_label: une étiquette commune permettant de regrouper les alias d’utilisateur
user_alias_name |
user_alias_label |
last_name |
email |
sample_attribute |
|---|---|---|---|---|
| 182736485 | my_alt_identifier | Smith | [email protected] | TRUE |
| 182736486 | my_alt_identifier | Nguyen | [email protected] | FALSE |
Lorsque vous fournissez à la fois un user_alias_name et un user_alias_label dans votre importation, Braze met à jour tout utilisateur existant ayant les mêmes user_alias_name et user_alias_label. Si aucun utilisateur n’est trouvé, Braze crée un nouvel utilisateur identifié avec ce user_alias_name.

Vous ne pouvez pas utiliser une importation CSV pour mettre à jour un utilisateur existant avec un user_alias_name s’il possède déjà un external_id. Cela crée plutôt un nouveau profil utilisateur avec le user_alias_name associé. Pour associer un utilisateur disposant uniquement d’un alias à un external_id, utilisez l’endpoint d’identification des utilisateurs.
Télécharger : Modèle d’importation CSV d’attributs : alias d’utilisateur
Pour mettre à jour des profils utilisateur existants dans Braze à l’aide d’une valeur d’ID Braze interne plutôt qu’avec un external_id ou des valeurs user_alias_name et user_alias_label, indiquez braze_id comme en-tête de colonne.
Cela peut être utile si vous avez exporté des données utilisateur depuis Braze via l’option d’exportation CSV de la segmentation et que vous souhaitez ajouter un nouvel attribut personnalisé à ces utilisateurs existants.

Vous ne pouvez pas utiliser une importation CSV pour créer un nouvel utilisateur à l’aide de braze_id. Cette méthode permet uniquement de mettre à jour des utilisateurs déjà présents dans la plateforme Braze.

La valeur braze_id peut apparaître sous le libellé Appboy ID dans les exportations CSV depuis le tableau de bord de Braze. Cet ID est identique au braze_id d’un utilisateur : vous pouvez donc renommer cette colonne en braze_id lorsque vous réimportez le fichier CSV.
Vous pouvez omettre l’ID externe ou l’alias d’utilisateur et utiliser une adresse e-mail ou un numéro de téléphone pour importer des utilisateurs. Avant d’importer un fichier CSV contenant des adresses e-mail ou des numéros de téléphone, vérifiez les points suivants :
- Assurez-vous que votre fichier CSV ne contient aucun ID externe ni alias d’utilisateur pour ces profils. Si c’est le cas, Braze utilisera en priorité l’ID externe ou l’alias d’utilisateur plutôt que l’adresse e-mail pour identifier les profils.
- Vérifiez que votre fichier CSV est correctement formaté.

Si votre fichier CSV contient à la fois des adresses e-mail et des numéros de téléphone, l’adresse e-mail est prioritaire sur le numéro de téléphone pour la recherche des profils.
Si un profil existant possède cette adresse e-mail ou ce numéro de téléphone, ce profil est mis à jour et Braze ne crée pas de nouveau profil. Si plusieurs profils partagent la même adresse e-mail, Braze applique la même logique que l’endpoint /users/track : le profil mis à jour le plus récemment sera mis à jour.
Si aucun profil ne possède cette adresse e-mail ou ce numéro de téléphone, Braze crée un nouveau profil avec cet identifiant. Vous pouvez utiliser l’endpoint /users/identify pour identifier ce profil ultérieurement. Pour supprimer un profil utilisateur, vous pouvez également utiliser l’endpoint /users/delete.
Étape 3 : Créer votre fichier CSV
Vous pouvez téléverser l’un des types de données suivants sous la forme d’un fichier CSV unique. Pour téléverser plusieurs types de données, téléversez plusieurs fichiers CSV.
- Attributs utilisateur : il s’agit des attributs utilisateur par défaut et personnalisés. Les attributs utilisateur par défaut sont des clés réservées dans Braze (comme
first_nameouemail), tandis que les attributs personnalisés sont des attributs utilisateur propres à votre entreprise (commelast_destination_searched). - Événements personnalisés : ils sont propres à votre entreprise et reflètent les actions effectuées par un utilisateur, comme
trip_bookedpour une application de réservation de voyages. - Événements recommandés : il s’agit d’événements personnalisés dotés de schémas définis et d’un traitement spécialisé, comme le calcul automatique de champs ou la gestion du panier, dont ne bénéficient pas les événements personnalisés génériques. Ils comprennent
order_placed,product_viewedetcart_updated.
Lorsque vous êtes prêt à créer votre fichier CSV, reportez-vous aux informations suivantes :
Identifiants requis
Bien que l’external_id ne soit pas obligatoire, votre fichier CSV doit inclure un identifiant utilisateur pouvant être mappé à l’un des identifiants suivants. Pour en savoir plus sur chacun d’eux, consultez Choisir un identifiant.
external_idbraze_iduser_alias_nameetuser_alias_labelemailphone
Attributs personnalisés
Les types de données suivants peuvent être utilisés comme attributs personnalisés pour l’importation CSV. Les en-têtes de colonne qui ne correspondent pas exactement à un attribut par défaut sont importés comme attributs personnalisés dans Braze, sauf s’ils sont modifiés lors de l’étape de mappage.
| Type de données | Description |
|---|---|
| Date/heure | Doit être enregistré au format ISO-8601. |
| Booléen | Accepte true ou false. |
| Nombre | Doit être un entier ou un float sans espaces ni virgules. Les floats doivent utiliser un point (.) comme séparateur décimal. |
| Chaîne de caractères | Peut contenir des virgules si la valeur est placée entre guillemets doubles (""). |
| Vide | Les valeurs vides n’écrasent pas les valeurs existantes du profil utilisateur, et vous n’avez pas besoin d’inclure tous les attributs utilisateur existants dans votre fichier CSV. |

Les tableaux, les jetons de notification push et les types de données d’événements personnalisés ne sont pas pris en charge dans l’importation d’utilisateurs, car les virgules de votre fichier CSV seraient interprétées comme des séparateurs de colonnes et provoqueraient des erreurs lors de l’analyse de votre fichier.
Pour téléverser ce type de valeurs, utilisez plutôt l’endpoint /users/track ou l’ingestion de données cloud.
Attributs par défaut

Lorsque vous importez des attributs par défaut, les en-têtes de colonne utilisés doivent correspondre exactement à l’orthographe et à la casse des attributs utilisateur par défaut. Sinon, Braze les détecte comme des attributs personnalisés.

Pour consulter la liste complète des attributs standard reconnus par Braze (via le SDK, l’API, l’importation CSV et l’ingestion de données cloud), consultez Attributs standard. Le tableau suivant ne couvre que les attributs pouvant être définis par importation CSV.
Les attributs par défaut suivants sont disponibles pour l’importation d’utilisateurs.
| Champ du profil utilisateur | Type de données | Description | Obligatoire ? |
|---|---|---|---|
external_id |
Chaîne de caractères | Un identifiant utilisateur unique pour votre client. | Sous condition. Voir Identifiants requis. |
user_alias_name |
Chaîne de caractères | Un identifiant utilisateur unique pour les utilisateurs anonymes, alternative à l’external_id. Doit être utilisé avec user_alias_label. |
Sous condition. Voir Identifiants requis. |
user_alias_label |
Chaîne de caractères | Une étiquette commune permettant de regrouper les alias d’utilisateur. Doit être utilisée avec user_alias_name. |
Sous condition. Voir Identifiants requis. |
first_name |
Chaîne de caractères | Le prénom de vos utilisateurs, tel qu’ils l’ont indiqué (par exemple, Jane). |
Non |
last_name |
Chaîne de caractères | Le nom de famille de vos utilisateurs, tel qu’ils l’ont indiqué (par exemple, Doe). |
Non |
email |
Chaîne de caractères | L’adresse e-mail de vos utilisateurs, telle qu’ils l’ont indiquée (par exemple, [email protected]). |
Non |
country |
Chaîne de caractères | Les codes pays doivent être transmis à Braze selon la norme ISO-3166-1 alpha-2 (par exemple, GB). |
Non |
dob |
Chaîne de caractères | Doit être transmis au format « YYYY-MM-DD » (par exemple, 1980-12-21). Cela importe la date de naissance de votre utilisateur et vous permet de cibler les utilisateurs dont l’anniversaire est « aujourd’hui ». |
Non |
gender |
Chaîne de caractères | « M », « F », « O » (autre), « N » (non applicable), « P » (préfère ne pas le dire) ou nil (inconnu). | Non |
home_city |
Chaîne de caractères | La ville de résidence de vos utilisateurs, telle qu’ils l’ont indiquée (par exemple, London). |
Non |
language |
Chaîne de caractères | La langue doit être transmise à Braze selon la norme ISO-639-1 (par exemple, en). Consultez notre liste des langues acceptées. |
Non |
phone |
Chaîne de caractères | Un numéro de téléphone indiqué par vos utilisateurs, au format E.164 (par exemple, +442071838750). Consultez Numéros de téléphone des utilisateurs pour obtenir des conseils de formatage. |
Non |
email_open_tracking_disabled |
Booléen | Accepte true ou false. Définissez sur true pour empêcher l’ajout du pixel de suivi des ouvertures à tous les futurs e-mails envoyés à cet utilisateur. | Non |
email_click_tracking_disabled |
Booléen | Accepte true ou false. Définissez sur true pour désactiver le suivi des clics sur tous les liens des futurs e-mails envoyés à cet utilisateur. | Non |
email_subscribe |
Chaîne de caractères | Les valeurs disponibles sont opted_in (inscription explicite pour recevoir des e-mails), unsubscribed (désinscription explicite des e-mails) et subscribed (ni inscrit ni désinscrit explicitement). |
Non |
push_subscribe |
Chaîne de caractères | Les valeurs disponibles sont opted_in (inscription explicite pour recevoir des notifications push), unsubscribed (désinscription explicite des notifications push) et subscribed (ni inscrit ni désinscrit explicitement). |
Non |
time_zone |
Chaîne de caractères | Le fuseau horaire doit être transmis à Braze dans le même format que la base de données des fuseaux horaires de l’IANA (par exemple, America/New_York ou Eastern Time (US & Canada)). |
Non |
date_of_first_session date_of_last_session |
Chaîne de caractères | Peut être transmis dans l’un des formats ISO 8601 suivants : “YYYY-MM-DD” “YYYY-MM-DDTHH:MM:SS+00:00” “YYYY-MM-DDTHH:MM:SSZ” “YYYY-MM-DDTHH:MM:SS” (par exemple, 2019-11-20T18:38:57) | Non |
subscription_group_id |
Chaîne de caractères | L’id de votre groupe d’abonnement. Cet identifiant se trouve sur la page du groupe d’abonnement de votre tableau de bord. |
Non |
subscription_state |
Chaîne de caractères | Le statut d’abonnement pour le groupe d’abonnement spécifié par subscription_group_id. Les valeurs autorisées sont unsubscribed (hors du groupe d’abonnement) ou subscribed (dans le groupe d’abonnement). |
Non, mais fortement recommandé si subscription_group_id est utilisé |
Mise à jour du statut du groupe d’abonnement (facultatif)
Vous pouvez également ajouter des utilisateurs à des groupes d’abonnement e-mail ou SMS via l’importation d’utilisateurs. C’est particulièrement utile pour les SMS, car un utilisateur doit être inscrit à un groupe d’abonnement SMS pour pouvoir recevoir des messages via le canal SMS. Pour plus d’informations, consultez Groupes d’abonnement SMS.
Si vous mettez à jour des statuts de groupe d’abonnement, votre fichier CSV doit contenir les deux colonnes suivantes :
subscription_group_id: l’iddu groupe d’abonnement.subscription_state: les valeurs disponibles sontunsubscribed(hors du groupe d’abonnement) ousubscribed(dans le groupe d’abonnement).
| external_id | first_name | subscription_group_id | subscription_state |
|---|---|---|---|
| A8i3mkd99 | Colby | 6ff593d7-cf69-448b-aca9-abf7d7b8c273 | subscribed |
| k2LNhj8Ks | Tom | aea02307-a91e-4bc0-abad-1c0bee817dfa | subscribed |

Un seul subscription_group_id peut être défini par ligne dans l’importation d’utilisateurs. Des lignes différentes peuvent avoir des valeurs subscription_group_id différentes. Toutefois, si vous devez inscrire les mêmes utilisateurs à plusieurs groupes d’abonnement, vous devrez effectuer plusieurs importations.
Identifiants requis
Bien que l’external_id ne soit pas obligatoire, votre fichier CSV doit inclure un identifiant utilisateur correspondant à l’un des identifiants suivants. Pour en savoir plus sur chacun d’eux, consultez Choisir un identifiant.
external_idbraze_iduser_alias_nameetuser_alias_labelemailphone
Champs des événements personnalisés
En plus des champs standard répertoriés dans le tableau suivant, votre fichier CSV peut également contenir des en-têtes de colonne supplémentaires pour les propriétés d’événement. Ces propriétés doivent avoir un en-tête de colonne <property name>. Braze détecte les propriétés pertinentes pour chaque événement selon qu’une valeur figure ou non dans la cellule CSV correspondante.
Par exemple, l’événement personnalisé trip_booked peut avoir la propriété destination. Vous pouvez l’importer à l’aide de l’en-tête de colonne destination, avec une valeur dans la cellule CSV correspondante. Plusieurs événements peuvent ainsi avoir une propriété nommée destination sans nécessiter de colonnes distinctes.

Bien que l’ancien format des en-têtes de propriétés d’événement soit toujours pris en charge, les en-têtes de propriétés n’ont pas besoin de suivre le format <event_name>.properties.<property name>.
| Champ du profil utilisateur | Type de données | Informations | Obligatoire ? |
|---|---|---|---|
external_id |
Chaîne de caractères | Un identifiant utilisateur unique pour votre utilisateur. | Sous condition. Voir Identifiants requis. |
braze_id |
Chaîne de caractères | Un identifiant attribué par Braze à votre utilisateur. | Sous condition. Voir Identifiants requis. |
user_alias_name |
Chaîne de caractères | Un identifiant utilisateur unique pour les utilisateurs anonymes, alternative à l’external_id. Doit être utilisé avec user_alias_label. |
Sous condition. Voir Identifiants requis. |
user_alias_label |
Chaîne de caractères | Une étiquette commune permettant de regrouper les alias d’utilisateur. Doit être utilisée avec user_alias_name. |
Sous condition. Voir Identifiants requis. |
email |
Chaîne de caractères | L’adresse e-mail de vos utilisateurs, telle qu’ils l’ont indiquée (par exemple, [email protected]). |
Non, et ne peut être utilisé qu’en l’absence d’autres identifiants. Voir la remarque suivante. |
phone |
Chaîne de caractères | Un numéro de téléphone indiqué par vos utilisateurs, au format E.164 (par exemple, +442071838750). Consultez Numéros de téléphone des utilisateurs pour obtenir des conseils de formatage. |
Non, et ne peut être utilisé qu’en l’absence d’autres identifiants. Voir la remarque suivante. |
name |
Chaîne de caractères | Un événement personnalisé de vos utilisateurs. | Oui |
time |
Chaîne de caractères | L’heure de l’événement. Peut être transmise dans l’un des formats ISO-8601 suivants : “YYYY-MM-DD” “YYYY-MM-DDTHH:MM:SS+00:00” “YYYY-MM-DDTHH:MM:SSZ” “YYYY-MM-DDTHH:MM:SS” (par exemple, 2019-11-20T18:38:57) | Oui |
<property name> |
Multiple | Une propriété d’événement que vous pouvez utiliser pour plusieurs types d’événements, par exemple destination. Cette propriété est associée à un événement lorsque la cellule CSV correspondante contient une valeur non nulle. |
Non |
<event name>.properties.<property name> |
Multiple | Une propriété d’événement associée à un événement personnalisé, par exemple trip_booked.properties.destination |
Non |
Comprendre le formatage des événements personnalisés
Formatez correctement votre fichier CSV d’événements personnalisés avec un en-tête <property_name> et une valeur non nulle dans la bonne cellule, ou utilisez l’ancien format en notation pointée. Braze peut ainsi mapper chaque propriété au bon événement. Si le format est incorrect, des propriétés peuvent être ignorées ou l’importation peut échouer, en particulier lorsque plusieurs types d’événements figurent dans un même fichier.
Un événement par ligne
Chaque ligne de votre fichier CSV représente un seul événement personnalisé pour un seul utilisateur. Si un utilisateur a plusieurs événements, vous devez inclure une ligne distincte pour chaque événement, même s’ils partagent le même identifiant utilisateur.

Lorsqu’une ligne contient des données pour un événement spécifique, ne renseignez que les colonnes des propriétés de cet événement. Laissez vides les colonnes des autres événements.
Exemple de structure CSV
Le tableau suivant illustre le formatage correct pour importer des événements personnalisés avec des propriétés. Cet exemple présente deux utilisateurs ayant chacun effectué un événement différent : l’un a loué un film, l’autre a acheté une sitcom.
| external_id | name | time | movie_name | sitcom_name | genre |
|---|---|---|---|---|---|
| 123 | rented_movie | 2024-06-10T12:00:00Z | Ghostbusters | Action | |
| 456 | bought_sitcom | 2024-06-12T12:00:00Z | Scrubs | Comedy |
Dans cet exemple :
- L’utilisateur
123a déclenché l’événementrented_movieavec les propriétésmovie_name(Ghostbusters) etgenre(Action) - L’utilisateur
456a déclenché l’événementbought_sitcomavec les propriétéssitcom_name(Scrubs) etgenre(Comedy) - Chaque événement ne renseigne que ses propres colonnes de propriétés et laisse vides les colonnes de propriétés des autres événements
Identifiants requis
Bien que l’external_id ne soit pas obligatoire, votre fichier CSV doit inclure l’un des identifiants suivants comme en-tête. Pour en savoir plus sur chacun d’eux, consultez Choisir un identifiant.
external_idbraze_iduser_alias_nameetuser_alias_labelemailphone
Champs des événements recommandés
En plus des champs suivants, votre fichier CSV doit également contenir des en-têtes de colonne supplémentaires pour les propriétés obligatoires de l’événement recommandé que vous souhaitez importer. Ces propriétés doivent avoir un en-tête de colonne <property_name> et peuvent être mappées à la propriété correspondante de l’événement recommandé.
Par exemple, l’événement recommandé order_placed doit notamment avoir les propriétés order_id et total_value. Vous pouvez les importer avec les en-têtes de colonne order_id et total_value, ou avec des en-têtes basés sur votre modèle de données que vous mappez à la bonne propriété. Pour obtenir la liste complète des propriétés des événements recommandés, consultez Schémas des événements recommandés.
| Champ du profil utilisateur | Type de données | Informations | Obligatoire ? |
|---|---|---|---|
external_id |
Chaîne de caractères | Un identifiant utilisateur unique pour votre utilisateur. | Sous condition. Voir Identifiants requis. |
braze_id |
Chaîne de caractères | Un identifiant attribué par Braze à votre utilisateur. | Sous condition. Voir Identifiants requis. |
user_alias_name |
Chaîne de caractères | Un identifiant utilisateur unique pour les utilisateurs anonymes, alternative à l’external_id. Doit être utilisé avec user_alias_label. |
Sous condition. Voir Identifiants requis. |
user_alias_label |
Chaîne de caractères | Une étiquette commune permettant de regrouper les alias d’utilisateur. Doit être utilisée avec user_alias_name. |
Sous condition. Voir Identifiants requis. |
email |
Chaîne de caractères | L’adresse e-mail de vos utilisateurs, telle qu’ils l’ont indiquée (par exemple, [email protected]). |
Non, et ne peut être utilisé qu’en l’absence d’autres identifiants. Voir la remarque suivante. |
phone |
Chaîne de caractères | Un numéro de téléphone indiqué par vos utilisateurs, au format E.164 (par exemple, +442071838750). Consultez Numéros de téléphone des utilisateurs pour obtenir des conseils de formatage. |
Non, et ne peut être utilisé qu’en l’absence d’autres identifiants. Voir la remarque suivante. |
name |
Chaîne de caractères | Un événement personnalisé de vos utilisateurs. | Oui |
time |
Chaîne de caractères | L’heure de l’événement. Peut être transmise dans l’un des formats ISO-8601 suivants : “YYYY-MM-DD” “YYYY-MM-DDTHH:MM:SS+00:00” “YYYY-MM-DDTHH:MM:SSZ” “YYYY-MM-DDTHH:MM:SS” (par exemple, 2019-11-20T18:38:57) | Oui |
<property_name> |
Multiple | Une propriété d’événement associée à un événement recommandé, par exemple order_id. |
Sous condition. Voir Schémas des événements recommandés. |
Exigences de format pour les événements recommandés
Lorsque vous importez des événements recommandés via un fichier CSV, vous devez formater votre fichier selon les exigences suivantes pour que l’importation des données réussisse. Pour limiter les erreurs de mappage, n’incluez qu’un seul type d’événement par fichier.
Comprendre le formatage des événements recommandés
Il est important de formater votre fichier CSV d’événements recommandés avec des en-têtes appropriés afin que chaque propriété identifiée soit mappée à la bonne propriété d’événement. Si le format est incorrect, des événements peuvent être ignorés ou l’importation peut échouer, en particulier lorsque plusieurs types d’événements figurent dans un même fichier.
Regroupement des événements recommandés pour les propriétés imbriquées
Les événements recommandés ont un schéma défini. Par exemple, order_placed possède une propriété obligatoire products, qui est un tableau d’objets, et chaque objet imbriqué possède ses propres propriétés imbriquées obligatoires.
Le fichier CSV des événements recommandés permet de regrouper plusieurs lignes ayant le même identifiant, le même nom d’événement et la même heure, à condition que ces lignes ne soient pas séparées dans le fichier. Vous pouvez ainsi utiliser des lignes consécutives pour renseigner les valeurs des propriétés imbriquées. Lors du formatage de votre fichier, ne renseignez dans les lignes supplémentaires que l’identifiant, le nom de l’événement, l’heure et les propriétés imbriquées pertinentes. Il n’est pas nécessaire de répéter les valeurs des propriétés de premier niveau sur chaque ligne.
Métadonnées et propriétés facultatives
Bien que les événements recommandés aient un schéma défini (voir Schémas des événements recommandés), vous pouvez mapper et importer des propriétés facultatives, comme image_url pour la propriété de tableau products. Vous pouvez également transmettre des propriétés supplémentaires dans la propriété metadata de premier niveau, dans la propriété imbriquée metadata au niveau de products, ou dans le tableau de propriétés discounts. Après avoir mappé toutes les propriétés obligatoires, cliquez sur Charger les propriétés facultatives pour charger et mapper des propriétés supplémentaires.
Exemple de structure CSV
L’exemple suivant illustre le formatage correct pour importer des événements recommandés avec des propriétés obligatoires et des propriétés imbriquées. Il présente trois utilisateurs ayant chacun passé une commande comportant deux produits distincts.

Dans cet exemple :
- Les commandes sont identifiées et regroupées par identifiant, nom d’événement et heure identiques, toutes les lignes concernées se suivant.
- Les utilisateurs
user_101,user_102etuser_103ont chacun déclenché l’événementorder_placedavec les propriétés obligatoires et les propriétés imbriquées. - Les commandes des utilisateurs
user_101etuser_102incluent des métadonnées ajoutées au tableau de propriétésdiscounts.

Lorsqu’une ligne contient des données pour un événement spécifique, ne renseignez que les colonnes des propriétés de cet événement. Laissez vides les colonnes des autres événements.
Étape 4 : Téléverser votre fichier
Pour téléverser votre fichier, sélectionnez Attributs, Événements personnalisés ou Événements recommandés dans le menu déroulant Importer des utilisateurs, cliquez sur Parcourir les fichiers, puis téléversez votre fichier CSV. Braze affiche un aperçu des premières lignes et un récapitulatif des champs détectés.
Pour les fichiers volumineux (jusqu’à 500 Mo pour les attributs par défaut et les attributs personnalisés, ou 50 Mo pour les événements personnalisés), le tableau de bord peut sembler temporairement ne plus répondre pendant le téléversement du fichier et le calcul de l’importation par Braze. Ces téléversements et calculs peuvent prendre plus de temps que pour des fichiers plus petits. Laissez cette étape se terminer. Pour en savoir plus sur les limites de fichiers et les délais, consultez Construire votre fichier CSV.

L’aperçu du fichier n’affiche que les premières lignes de votre fichier. Pour vérifier chaque ligne avant l’importation, utilisez la validation du fichier.

Les importations d’utilisateurs CSV peuvent être téléchargées depuis le tableau de bord pendant 14 jours après leur téléversement. Passé ce délai, le fichier est supprimé du stockage et n’est plus accessible.
Étape 5 : Mapper vos champs
Après l’aperçu, vous pouvez mapper les en-têtes de votre fichier CSV aux attributs, événements ou propriétés d’événement de Braze. Braze mappe automatiquement les champs de votre fichier CSV aux attributs, événements ou propriétés d’événement portant un nom identique, et crée de nouveaux champs si nécessaire. Vous pouvez également ajuster manuellement les suggestions ou sélectionner d’autres attributs, événements ou propriétés.
Pour les propriétés d’événement, Braze détecte les propriétés et les associe aux événements pertinents selon qu’une cellule CSV contient une valeur non nulle, ou à partir d’en-têtes utilisant l’ancien format en notation pointée (par exemple <event name>.properties.<property name>).

Statuts de mappage
La colonne du statut de mappage indique l’action effectuée lors de l’importation de votre fichier CSV. Elle peut prendre l’une des valeurs suivantes.
| Statut de mappage | Signification |
|---|---|
| Mappé | Le champ est mappé à un attribut, un événement ou un identifiant existant. |
| Nouvel attribut, Nouvel événement ou Nouvelle propriété d’événement | Braze crée un nouvel attribut ou événement lors de l’importation. Vous pouvez le modifier en sélectionnant le bouton Modifier le nouvel attribut, Modifier le nouvel événement ou Modifier la nouvelle propriété. |
| Incompatibilité du type de données | Le type de données détecté pour la colonne CSV ne correspond pas au type de données de l’attribut, de l’événement ou de l’identifiant existant. Braze tente de convertir le type de données lors de l’importation pour qu’il corresponde à l’attribut existant. Si ce n’est pas possible, Braze ignore la valeur. |
| Attribut sur liste de blocage ou Événement sur liste de blocage | Le champ CSV correspond au nom d’un attribut ou d’un événement placé sur liste de blocage. Sélectionnez un autre attribut ou événement auquel le mapper ; sinon, il ne sera pas importé. |
| Attribut en double | Votre fichier CSV contient plusieurs champs portant le même nom. Mappez les colonnes de même nom à des attributs différents ; sinon, seule la première colonne sera importée. |
| Clé d’événement réservée | Le nom de votre propriété d’événement correspond à une clé d’événement réservée dans Braze, comme time ou event_name. Saisissez un autre nom ou sélectionnez une autre propriété à mapper ; sinon, elle sera ignorée. |
Modifier les nouveaux attributs, événements et propriétés
Lorsqu’aucun attribut, événement ou propriété d’événement correspondant n’existe dans votre espace de travail, Braze tente d’en créer un nouveau lors de l’importation en utilisant le nom du champ CSV et le type de données détecté. Vous pouvez modifier ce nouveau champ avant l’importation en sélectionnant le bouton Modifier le nouvel attribut, Modifier le nouvel événement ou Modifier la nouvelle propriété à côté du statut de mappage.


Vous ne pouvez pas passer l’étape de mappage tant qu’aucun identifiant n’est mappé. Braze mappe automatiquement un identifiant lorsque c’est possible. Pour les événements personnalisés, vous devez également mapper les colonnes name et time. Pour plus d’informations, consultez la section Champs obligatoires.
Étape 6 : Choisir les préférences de ciblage
Après le mappage, vous pouvez choisir parmi les préférences de ciblage suivantes sur la page Paramètres d’importation. Si vous n’avez pas besoin de créer un nouveau filtre de ciblage ou un nouveau Segment à partir de votre importation, sélectionnez Ne pas rendre cette liste disponible comme filtre de ciblage.
| Option | Description |
|---|---|
| Filtre de ciblage | Pour convertir votre fichier CSV en option de reciblage lors de la création de Segments d’utilisateurs, choisissez votre fichier dans le menu déroulant Mis à jour/importé depuis un CSV, puis sélectionnez Créer un filtre de ciblage. |
| Nouveaux Segments | Pour créer également un nouveau Segment à partir de votre nouveau filtre de ciblage, sélectionnez Créer un filtre de ciblage et l’ajouter à un nouveau Segment. |

Étape 7 : Valider votre fichier (facultatif)
Avant de lancer votre importation, vous pouvez exécuter une validation du fichier pour vérifier chaque ligne et détecter les erreurs et avertissements. Pour valider votre fichier, sélectionnez Valider le fichier avant l’importation sur la page Paramètres d’importation, puis sélectionnez Suivant.
La validation peut prendre jusqu’à 2 minutes pour les fichiers de taille maximale autorisée. Pendant la validation, vous pouvez sélectionner Ignorer la validation pour la contourner et continuer immédiatement.
Résultats de la validation
Une fois la validation terminée, l’un des résultats suivants s’affiche.
| Résultat | Signification | Étape suivante |
|---|---|---|
| Validation terminée | Aucun problème détecté. | Sélectionnez Importer les données. |
| Problèmes détectés | Certaines lignes comportent des erreurs ou des avertissements. | Téléchargez le rapport d’erreurs pour les examiner, puis sélectionnez Importer quand même pour continuer ou Annuler pour corriger d’abord votre fichier. |
| Délai de validation dépassé | La validation a manqué de temps. Les lignes vérifiées ne présentaient aucun problème. | Sélectionnez Importer les données. Un rapport complet sera disponible dans quelques minutes. |
| Délai de validation dépassé avec des problèmes | La validation a manqué de temps et a détecté des erreurs dans certaines des lignes vérifiées. | Téléchargez le rapport partiel pour examiner les problèmes détectés, puis sélectionnez Importer quand même ou Annuler. |

Comprendre le rapport d’erreurs
Le rapport d’erreurs est un fichier CSV qui contient chaque ligne signalée, avec ses données d’origine et une description du problème.
| Type de problème | Description |
|---|---|
| Erreur | La ligne sera entièrement ignorée lors de l’importation. |
| Avertissement | La ligne sera importée, mais certaines valeurs seront ignorées. |
Après avoir examiné le rapport, vous pouvez corriger les problèmes dans votre fichier d’origine et le téléverser à nouveau, ou poursuivre l’importation en acceptant des résultats partiels.
Étape 8 : Lancer votre importation CSV
Lorsque vous êtes prêt, sélectionnez Lancer l’importation. Vous pouvez suivre la progression sur la page Importer des utilisateurs, qui s’actualise automatiquement toutes les 5 secondes. Le traitement peut prendre de quelques minutes à plusieurs heures selon la taille de votre fichier CSV. Pendant ce temps, le tableau de bord peut sembler ne plus répondre ou répondre lentement, mais l’importation se poursuit.

Vous pouvez importer plusieurs fichiers CSV en même temps. Les importations CSV s’exécutent simultanément : l’ordre des mises à jour n’est donc pas garanti. Si vous avez besoin que les importations CSV s’exécutent l’une après l’autre, attendez qu’une importation CSV soit terminée avant d’en téléverser une deuxième.
Statuts d’importation
Après avoir lancé votre importation, vous pouvez consulter son statut sur la page Importer des utilisateurs.
| Statut | Description |
|---|---|
| Terminé | Toutes les lignes ont été importées avec succès. |
| Succès partiel | Certaines lignes ont échoué. Sélectionnez le menu à trois points à côté de l’importation pour télécharger un rapport d’erreurs ou le fichier CSV téléversé d’origine. |
| En cours | L’importation est en cours d’exécution. |

Le rapport d’erreurs post-importation inclut les lignes ayant échoué pour des raisons que la validation ne couvre pas, par exemple lorsqu’un utilisateur n’existe pas dans Braze.

Les fichiers CSV téléversés précédemment peuvent être téléchargés depuis la page Importer des utilisateurs pendant 14 jours après la date de téléversement. Passé ce délai, le fichier est définitivement supprimé et n’est plus accessible.
Considérations sur les points de données
Chaque donnée client importée à partir d’un fichier CSV écrase la valeur existante dans les profils utilisateurs et enregistre un point de donnée, à l’exception des ID externes et des valeurs vides. Si vous avez des questions sur les subtilités des points de données de Braze, votre gestionnaire de compte Braze pourra y répondre.
| Considération | Détails |
|---|---|
| ID externes | L’importation d’un fichier CSV contenant uniquement external_id n’enregistre pas de points de données. Vous pouvez ainsi segmenter des utilisateurs Braze existants sans affecter vos limites de données. Cependant, l’ajout de champs tels que email ou phone écrase les données utilisateur existantes et enregistre bien des points de données. Les importations CSV utilisées uniquement à des fins de segmentation, comme celles qui ne contiennent que external_id, braze_id ou user_alias_name, n’enregistrent pas de points de données. |
| Valeurs vides | Les valeurs vides de votre fichier CSV n’écrasent pas les données existantes du profil utilisateur. Vous n’avez pas besoin d’inclure tous les attributs utilisateur ou événements personnalisés lors de l’importation. |
| Statuts d’abonnement | La mise à jour de email_subscribe, push_subscribe, subscription_group_id ou subscription_state n’est pas comptabilisée dans l’utilisation des points de données. |

Définir language ou country pour un utilisateur via l’importation CSV ou l’API empêche Braze de capturer automatiquement ces informations par le biais du SDK.
Résolution des problèmes
Si vous avez utilisé la validation de fichier, commencez par consulter le rapport d’erreurs : il indique le problème précis de chaque ligne signalée ainsi que la façon de le corriger. Pour les lignes qui ont échoué pendant l’importation plutôt que pendant la validation, téléchargez le rapport d’erreurs en survolant la ligne et en sélectionnant le bouton sur la page Importer des utilisateurs.
Pour résoudre les problèmes d’importation CSV, consultez les problèmes courants décrits dans les sections suivantes.

En cas d’échec d’une importation, examinez les résultats de la validation de fichier, puis passez en revue les problèmes de formatage de fichier et les problèmes de structure des données. Vérifiez que vos colonnes d’identifiant correspondent à la section Choisir un identifiant avant de téléverser à nouveau le fichier. Si une importation reste bloquée sur « Calculating », ne la téléversez pas à nouveau ; consultez Importation CSV bloquée sur « Calculating ». Si une importation n’est pas disponible comme filtre de segmentation, consultez L’importation CSV n’est pas disponible comme filtre de segmentation.
Importation CSV bloquée sur « Calculating »
Dans Importer des utilisateurs, Calculating signifie que Braze prépare encore le fichier pour son traitement. Pendant cette étape, le nombre de lignes peut s’afficher sous la forme 0 / Calculating jusqu’à la fin de la préparation.
Si votre importation semble bloquée sur « Calculating » :
- Laissez l’importation se poursuivre. N’annulez pas et ne téléversez pas à nouveau le fichier, sauf sur recommandation du support de Braze.
- Vérifiez que votre fichier respecte les limites prises en charge, décrites dans Créer votre CSV.
- Consultez l’étape 4 : Téléverser votre fichier et l’étape 8 : Lancer votre importation CSV pour connaître le comportement attendu du tableau de bord et les délais de traitement.
- Contactez le support de Braze si
Calculatingdure beaucoup plus longtemps que prévu pour la taille de votre fichier après avoir effectué ces vérifications.
Utiliser l’e-mail comme external_id
Braze ne recommande pas d’utiliser une adresse e-mail comme external_id. Si vous utilisez l’e-mail comme external_id, incluez à la fois les colonnes external_id et email dans votre CSV afin que les utilisateurs restent ciblables sur le canal e-mail. Utilisez une virgule (,) comme délimiteur de colonnes, et non deux-points (:).
Guillemets dans les valeurs external_id
Si une cellule external_id contient un guillemet double, échappez-le en doublant le caractère (""), comme décrit dans Guillemets doubles non échappés ou non appariés. L’importation CSV n’utilise pas l’échappement par barre oblique inverse.
L’importation CSV n’est pas disponible comme filtre de segmentation
Vous ne pouvez utiliser une importation CSV comme filtre de segmentation que si vous avez activé une préférence de ciblage lors du téléversement.
Pour vérifier si la disponibilité pour le ciblage est activée pour une importation existante :
- Sur la page Importer des utilisateurs, trouvez votre importation CSV.
- Vérifiez si Accéder au Segment apparaît pour cette importation.
- Si Accéder au Segment apparaît, votre CSV est disponible dans le filtre de segmentation
Updated/Imported from CSV. - Si Accéder au Segment n’apparaît pas, la disponibilité pour le ciblage n’a pas été activée pour cette importation.
Vous ne pouvez pas activer la disponibilité pour le ciblage une fois le téléversement d’un CSV terminé. Pour utiliser ce CSV comme filtre de segmentation, téléversez à nouveau le fichier et, à l’étape 6 : Choisir les préférences de ciblage, sélectionnez Créer un filtre de ciblage ou Créer un filtre de ciblage et l’ajouter à un nouveau Segment.
Si votre objectif est de créer un Segment sans mettre à jour les données de profil, téléversez un CSV contenant uniquement des colonnes d’identifiant (par exemple, external_id ou des colonnes d’identifiant d’alias), puis sélectionnez Créer un filtre de ciblage et l’ajouter à un nouveau Segment.
Problèmes de formatage de fichier
Ligne mal formée
Si votre téléversement s’est terminé avec des erreurs, votre fichier CSV contient peut-être une ligne mal formée.
Pour importer correctement les données, le fichier doit comporter une ligne d’en-tête. Chaque ligne doit contenir le même nombre de cellules que la ligne d’en-tête. Les lignes contenant plus ou moins de valeurs que la ligne d’en-tête seront exclues de l’importation. Une virgule dans une valeur sera interprétée comme un séparateur et peut provoquer cette erreur.
Par ailleurs, toutes les données doivent être encodées en UTF-8. Si le fichier est enregistré avec un ancien encodage (par exemple, certains paramètres par défaut d’Excel), les caractères spéciaux et les URL des cellules peuvent être altérés et apparaître sous forme de points d’interrogation (?) dans Braze ou dans les messages envoyés.
Si votre fichier CSV contient des lignes vides et que le nombre de lignes importées est inférieur au nombre total de lignes du fichier, cela ne signale pas forcément un problème d’importation, puisque les lignes vides n’ont pas besoin d’être importées. Vérifiez le nombre de lignes correctement importées et assurez-vous qu’il correspond au nombre d’utilisateurs que vous souhaitez importer.
Ligne manquante
Plusieurs raisons peuvent expliquer pourquoi le nombre d’utilisateurs importés ne correspond pas au nombre total de lignes de votre fichier CSV :
| Problème | Résolution |
|---|---|
| ID externes, alias d’utilisateur, ID Braze, adresses e-mail ou numéros de téléphone en double | Des colonnes d’ID externe en double peuvent entraîner des lignes mal formées ou non importées, même si les lignes sont correctement formatées. Dans certains cas, aucune erreur spécifique n’est signalée. Recherchez les doublons et supprimez-les avant de téléverser à nouveau le fichier. |
| Caractères accentués | Votre CSV peut contenir des noms ou des attributs comportant des accents. Assurez-vous que le fichier est encodé en UTF-8 pour éviter les problèmes d’importation. |
| L’ID Braze appartient à un utilisateur orphelin | Si un utilisateur a été fusionné avec un autre et que Braze ne peut pas associer l’ID Braze au profil restant, la ligne ne sera pas importée. |
| Ligne vide | Les lignes vides dans le CSV peuvent provoquer des erreurs de données mal formées. Vérifiez à l’aide d’un éditeur de texte brut, et non d’Excel ou de Sheets. |
Guillemets doubles (") non échappés ou non appariés |
Les guillemets doubles encadrent les valeurs de chaîne de caractères qui contiennent des virgules. Si une valeur contient elle-même un guillemet double, échappez-le en le doublant (""). Des guillemets doubles non échappés ou non appariés entraînent une ligne mal formée. |
| Sauts de ligne incohérents | Des sauts de ligne mixtes (par exemple, \n et \r\n) peuvent faire en sorte que la première ligne de données soit traitée comme faisant partie de l’en-tête. Utilisez un éditeur hexadécimal ou un éditeur de texte avancé pour les inspecter et les corriger. |
| Fichier mal encodé | Même si les accents sont autorisés, le fichier doit être encodé en UTF-8. D’autres encodages peuvent fonctionner partiellement, mais ne sont pas entièrement pris en charge. |
Valeurs entre guillemets
Les valeurs encadrées par des guillemets simples ('') ou doubles ("") seront lues comme des chaînes de caractères lors de l’importation.
Dates mal formatées
Les dates qui ne sont pas au format ISO-8601 ne seront pas lues comme des datetimes lors de l’importation.
Problèmes de structure des données
Adresses e-mail non valides
Si votre téléversement s’est terminé avec des erreurs, il se peut qu’une ou plusieurs adresses e-mail chiffrées ne soient pas valides. Vérifiez que toutes les adresses e-mail sont correctement chiffrées avant de les importer dans Braze.
- Lors de la mise à jour ou de l’importation d’adresses e-mail dans Braze, utilisez la valeur d’e-mail hachée partout où un e-mail est inclus. Ces valeurs d’e-mail hachées sont fournies par votre équipe interne.
- Lors de la création d’un nouvel utilisateur, vous devez ajouter
email_encryptedavec la valeur chiffrée de l’e-mail de l’utilisateur. Sinon, Braze ne créera pas l’utilisateur. De même, si vous ajoutez une adresse e-mail à un utilisateur existant qui n’en possède pas, vous devez ajouteremail_encrypted. Sinon, Braze ne mettra pas l’utilisateur à jour.
Données importées en tant qu’attribut personnalisé
Si une donnée utilisateur par défaut (comme email ou first_name) est importée en tant qu’attribut personnalisé, vérifiez la casse et les espaces dans votre fichier CSV. Par exemple, First_name est importé en tant qu’attribut personnalisé, alors que first_name est correctement importé dans le champ « prénom » du profil d’un utilisateur.
Modifier le type de données d’un attribut personnalisé
Si vous devez modifier le type de données d’un attribut personnalisé existant (par exemple, de chaîne de caractères à booléen), mettez à jour le type de données sur la page Attributs personnalisés du tableau de bord avant d’importer votre CSV. Si le type de données de votre CSV ne correspond pas au type de données actuellement défini pour l’attribut, l’importation échoue avec une erreur.
Types de données multiples
Braze s’attend à ce que toutes les valeurs d’une colonne soient du même type de données. Les valeurs qui ne correspondent pas au type de données de leur attribut entraînent des erreurs de segmentation.
En outre, commencer un attribut numérique par un zéro posera problème, car les nombres commençant par des zéros sont considérés comme des chaînes de caractères. Lorsque Braze convertit cette chaîne, elle peut être traitée comme une valeur octale (qui utilise les chiffres de zéro à sept), ce qui signifie qu’elle est convertie en sa valeur décimale correspondante. Par exemple, si la valeur dans le fichier CSV est 0130, le profil Braze affiche 88. Pour éviter ce problème, utilisez des attributs de type chaîne de caractères. Notez toutefois que ce type de données n’est pas disponible dans la comparaison numérique de la segmentation.
Types d’attributs par défaut
Certains attributs par défaut n’acceptent que certaines valeurs comme valides pour les mises à jour des utilisateurs. Pour en savoir plus, consultez Créer votre CSV.
Les espaces de fin et les différences de casse peuvent entraîner l’interprétation d’une valeur comme non valide. Par exemple, dans le fichier CSV suivant, seul l’utilisateur de la première ligne (brazetest1) voit ses statuts d’e-mail et de notification push mis à jour avec succès, car les valeurs acceptées sont unsubscribed, subscribed et opted_in.
external_id,email,email_subscribe,push_subscribe
brazetest1,[email protected],unsubscribed,unsubscribed
brazetest2,[email protected],Unsubscribed,Unsubscribed
Le bouton « Sélectionner un fichier CSV » ne fonctionne pas
Plusieurs raisons peuvent expliquer pourquoi le bouton Sélectionner un fichier CSV ne fonctionne pas :
| Problème | Résolution |
|---|---|
| Bloqueur de fenêtres pop-up | Il peut empêcher l’affichage de la page. Vérifiez que votre navigateur autorise les fenêtres pop-up sur le site du tableau de bord de Braze. |
| Navigateur obsolète | Assurez-vous que votre navigateur est à jour ; sinon, installez la dernière version. |
| Processus en arrière-plan | Fermez toutes les instances du navigateur, puis redémarrez votre ordinateur. |