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 les limites de taille maximale indiquées dans le tableau suivant.

Utiliser l’importation CSV

Étape 1 : Accéder à l’importation CSV

Pour accéder à l’importation CSV, rendez-vous dans Audiences > Import Users. Vous y trouverez un tableau répertoriant les détails des importations les plus récentes, tels que la date de téléchargement, le nom de la personne ayant effectué l’importation, le nom du fichier, la disponibilité du ciblage, le nombre d’enregistrements importés et le statut de l’importation.

Pour commencer, sélectionnez Attributes, Custom Events ou Recommended Events dans le menu déroulant Import Users. Si vous utilisez le mappeur de données ou si vous disposez déjà d’un fichier, vous pouvez télécharger votre fichier et passer directement à l’étape 5 : Mapper vos champs. Vous pouvez également télécharger le modèle correspondant pour vous aider à construire votre fichier CSV, mais cela est facultatif lorsque vous utilisez le mappeur de données.

Conseil

Étant donné que les événements recommandés utilisent un schéma défini, consultez l’onglet Recommended Events dans l’étape 3 : Construire votre fichier CSV avant votre premier téléchargement.

Étape 2 : Choisir un identifiant

Le fichier CSV que vous importez nécessite un identifiant dédié. Choisissez l’un des types d’identifiants suivants pour votre importation :

• external id
• user alias
• braze id
• email address and phone numbers

Lors de l’importation de vos données clients, vous pouvez utiliser un external_id comme identifiant unique pour 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 si aucun n’est trouvé.

• Télécharger : Modèle d’importation d’attributs CSV : External ID
• Télécharger : Modèle d’importation d’événements CSV : External ID

Remarque

Si vous téléchargez un mélange d’utilisateurs avec un external_id et d’utilisateurs sans, vous devez créer un CSV distinct pour chaque importation. Un seul CSV ne peut pas contenir à la fois des external_id et des alias d’utilisateur.

Pour cibler des utilisateurs qui ne possèdent pas d’external_id, vous pouvez importer une liste d’utilisateurs avec des alias d’utilisateur. Un alias sert d’identifiant utilisateur unique alternatif et peut être utile si vous essayez de communiquer avec des utilisateurs anonymes qui ne se sont pas inscrits ou n’ont pas créé de compte sur votre application.

Si vous téléchargez ou mettez à jour des profils utilisateur qui sont uniquement basés sur un alias, votre CSV doit contenir les deux colonnes suivantes :

• user_alias_name : Un identifiant utilisateur unique ; une alternative à l’external_id
• user_alias_label : Un libellé commun 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.

Important

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 uniquement basé sur un alias à un external_id, utilisez l’endpoint Identifier les utilisateurs.

Télécharger : Modèle d’importation d’attributs CSV : Alias d’utilisateur

Pour mettre à jour des profils utilisateur existants dans Braze en utilisant une valeur interne Braze ID au lieu d’un external_id ou de valeurs user_alias_name et user_alias_label, spécifiez braze_id comme en-tête de colonne.

Cela peut être utile si vous avez exporté des données utilisateur depuis Braze via notre option d’exportation CSV dans la segmentation et que vous souhaitez ajouter un nouvel attribut personnalisé à ces utilisateurs existants.

Important

Vous ne pouvez pas utiliser une importation CSV pour créer un nouvel utilisateur en utilisant braze_id. Cette méthode ne peut être utilisée que pour mettre à jour des utilisateurs préexistants au sein de la plateforme Braze.

Conseil

La valeur braze_id peut être libellée Appboy ID dans les exportations CSV du tableau de bord de Braze. Cet ID sera identique au braze_id d’un utilisateur, vous pouvez donc renommer cette colonne en braze_id lorsque vous réimportez le CSV.

Vous pouvez omettre un ID externe ou un 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 avec des adresses e-mail ou des numéros de téléphone, vérifiez les points suivants :

• Vérifiez que vous n’avez pas d’ID externes ou d’alias d’utilisateur pour ces profils dans votre fichier CSV. Si c’est le cas, Braze priorisera l’utilisation de l’ID externe ou de l’alias d’utilisateur avant l’adresse e-mail pour identifier les profils.
• Confirmez que votre fichier CSV est correctement formaté.

Remarque

Si vous incluez à la fois des adresses e-mail et des numéros de téléphone dans votre fichier CSV, l’adresse e-mail est prioritaire sur le numéro de téléphone lors de la recherche de 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. S’il existe plusieurs profils avec la même adresse e-mail, Braze utilisera la même logique que l’endpoint /users/track où le profil le plus récemment mis à jour sera actualisé.

Si un profil avec cette adresse e-mail ou ce numéro de téléphone n’existe pas, 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 : Construire votre fichier CSV

Vous pouvez télécharger l’un des types de données suivants sous forme d’un seul fichier CSV. Pour télécharger plus d’un type de données, téléchargez plusieurs fichiers CSV.

• Attributs utilisateur : cela inclut les attributs utilisateur par défaut et les attributs personnalisés. Les attributs utilisateur par défaut sont des clés réservées dans Braze (comme first_name ou email) et les attributs personnalisés sont des attributs utilisateur propres à votre entreprise (comme last_destination_searched).
• Événements personnalisés : ce sont des événements propres à votre entreprise qui reflètent des actions effectuées par un utilisateur, comme trip_booked pour une application de réservation de voyages.
• Événements recommandés : ce sont des événements personnalisés avec des schémas définis et un traitement spécialisé, comme les calculs automatiques de champs ou la gestion du panier, que les événements personnalisés génériques ne reçoivent pas. Ceux-ci incluent order_placed, product_viewed et cart_updated.

Lorsque vous êtes prêt à commencer la construction de votre fichier CSV, consultez les informations suivantes :

• user attributes
• custom events
• recommended events

Identifiants requis

Bien que l’external_id ne soit pas requis, votre fichier CSV doit inclure un identifiant utilisateur pouvant être mappé à un des identifiants suivants. Pour plus de détails sur chacun d’entre eux, consultez Choisir un identifiant.

• external_id
• braze_id
• user_alias_name et user_alias_label
• email
• phone

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 modification lors de l’étape de mappage.

Type de données	Description
Date et heure	Doit être stocké au format ISO-8601.
Booléen	Accepte true ou false.
Nombre	Doit être un entier ou un nombre à virgule flottante sans espaces ni virgules. Les nombres à virgule flottante doivent utiliser un point (.) comme séparateur décimal.
Chaîne de caractères	Peut contenir des virgules si la valeur est encadrée par des guillemets doubles ("").
Vide	Les valeurs vides ne remplaceront pas les valeurs existantes sur le profil utilisateur, et vous n’avez pas besoin d’inclure tous les attributs utilisateur existants dans votre fichier CSV.

Important

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 dans votre fichier CSV seront interprétées comme un séparateur de colonne et provoqueront des erreurs lors de l’analyse de votre fichier.

Pour télécharger ces types de valeurs, utilisez plutôt l’endpoint /users/track ou l’ingestion de données cloud.

Attributs par défaut

Important

Lors de l’importation d’attributs par défaut, les en-têtes de colonne que vous utilisez doivent correspondre exactement à l’orthographe et à la casse des attributs utilisateur par défaut. Sinon, Braze les détectera comme des attributs personnalisés.

Conseil

Pour la liste complète des attributs standard reconnus par Braze (via le SDK, l’API, le CSV et l’ingestion de données cloud), consultez Attributs standard. Le tableau suivant ne couvre que le sous-ensemble pouvant être défini via l’importation CSV.

Les attributs par défaut suivants sont disponibles pour l’importation d’utilisateurs.

Champ du profil utilisateur	Type de données	Description	Requis ?
external_id	Chaîne de caractères	Un identifiant utilisateur unique pour votre client.	Conditionnel. Voir Identifiants requis.
user_alias_name	Chaîne de caractères	Un identifiant utilisateur unique pour les utilisateurs anonymes, servant d’alternative à l’external_id. Doit être utilisé avec user_alias_label.	Conditionnel. Voir Identifiants requis.
user_alias_label	Chaîne de caractères	Un libellé commun permettant de regrouper les alias d’utilisateur. Doit être utilisé avec user_alias_name.	Conditionnel. 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 « AAAA-MM-JJ » (par exemple, 1980-12-21). Cela importe la date de naissance de votre utilisateur et vous permet de cibler les utilisateurs dont c’est l’anniversaire « aujourd’hui ».	Non
gender	Chaîne de caractères	« M », « F », « O » (autre), « N » (non applicable), « P » (préfère ne pas répondre), 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 tel qu’indiqué par vos utilisateurs, au format E.164 (par exemple, +442071838750). Consultez Numéros de téléphone des utilisateurs pour des conseils de formatage.	Non
email_open_tracking_disabled	Booléen	Accepte true ou false. Définissez sur true pour désactiver l’ajout du pixel de suivi d’ouverture à 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 pour tous les liens dans un futur e-mail envoyé à cet utilisateur.	Non
email_subscribe	Chaîne de caractères	Les valeurs disponibles sont opted_in (inscrit explicitement pour recevoir des e-mails), unsubscribed (désinscrit explicitement des e-mails) et subscribed (ni inscrit ni désinscrit).	Non
push_subscribe	Chaîne de caractères	Les valeurs disponibles sont opted_in (inscrit explicitement pour recevoir des notifications push), unsubscribed (désinscrit explicitement des notifications push) et subscribed (ni inscrit ni désinscrit).	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 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 : « AAAA-MM-JJ » « AAAA-MM-JJTHH:MM:SS+00:00 » « AAAA-MM-JJTHH:MM:SSZ » « AAAA-MM-JJTHH: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 (pas dans le groupe d’abonnement) ou subscribed (dans le groupe d’abonnement).	Non, mais fortement recommandé si subscription_group_id est utilisé

Mettre à jour le statut du groupe d’abonnement (facultatif)

De plus, vous pouvez ajouter des utilisateurs à des groupes d’abonnement e-mail ou SMS via l’importation d’utilisateurs. Cela est particulièrement utile pour le SMS, car un utilisateur doit être inscrit à un groupe d’abonnement SMS pour recevoir des messages via le canal SMS. Pour plus d’informations, consultez Groupes d’abonnement SMS.

Si vous mettez à jour les statuts des groupes d’abonnement, votre CSV doit contenir les deux colonnes suivantes :

• subscription_group_id : L’id du groupe d’abonnement.
• subscription_state : Les valeurs disponibles sont unsubscribed (pas dans le groupe d’abonnement) ou subscribed (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

Remarque

Un seul subscription_group_id peut être défini par ligne dans l’importation d’utilisateurs. Différentes lignes peuvent avoir des valeurs subscription_group_id différentes. Cependant, 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 requis, votre fichier CSV doit inclure un identifiant utilisateur mappé à un des identifiants suivants. Pour plus de détails sur chacun d’entre eux, consultez Choisir un identifiant.

• external_id
• braze_id
• user_alias_name et user_alias_label
• email
• phone

Champs d’événements personnalisés

En plus des champs standard répertoriés dans le tableau suivant, votre 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 au format <property name>. Braze détecte les propriétés pertinentes pour chaque événement en fonction de la présence d’une valeur dans la cellule CSV correspondante.

Par exemple, l’événement personnalisé trip_booked peut avoir la propriété destination. Vous pouvez l’importer en utilisant l’en-tête de colonne destination et en indiquant une valeur dans la cellule CSV correspondante. Cela permet à plusieurs événements d’avoir une propriété nommée destination sans nécessiter de colonnes séparées.

Remarque

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	Requis ?
external_id	Chaîne de caractères	Un identifiant utilisateur unique pour votre utilisateur.	Conditionnel. Voir Identifiants requis.
braze_id	Chaîne de caractères	Un identifiant attribué par Braze pour votre utilisateur.	Conditionnel. Voir Identifiants requis.
user_alias_name	Chaîne de caractères	Un identifiant utilisateur unique pour les utilisateurs anonymes, servant d’alternative à l’external_id. Doit être utilisé avec user_alias_label.	Conditionnel. Voir Identifiants requis.
user_alias_label	Chaîne de caractères	Un libellé commun permettant de regrouper les alias d’utilisateur. Doit être utilisé avec user_alias_name.	Conditionnel. 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ée qu’en l’absence d’autres identifiants. Voir la note suivante.
phone	Chaîne de caractères	Un numéro de téléphone tel qu’indiqué par vos utilisateurs, au format E.164 (par exemple, +442071838750). Consultez Numéros de téléphone des utilisateurs pour des conseils de formatage.	Non, et ne peut être utilisé qu’en l’absence d’autres identifiants. Voir la note suivante.
name	Chaîne de caractères	Un événement personnalisé de vos utilisateurs.	Oui
time	Chaîne de caractères	L’horodatage de l’événement. Peut être transmis dans l’un des formats ISO-8601 suivants : « AAAA-MM-JJ » « AAAA-MM-JJTHH:MM:SS+00:00 » « AAAA-MM-JJTHH:MM:SSZ » « AAAA-MM-JJTHH: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 lorsqu’il y a une valeur non nulle dans la cellule CSV correspondante.	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 CSV d’événements personnalisés avec un en-tête <property_name> et une valeur non nulle dans la cellule appropriée, ou en utilisant l’ancien format à notation par points. Cela garantit que Braze mappe chaque propriété au bon événement. Si le format est incorrect, les propriétés peuvent être ignorées ou l’importation peut échouer, surtout lorsque plusieurs types d’événements sont inclus dans un seul fichier.

Un événement par ligne

Chaque ligne de votre CSV représente un seul événement personnalisé pour un seul utilisateur. Si un utilisateur a plusieurs événements, vous devez inclure une ligne séparée pour chaque événement, même s’ils partagent le même identifiant utilisateur.

Important

Lorsqu’une ligne contient des données pour un événement spécifique, ne remplissez que les colonnes correspondant aux propriétés de cet événement. Laissez les colonnes des autres événements vides.

Exemple de structure CSV

Le tableau suivant illustre le formatage correct pour l’importation d’événements personnalisés avec des propriétés. Cet exemple montre deux utilisateurs ayant chacun effectué des événements différents : l’un a loué un film et l’autre a acheté une série télévisée.

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 123 a déclenché l’événement rented_movie avec les propriétés movie_name (Ghostbusters) et genre (Action)
• L’utilisateur 456 a déclenché l’événement bought_sitcom avec les propriétés sitcom_name (Scrubs) et genre (Comedy)
• Chaque événement ne remplit que les colonnes de propriétés pertinentes, laissant les colonnes de propriétés des autres événements vides

Identifiants requis

Bien que l’external_id ne soit pas requis, votre fichier CSV doit inclure l’un des identifiants suivants comme en-tête. Pour plus de détails sur chacun d’entre eux, consultez Choisir un identifiant.

• external_id
• braze_id
• user_alias_name et user_alias_label
• email
• phone

Champs d’événements recommandés

En plus des champs suivants, votre CSV doit également contenir des en-têtes de colonne supplémentaires pour les propriétés requises des événements recommandés, en fonction de l’événement recommandé que vous essayez d’importer. Ces propriétés doivent avoir un en-tête de colonne au format <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 avoir les propriétés order_id et total_value, entre autres. Celles-ci peuvent être importées en utilisant les en-têtes de colonne order_id et total_value, ou en utilisant des en-têtes basés sur votre modèle de données et en les mappant à la propriété correcte. Pour la liste complète des propriétés d’événements recommandés, consultez Schémas d’événements recommandés.

Champ du profil utilisateur	Type de données	Informations	Requis ?
external_id	Chaîne de caractères	Un identifiant utilisateur unique pour votre utilisateur.	Conditionnel. Voir Identifiants requis.
braze_id	Chaîne de caractères	Un identifiant attribué par Braze pour votre utilisateur.	Conditionnel. Voir Identifiants requis.
user_alias_name	Chaîne de caractères	Un identifiant utilisateur unique pour les utilisateurs anonymes, servant d’alternative à l’external_id. Doit être utilisé avec user_alias_label.	Conditionnel. Voir Identifiants requis.
user_alias_label	Chaîne de caractères	Un libellé commun permettant de regrouper les alias d’utilisateur. Doit être utilisé avec user_alias_name.	Conditionnel. 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ée qu’en l’absence d’autres identifiants. Voir la note suivante.
phone	Chaîne de caractères	Un numéro de téléphone tel qu’indiqué par vos utilisateurs, au format E.164 (par exemple, +442071838750). Consultez Numéros de téléphone des utilisateurs pour des conseils de formatage.	Non, et ne peut être utilisé qu’en l’absence d’autres identifiants. Voir la note suivante.
name	Chaîne de caractères	Un événement personnalisé de vos utilisateurs.	Oui
time	Chaîne de caractères	L’horodatage de l’événement. Peut être transmis dans l’un des formats ISO-8601 suivants : « AAAA-MM-JJ » « AAAA-MM-JJTHH:MM:SS+00:00 » « AAAA-MM-JJTHH:MM:SSZ » « AAAA-MM-JJTHH: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.	Conditionnel. Voir Schémas d’événements recommandés.

Exigences de format pour les événements recommandés

Lors de l’importation d’événements recommandés via CSV, vous devez formater votre fichier conformément aux exigences suivantes pour que l’importation des données réussisse. Pour réduire 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 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, les événements peuvent être ignorés ou l’importation peut échouer, surtout lorsque plusieurs types d’événements sont inclus dans un seul fichier.

Regroupements d’é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 a une propriété requise products qui est un tableau d’objets, et chaque objet imbriqué possède ses propres propriétés imbriquées requises.

Le CSV d’événements recommandés prend en charge le regroupement de plusieurs lignes ayant le même identifiant, le même nom d’événement et le même horodatage, à condition que les lignes ne soient pas séparées dans le fichier. Cela vous permet d’utiliser des lignes séquentielles pour renseigner les valeurs des propriétés imbriquées. Lors du formatage de votre fichier, remplissez les lignes supplémentaires uniquement avec l’identifiant, le nom de l’événement, l’horodatage et les propriétés imbriquées pertinentes. Vous n’avez pas besoin de répéter les valeurs des propriétés de niveau supérieur dans 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 d’événements recommandés), vous pouvez mapper et importer des propriétés facultatives telles que image_url pour la propriété de tableau products. Vous pouvez également transmettre des propriétés supplémentaires dans la propriété de niveau supérieur metadata, 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 requises, cliquez sur Load optional properties pour charger et mapper les propriétés supplémentaires.

Exemple de structure CSV

L’exemple suivant illustre le formatage correct pour l’importation d’événements recommandés avec les propriétés requises et les propriétés imbriquées. Cet exemple montre trois utilisateurs, chacun passant une commande avec deux produits distincts.

Dans cet exemple :

• Les commandes sont identifiées et regroupées par le même identifiant, le même nom d’événement et le même horodatage, avec toutes les lignes pertinentes en séquence.
• Les utilisateurs user_101, user_102 et user_103 ont chacun déclenché l’événement order_placed avec les propriétés requises et les propriétés imbriquées.
• Les commandes des utilisateurs user_101 et user_102 incluent des métadonnées ajoutées au tableau de propriétés discounts.

Important

Lorsqu’une ligne contient des données pour un événement spécifique, ne remplissez que les colonnes correspondant aux propriétés de cet événement. Laissez les colonnes des autres événements vides.

Étape 4 : Télécharger votre fichier

Pour télécharger votre fichier, sélectionnez Attributes, Custom Events ou Recommended Events dans le menu déroulant Import Users, cliquez sur Browse Files et téléchargez votre CSV. Braze affiche un aperçu des premières lignes et un résumé 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 non réactif pendant le téléchargement du fichier et le calcul de l’importation par Braze. Ces téléchargements et calculs peuvent prendre plus de temps que pour les fichiers plus petits. Laissez cette étape se terminer. Pour plus de contexte sur les limites de fichiers et les délais, consultez Construire votre CSV.

Remarque

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

Important

Les importations CSV d’utilisateurs sont disponibles au téléchargement depuis le tableau de bord pendant 14 jours après le téléchargement. Après cette période, 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 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 avez également la possibilité d’ajuster manuellement les suggestions ou de sélectionner des attributs, événements ou propriétés différents.

Pour les propriétés d’événement, Braze détecte les propriétés et les associe aux événements pertinents en fonction de la présence d’une valeur non nulle dans la cellule CSV, ou à partir d’en-têtes utilisant l’ancien format à notation par points (tel que <event name>.properties.<property name>).

Statuts de mappage

La colonne de statut de mappage indique l’action qui se produit lors de l’importation de votre fichier CSV. Elle peut prendre l’une des valeurs suivantes.

Modifier de nouveaux attributs, événements et propriétés

Lorsqu’un attribut, un événement ou une propriété d’événement correspondant n’existe pas dans votre espace de travail, Braze tente de créer un nouvel attribut, événement ou propriété 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 Edit new attribute, Edit new event ou Edit new property à côté du statut de mappage.

Remarque

Vous ne pouvez pas passer au-delà de l’étape de mappage tant qu’un identifiant n’est pas 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. Consultez la section Champs requis pour plus d’informations.

É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 des paramètres d’importation. Si vous n’avez pas besoin de créer un nouveau filtre de ciblage ou Segment à partir de votre importation, sélectionnez Do not make this list available as a targeting filter.

Étape 7 : Valider votre fichier (facultatif)

Avant de démarrer votre importation, vous pouvez exécuter une validation de fichier pour vérifier chaque ligne à la recherche d’erreurs et d’avertissements. Pour valider votre fichier, sélectionnez Validate file before importing sur la page des paramètres d’importation, puis sélectionnez Next.

La validation peut prendre jusqu’à 2 minutes pour les fichiers à la taille maximale autorisée. Pendant l’exécution de la validation, vous pouvez sélectionner Skip validation pour l’ignorer et procéder immédiatement.

Résultats de la validation

Lorsque la validation est terminée, l’un des résultats suivants apparaît.

Comprendre le rapport d’erreurs

Le rapport d’erreurs est un fichier CSV contenant chaque ligne signalée avec ses données d’origine et une description du problème.

Après avoir examiné le rapport, vous pouvez corriger les problèmes dans votre fichier d’origine et le retélécharger, ou poursuivre l’importation en acceptant les résultats partiels.

Étape 8 : Démarrer votre importation CSV

Lorsque vous êtes prêt, sélectionnez Start Import. Vous pouvez suivre la progression en cours sur la page Import Users, 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 non réactif ou répondre lentement, mais l’importation est toujours en cours.

Remarque

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 d’être séquentiel. Si vous avez besoin que les importations CSV s’exécutent les unes après les autres, attendez qu’une importation CSV soit terminée avant de télécharger la suivante.

Statuts d’importation

Après avoir démarré votre importation, vous pouvez vérifier son statut sur la page Import Users.

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

Important

Les fichiers CSV précédemment téléchargés sont disponibles au téléchargement depuis la page Import Users pendant 14 jours après la date de téléchargement. Après 14 jours, le fichier est définitivement supprimé et ne peut plus être consulté.

Considérations relatives aux points de donnée

Chaque donnée client importée à partir d’un fichier CSV écrase la valeur existante dans les profils utilisateur 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ée Braze, votre gestionnaire de compte Braze peut y répondre.

Important

Définir language ou country pour un utilisateur via une importation CSV ou l’API empêche Braze de capturer automatiquement ces informations via le SDK.

Résolution des problèmes

Si vous avez utilisé la validation de fichier, commencez par le rapport d’erreurs, car il inclut le problème spécifique pour chaque ligne signalée et une description de la manière de le corriger. Pour les lignes qui ont échoué lors de l’importation plutôt que lors de la validation, téléchargez le rapport d’erreurs en survolant la ligne et en sélectionnant le bouton sur la page Import Users.

Pour résoudre les problèmes d’importation CSV, examinez ces problèmes courants dans les sections suivantes.

Importation CSV bloquée sur Calculating

Dans Import Users, Calculating signifie que Braze prépare encore le fichier pour le traitement. Au cours de cette étape, le nombre de lignes peut s’afficher comme 0 / Calculating jusqu’à la fin de la préparation.

Si votre importation semble bloquée sur Calculating :

• Laissez l’importation continuer. N’annulez pas et ne rechargez pas le fichier à moins que le support Braze ne vous le conseille.
• Confirmez que votre fichier respecte les limites prises en charge dans Construire votre CSV.
• Consultez Étape 4 : Charger votre fichier et Étape 8 : Démarrer votre importation CSV pour le comportement attendu du tableau de bord et les temps de traitement.
• Contactez le support Braze si Calculating dure bien plus longtemps que prévu pour la taille de votre fichier après avoir vérifié ces points.

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 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 un deux-points (:).

Caractères de guillemet dans les valeurs external_id

Si une cellule external_id contient un guillemet double, échappez-le en doublant le caractère (""), comme décrit sous Guillemets doubles non échappés ou déséquilibrés. L’importation CSV n’utilise pas l’échappement par barre oblique inversée.

L’importation CSV n’est pas disponible comme filtre de segment

Vous ne pouvez utiliser une importation CSV comme filtre de segment que si vous avez activé une préférence de ciblage lors du chargement.

Pour vérifier si la disponibilité du ciblage est activée pour une importation existante :

1. Sur la page Import Users, trouvez votre importation CSV.
2. Vérifiez si Go to Segment apparaît pour cette importation.
3. Si Go to Segment apparaît, votre CSV est disponible dans le filtre de segment Updated/Imported from CSV.
4. Si Go to Segment n’apparaît pas, la disponibilité du ciblage n’était pas activée pour cette importation.

Vous ne pouvez pas activer la disponibilité du ciblage une fois qu’un chargement CSV est terminé. Pour utiliser ce CSV comme filtre de segment, rechargez le fichier, et à l’Étape 6 : Choisir les préférences de ciblage, sélectionnez Create targeting filter ou Create targeting filter and add to new segment.

Si votre objectif est de créer un segment sans mettre à jour les données de profil, chargez un CSV qui inclut uniquement les colonnes d’identifiants (par exemple, external_id ou les colonnes d’identifiants d’alias), puis sélectionnez Create targeting filter and add to new segment.

Problèmes de formatage de fichier

Ligne mal formée

Si votre chargement s’est terminé avec des erreurs, il peut y avoir une ligne mal formée dans votre fichier CSV.

Pour importer correctement les données, il doit y avoir une ligne d’en-tête. Chaque ligne doit avoir le même nombre de cellules que la ligne d’en-tête. Les lignes ayant plus ou moins de valeurs que la ligne d’en-tête seront exclues de l’importation. Les virgules dans une valeur seront interprétées comme un séparateur et peuvent entraîner cette erreur.

De plus, toutes les données doivent être encodées en UTF-8. Si le fichier est enregistré avec un encodage ancien (par exemple, certaines valeurs par défaut d’Excel), les caractères spéciaux et les URL dans les cellules peuvent être corrompus et apparaître sous forme de points d’interrogation (?) dans Braze ou dans les messages envoyés.

Si votre fichier CSV comporte des lignes vides et importe moins de lignes que le nombre total de lignes dans le fichier CSV, cela peut ne pas indiquer un problème avec l’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 essayez d’importer.

Ligne manquante

Il existe plusieurs raisons pour lesquelles le nombre d’utilisateurs importés peut ne pas correspondre au nombre total de lignes de votre fichier CSV :

Guillemets de chaîne de caractères

Les valeurs encapsulées dans des guillemets simples ('') ou doubles ("") seront lues comme des chaînes de caractères lors de l’importation.

Dates incorrectement 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 de données

Adresses e-mail invalides

Si votre chargement s’est terminé avec des erreurs, il peut y avoir une ou plusieurs adresses e-mail chiffrées invalides. Confirmez 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 e-mail hachée partout où un e-mail est inclus. Ces valeurs e-mail hachées sont fournies par votre équipe interne.
• Lors de la création d’un nouvel utilisateur, vous devez ajouter email_encrypted avec la valeur e-mail chiffrée 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 a pas, vous devez ajouter email_encrypted. Sinon, Braze ne mettra pas à jour l’utilisateur.

Données importées comme attribut personnalisé

Si une donnée utilisateur par défaut (telle que email ou first_name) est importée comme attribut personnalisé, vérifiez la casse et l’espacement de votre fichier CSV. Par exemple, First_name est importé comme attribut personnalisé, tandis que first_name est correctement importé dans le champ « first name » du profil 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 Custom Attributes 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 chaque valeur d’une colonne soit du même type de données. Les valeurs qui ne correspondent pas au type de données de leur attribut provoquent des erreurs de segmentation.

De plus, commencer un attribut numérique par zéro causera des problèmes, car les nombres commençant par zéro 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. Cependant, ce type de données n’est pas disponible dans la comparaison numérique de segmentation.

Types d’attributs par défaut

Certains attributs par défaut n’acceptent que certaines valeurs comme valides pour les mises à jour utilisateur. Pour plus de détails, consultez Construire votre CSV.

Les espaces en fin de chaîne et les différences de casse peuvent entraîner l’interprétation d’une valeur comme invalide. Par exemple, dans le fichier CSV suivant, seul l’utilisateur de la première ligne (brazetest1) a ses statuts e-mail et push mis à jour avec succès, car les valeurs acceptées sont unsubscribed, subscribed et opted_in.

1
2
3

external_id,email,email_subscribe,push_subscribe
brazetest1,[email protected],unsubscribed,unsubscribed
brazetest2,[email protected],Unsubscribed,Unsubscribed

« Select CSV File » ne fonctionne pas

Il existe plusieurs raisons pour lesquelles le bouton Select CSV File peut ne pas fonctionner :