Importación CSV

Aprende a registrar y actualizar atributos de usuario, eventos personalizados y eventos recomendados mediante la importación CSV.

Acerca de la importación en CSV

Puedes utilizar la importación en CSV para registrar y actualizar los siguientes atributos de usuario, eventos personalizados y eventos recomendados. Braze acepta estos datos como archivos CSV estándar dentro de los tamaños máximos indicados en la siguiente tabla.

Uso de la importación CSV

Paso 1: Navegar a la importación CSV

Para acceder a la importación CSV, ve a Audiencias > Importar usuarios. Aquí encontrarás una tabla con los detalles de las importaciones más recientes, como la fecha de carga, el nombre del responsable de la carga, el nombre del archivo, la disponibilidad de segmentación, el número de registros importados y el estado de la importación.

Para comenzar, selecciona Atributos, Eventos personalizados o Eventos recomendados en el desplegable Importar usuarios. Si usas el mapeador de datos o ya tienes un archivo, puedes cargarlo y pasar al Paso 5: Mapear tus campos. También puedes descargar la plantilla correspondiente para ayudarte a construir tu archivo CSV para la carga, aunque esto es opcional cuando usas el mapeador de datos.

Consejo

Dado que los eventos recomendados usan un esquema definido, revisa la pestaña Eventos recomendados en el Paso 3: Construir tu archivo CSV antes de tu primera carga.

Paso 2: Elegir un identificador

El archivo CSV que importes necesita un identificador dedicado. Elige uno de los siguientes tipos de identificador para tu importación:

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

Al importar los datos de tus clientes, puedes usar un external_id como identificador único de cada cliente. Cuando proporcionas un external_id en tu importación, Braze actualiza cualquier usuario existente con el mismo external_id o crea un usuario recién identificado con ese external_id configurado si no se encuentra uno.

• Descargar: Plantilla de importación de atributos CSV: ID externo
• Descargar: Plantilla de importación de eventos CSV: ID externo

Nota

Si estás cargando una combinación de usuarios con external_id y usuarios sin él, necesitas crear un CSV para cada importación. Un CSV no puede contener tanto external_id como alias de usuario.

Para dirigirte a usuarios que no tienen un external_id, puedes importar una lista de usuarios con alias de usuario. Un alias sirve como identificador único alternativo del usuario y puede ser útil si intentas realizar marketing a usuarios anónimos que no se han registrado o creado una cuenta en tu aplicación.

Si estás cargando o actualizando perfiles de usuario que son solo de alias, debes tener las dos columnas siguientes en tu CSV:

• user_alias_name: Un identificador de usuario único; una alternativa al external_id
• user_alias_label: Una etiqueta común para agrupar alias de usuario

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

Cuando proporcionas tanto un user_alias_name como un user_alias_label en tu importación, Braze actualiza cualquier usuario existente con los mismos user_alias_name y user_alias_label. Si no se encuentra un usuario, Braze crea un usuario recién identificado con ese user_alias_name configurado.

Importante

No puedes usar una importación CSV para actualizar un usuario existente con un user_alias_name si ya tiene un external_id. En cambio, esto crea un nuevo perfil de usuario con el user_alias_name asociado. Para asociar un usuario solo de alias con un external_id, usa el endpoint Identificar usuarios.

Descargar: Plantilla de importación de atributos CSV: Alias de usuario

Para actualizar perfiles de usuario existentes en Braze usando un valor de ID interno de Braze en lugar de un external_id o un valor de user_alias_name y user_alias_label, especifica braze_id como encabezado de columna.

Esto puede ser útil si exportaste datos de usuario de Braze a través de nuestra opción de exportación CSV dentro de la segmentación y deseas añadir un nuevo atributo personalizado a esos usuarios existentes.

Importante

No puedes usar una importación CSV para crear un nuevo usuario usando braze_id. Este método solo puede usarse para actualizar usuarios preexistentes dentro de la plataforma Braze.

Consejo

El valor de braze_id puede estar etiquetado como Appboy ID en las exportaciones CSV del panel de Braze. Este ID será el mismo que el braze_id de un usuario, por lo que puedes renombrar esta columna a braze_id cuando reimportes el CSV.

Puedes omitir un ID externo o alias de usuario y usar una dirección de correo electrónico o un número de teléfono para importar usuarios. Antes de importar un archivo CSV con direcciones de correo electrónico o números de teléfono, verifica lo siguiente:

• Comprueba que no tengas IDs externos o alias de usuario para estos perfiles en tu archivo CSV. Si los tienes, Braze priorizará el uso del ID externo o alias de usuario antes que la dirección de correo electrónico para identificar perfiles.
• Confirma que tu archivo CSV tenga el formato correcto.

Nota

Si incluyes tanto direcciones de correo electrónico como números de teléfono en tu archivo CSV, la dirección de correo electrónico se prioriza sobre el número de teléfono al buscar perfiles.

Si un perfil existente tiene esa dirección de correo electrónico o número de teléfono, ese perfil se actualiza, y Braze no crea un perfil nuevo. Si hay varios perfiles con la misma dirección de correo electrónico, Braze usará la misma lógica que el endpoint /users/track, donde se actualizará el perfil actualizado más recientemente.

Si un perfil con esa dirección de correo electrónico o número de teléfono no existe, Braze crea un nuevo perfil con ese identificador. Puedes usar el endpoint /users/identify para identificar este perfil posteriormente. Para eliminar un perfil de usuario, también puedes usar el endpoint /users/delete.

Paso 3: Construir tu archivo CSV

Puedes cargar cualquiera de los siguientes tipos de datos como un solo archivo CSV. Para cargar más de un tipo de datos, sube varios archivos CSV.

• Atributos de usuario: Esto incluye tanto atributos de usuario predeterminados como personalizados. Los atributos de usuario predeterminados son claves reservadas en Braze (como first_name o email), y los atributos personalizados son atributos de usuario exclusivos de tu negocio (como last_destination_searched).
• Eventos personalizados: Son exclusivos de tu negocio y reflejan acciones que un usuario ha realizado, como trip_booked para una aplicación de reservas de viajes.
• Eventos recomendados: Son eventos personalizados con esquemas definidos y procesamiento especializado, como cálculos automáticos de campos o gestión de carritos, que los eventos personalizados genéricos no reciben. Incluyen order_placed, product_viewed y cart_updated.

Cuando estés listo para empezar a construir tu archivo CSV, consulta la siguiente información:

• user attributes
• custom events
• recommended events

Identificadores requeridos

Aunque external_id no es obligatorio, tu archivo CSV debe incluir un identificador de usuario que pueda mapearse a uno de los siguientes identificadores. Para más detalles sobre cada uno, revisa Elegir un identificador.

• external_id
• braze_id
• user_alias_name y user_alias_label
• email
• phone

Atributos personalizados

Los siguientes tipos de datos pueden usarse como atributos personalizados para la importación CSV. Los encabezados de columna que no coincidan exactamente con un atributo predeterminado se importan como atributos personalizados en Braze a menos que se cambien durante el paso de mapeo.

Tipo de datos	Descripción
Datetime	Debe almacenarse en formato ISO-8601.
Boolean	Acepta true o false.
Número	Debe ser un entero o flotante sin espacios ni comas. Los flotantes deben usar un punto (.) como separador decimal.
Cadena	Puede contener comas si el valor está entre comillas dobles ("").
En blanco	Los valores en blanco no sobrescribirán los valores existentes en el perfil de usuario, y no necesitas incluir todos los atributos de usuario existentes en tu archivo CSV.

Importante

Los arreglos, tokens de notificaciones push y tipos de datos de eventos personalizados no son compatibles con la importación de usuarios, ya que las comas en tu archivo CSV se interpretarán como separador de columna y causarán errores al analizar tu archivo.

Para cargar este tipo de valores, usa el endpoint /users/track o la ingesta de datos en la nube en su lugar.

Atributos predeterminados

Importante

Al importar atributos predeterminados, los encabezados de columna que uses deben coincidir exactamente con la ortografía y las mayúsculas de los atributos de usuario predeterminados. De lo contrario, Braze los detectará como atributos personalizados.

Consejo

Para la lista completa de atributos estándar que Braze reconoce (a través de SDK, API, CSV e ingesta de datos en la nube), consulta Atributos estándar. La siguiente tabla cubre solo el subconjunto que se puede configurar a través de la importación CSV.

Los siguientes atributos predeterminados están disponibles para la importación de usuarios.

Campo del perfil de usuario	Tipo de datos	Descripción	¿Obligatorio?
external_id	Cadena	Un identificador de usuario único para tu cliente.	Condicional. Ver Identificadores requeridos.
user_alias_name	Cadena	Un identificador de usuario único para usuarios anónimos que es una alternativa al external_id. Debe usarse con user_alias_label.	Condicional. Ver Identificadores requeridos.
user_alias_label	Cadena	Una etiqueta común para agrupar alias de usuario. Debe usarse con user_alias_name.	Condicional. Ver Identificadores requeridos.
first_name	Cadena	El nombre de tus usuarios como lo han indicado (por ejemplo, Jane).	No
last_name	Cadena	El apellido de tus usuarios como lo han indicado (por ejemplo, Doe).	No
email	Cadena	El correo electrónico de tus usuarios como lo han indicado (por ejemplo, [email protected]).	No
country	Cadena	Los códigos de país deben pasarse a Braze en el estándar ISO-3166-1 alfa-2 (por ejemplo, GB).	No
dob	Cadena	Debe pasarse en el formato “AAAA-MM-DD” (por ejemplo, 1980-12-21). Esto importa la fecha de nacimiento de tu usuario y te permite dirigirte a usuarios cuyo cumpleaños es “hoy”.	No
gender	Cadena	“M”, “F”, “O” (otro), “N” (no aplica), “P” (prefiere no decir) o nil (desconocido).	No
home_city	Cadena	La ciudad de residencia de tus usuarios como la han indicado (por ejemplo, London).	No
language	Cadena	El idioma debe pasarse a Braze en el estándar ISO-639-1 (por ejemplo, en). Consulta nuestra lista de idiomas aceptados.	No
phone	Cadena	Un número de teléfono según lo indicado por tus usuarios, en formato E.164 (por ejemplo, +442071838750). Consulta Números de teléfono de usuario para orientación sobre el formato.	No
email_open_tracking_disabled	Boolean	Acepta true o false. Establece en true para deshabilitar el píxel de seguimiento de aperturas de todos los correos electrónicos futuros enviados a este usuario.	No
email_click_tracking_disabled	Boolean	Acepta true o false. Establece en true para deshabilitar el seguimiento de clics de todos los enlaces dentro de un correo electrónico futuro enviado a este usuario.	No
email_subscribe	Cadena	Los valores disponibles son opted_in (registrado explícitamente para recibir mensajes de correo electrónico), unsubscribed (excluido explícitamente de los mensajes de correo electrónico) y subscribed (ni incluido ni excluido).	No
push_subscribe	Cadena	Los valores disponibles son opted_in (registrado explícitamente para recibir mensajes push), unsubscribed (excluido explícitamente de los mensajes push) y subscribed (ni incluido ni excluido).	No
time_zone	Cadena	La zona horaria debe pasarse a Braze en el mismo formato que la base de datos de zonas horarias IANA (por ejemplo, America/New_York o Eastern Time (US & Canada)).	No
date_of_first_session date_of_last_session	Cadena	Puede pasarse en uno de los siguientes formatos ISO 8601: “AAAA-MM-DD” “AAAA-MM-DDTHH:MM:SS+00:00” “AAAA-MM-DDTHH:MM:SSZ” “AAAA-MM-DDTHH:MM:SS” (por ejemplo, 2019-11-20T18:38:57)	No
subscription_group_id	Cadena	El id de tu grupo de suscripción. Este identificador se puede encontrar en la página de grupos de suscripción de tu panel.	No
subscription_state	Cadena	El estado de suscripción para el grupo de suscripción especificado por subscription_group_id. Los valores permitidos son unsubscribed (no está en el grupo de suscripción) o subscribed (está en el grupo de suscripción).	No, pero se recomienda encarecidamente si se usa subscription_group_id

Actualizar el estado del grupo de suscripción (opcional)

Además, puedes añadir usuarios a grupos de suscripción de correo electrónico o servicio de mensajes cortos a través de la importación de usuarios. Esto es particularmente útil para el servicio de mensajes cortos, ya que un usuario debe estar inscrito en un grupo de suscripción de servicio de mensajes cortos para recibir mensajes a través del canal de servicio de mensajes cortos. Para más información, consulta Grupos de suscripción de servicio de mensajes cortos.

Si estás actualizando estados de grupos de suscripción, debes tener las dos columnas siguientes en tu CSV:

• subscription_group_id: El id del grupo de suscripción.
• subscription_state: Los valores disponibles son unsubscribed (no está en el grupo de suscripción) o subscribed (está en el grupo de suscripción).

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

Nota

Solo se puede configurar un único subscription_group_id por fila en la importación de usuarios. Las diferentes filas pueden tener distintos valores de subscription_group_id. Sin embargo, si necesitas inscribir a los mismos usuarios en varios grupos de suscripción, tendrás que realizar múltiples importaciones.

Identificadores requeridos

Aunque external_id no es obligatorio, tu archivo CSV debe incluir un identificador de usuario que se mapee a uno de los siguientes identificadores. Para más detalles sobre cada uno, revisa Elegir un identificador.

• external_id
• braze_id
• user_alias_name y user_alias_label
• email
• phone

Campos de eventos personalizados

Además de los campos estándar enumerados en la siguiente tabla, tu CSV también puede contener encabezados de columna adicionales para propiedades del evento. Estas propiedades deben tener un encabezado de columna con el formato <property name>. Braze detecta las propiedades relevantes para cada evento en función de si hay un valor en la celda CSV correspondiente.

Por ejemplo, el evento personalizado trip_booked puede tener la propiedad destination. Puedes importar esto usando el encabezado de columna destination y teniendo un valor en la celda CSV correspondiente. Esto permite que múltiples eventos tengan una propiedad llamada destination sin necesidad de columnas separadas.

Nota

Aunque el formato heredado para los encabezados de propiedades de evento sigue siendo compatible, los encabezados de propiedades no necesitan seguir el formato <event_name>.properties.<property name>.

Campo del perfil de usuario	Tipo de datos	Información	¿Obligatorio?
external_id	Cadena	Un identificador de usuario único para tu usuario.	Condicional. Ver Identificadores requeridos.
braze_id	Cadena	Un identificador asignado por Braze para tu usuario.	Condicional. Ver Identificadores requeridos.
user_alias_name	Cadena	Un identificador de usuario único para usuarios anónimos, que es una alternativa al external_id. Debe usarse con user_alias_label.	Condicional. Ver Identificadores requeridos.
user_alias_label	Cadena	Una etiqueta común para agrupar alias de usuario. Debe usarse con user_alias_name.	Condicional. Ver Identificadores requeridos.
email	Cadena	El correo electrónico de tus usuarios como lo han indicado (por ejemplo, [email protected]).	No, y solo puede usarse en ausencia de otros identificadores. Ve la nota siguiente.
phone	Cadena	Un número de teléfono según lo indicado por tus usuarios, en formato E.164 (por ejemplo, +442071838750). Consulta Números de teléfono de usuario para orientación sobre el formato.	No, y solo puede usarse en ausencia de otros identificadores. Ve la nota siguiente.
name	Cadena	Un evento personalizado de tus usuarios.	Sí
time	Cadena	La hora del evento. Puede pasarse en uno de los siguientes formatos ISO-8601: “AAAA-MM-DD” “AAAA-MM-DDTHH:MM:SS+00:00” “AAAA-MM-DDTHH:MM:SSZ” “AAAA-MM-DDTHH:MM:SS” (por ejemplo, 2019-11-20T18:38:57)	Sí
<property name>	Múltiple	Una propiedad de evento que puedes usar en múltiples tipos de eventos. Un ejemplo es destination. Esta propiedad se asocia con un evento cuando hay un valor no nulo en la celda CSV correspondiente.	No
<event name>.properties.<property name>	Múltiple	Una propiedad de evento asociada con un evento personalizado. Un ejemplo es trip_booked.properties.destination	No

Comprender el formato de eventos personalizados

Formatea correctamente tu CSV de eventos personalizados con un encabezado <property_name> y un valor no nulo en la celda correcta, o usando el formato heredado de notación de puntos. Esto asegura que Braze mapee cada propiedad al evento correcto. Si el formato es incorrecto, las propiedades pueden descartarse o la importación puede fallar, especialmente cuando se incluyen múltiples tipos de eventos en un archivo.

Un evento por fila

Cada fila de tu CSV representa un solo evento personalizado para un solo usuario. Si un usuario tiene múltiples eventos, debes incluir una fila separada para cada evento, incluso si comparten el mismo identificador de usuario.

Importante

Cuando una fila contiene datos para un evento específico, solo completa las columnas para las propiedades de ese evento. Deja las columnas de otros eventos en blanco.

Ejemplo de estructura CSV

La siguiente tabla muestra el formato correcto para importar eventos personalizados con propiedades. Este ejemplo muestra dos usuarios que realizaron diferentes eventos: uno alquiló una película y otro compró una serie de comedia.

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

En este ejemplo:

• El usuario 123 activó el evento rented_movie con las propiedades movie_name (Ghostbusters) y genre (Action)
• El usuario 456 activó el evento bought_sitcom con las propiedades sitcom_name (Scrubs) y genre (Comedy)
• Cada evento solo completa sus columnas de propiedades relevantes, dejando en blanco las columnas de propiedades de otros eventos

Identificadores requeridos

Aunque external_id no es obligatorio, tu archivo CSV debe incluir uno de los siguientes identificadores como encabezado. Para más detalles sobre cada uno, revisa Elegir un identificador.

• external_id
• braze_id
• user_alias_name y user_alias_label
• email
• phone

Campos de eventos recomendados

Además de lo siguiente, tu CSV también debe contener encabezados de columna adicionales para las propiedades de eventos recomendados requeridas, según el evento recomendado que estés intentando importar. Estas propiedades deben tener un encabezado de columna con el formato <property_name> y pueden mapearse a la propiedad correspondiente del evento recomendado.

Por ejemplo, el evento recomendado order_placed debe tener las propiedades order_id y total_value, entre otras. Estas pueden importarse teniendo los encabezados de columna order_id y total_value, o teniendo encabezados basados en tu modelo de datos y mapeándolos a la propiedad correcta. Para una lista completa de propiedades de eventos recomendados, consulta Esquemas de eventos recomendados.

Campo del perfil de usuario	Tipo de datos	Información	¿Obligatorio?
external_id	Cadena	Un identificador de usuario único para tu usuario.	Condicional. Ver Identificadores requeridos.
braze_id	Cadena	Un identificador asignado por Braze para tu usuario.	Condicional. Ver Identificadores requeridos.
user_alias_name	Cadena	Un identificador de usuario único para usuarios anónimos que es una alternativa al external_id. Debe usarse con user_alias_label.	Condicional. Ver Identificadores requeridos.
user_alias_label	Cadena	Una etiqueta común para agrupar alias de usuario. Debe usarse con user_alias_name.	Condicional. Ver Identificadores requeridos.
email	Cadena	El correo electrónico de tus usuarios como lo han indicado (por ejemplo, [email protected]).	No, y solo puede usarse en ausencia de otros identificadores. Ve la nota siguiente.
phone	Cadena	Un número de teléfono según lo indicado por tus usuarios, en formato E.164 (por ejemplo, +442071838750). Consulta Números de teléfono de usuario para orientación sobre el formato.	No, y solo puede usarse en ausencia de otros identificadores. Ve la nota siguiente.
name	Cadena	Un evento personalizado de tus usuarios.	Sí
time	Cadena	La hora del evento. Puede pasarse en uno de los siguientes formatos ISO-8601: “AAAA-MM-DD” “AAAA-MM-DDTHH:MM:SS+00:00” “AAAA-MM-DDTHH:MM:SSZ” “AAAA-MM-DDTHH:MM:SS” (por ejemplo, 2019-11-20T18:38:57)	Sí
<property_name>	Múltiple	Una propiedad de evento asociada con un evento recomendado. Un ejemplo es order_id.	Condicional. Ver Esquemas de eventos recomendados.

Requisitos de formato para eventos recomendados

Al importar eventos recomendados usando CSV, debes formatear tu archivo de acuerdo con los siguientes requisitos para una importación de datos exitosa. Para reducir errores de mapeo, incluye solo un tipo de evento por archivo.

Comprender el formato de eventos recomendados

Es importante formatear tu CSV de eventos recomendados con encabezados adecuados para que cada propiedad identificada se mapee a la propiedad de evento correcta. Si el formato es incorrecto, los eventos pueden descartarse o la importación puede fallar, especialmente cuando se incluyen múltiples tipos de eventos en un archivo.

Agrupaciones de eventos recomendados para propiedades anidadas

Los eventos recomendados tienen un esquema definido. Por ejemplo, order_placed tiene una propiedad requerida products que es un arreglo de objetos, y cada objeto anidado tiene sus propias propiedades anidadas requeridas.

El CSV de eventos recomendados admite agrupar múltiples filas que tienen el mismo identificador, nombre de evento y hora, siempre que las filas no estén separadas en el archivo. Esto te permite usar filas secuenciales para completar valores de propiedades anidadas. Al formatear tu archivo, completa las filas adicionales solo con el identificador, nombre de evento, hora y propiedades anidadas relevantes. No necesitas repetir los valores de propiedades de nivel superior en cada fila.

Metadatos y propiedades opcionales

Aunque los eventos recomendados tienen un esquema definido (consulta Esquemas de eventos recomendados), puedes mapear e importar propiedades opcionales como image_url para la propiedad de arreglo products. También puedes pasar propiedades adicionales a la propiedad de nivel superior metadata, a la propiedad anidada metadata del nivel de products, o al arreglo de propiedad discounts. Después de mapear todas las propiedades requeridas, haz clic en Cargar propiedades opcionales para cargar y mapear propiedades adicionales.

Ejemplo de estructura CSV

El siguiente ejemplo muestra el formato correcto para importar eventos recomendados con propiedades requeridas y propiedades anidadas. Este ejemplo muestra tres usuarios, cada uno realizando un pedido con dos productos distintos.

En este ejemplo:

• Los pedidos se identifican y agrupan por el mismo identificador, nombre de evento y hora, con todas las filas relevantes en secuencia.
• Los usuarios user_101, user_102 y user_103 activaron cada uno el evento order_placed con las propiedades requeridas y propiedades anidadas.
• Los pedidos de los usuarios user_101 y user_102 incluyen metadatos que se añaden al arreglo de propiedad discounts.

Importante

Cuando una fila contiene datos para un evento específico, solo completa las columnas para las propiedades de ese evento. Deja las columnas de otros eventos en blanco.

Paso 4: Cargar tu archivo

Para cargar tu archivo, selecciona Atributos, Eventos personalizados o Eventos recomendados en el desplegable Importar usuarios, haz clic en Examinar archivos y sube tu CSV. Braze muestra una vista previa de las primeras filas y un resumen de los campos detectados.

Para archivos grandes (hasta 500 MB para atributos predeterminados y atributos personalizados, o 50 MB para eventos personalizados), el panel puede parecer temporalmente sin respuesta mientras el archivo se carga y Braze calcula la importación. Estas cargas y cálculos pueden tardar más en completarse que con archivos más pequeños. Deja que este paso se complete. Para más contexto sobre los límites de archivo y los tiempos, consulta Construir tu CSV.

Nota

La vista previa del archivo muestra solo las primeras filas de tu archivo. Para verificar cada fila antes de importar, usa la validación de archivos.

Importante

Las importaciones de usuarios CSV están disponibles para descargar desde el panel durante 14 días después de la carga. Transcurrido ese período, el archivo se elimina del almacenamiento y ya no es accesible.

Paso 5: Mapear tus campos

Después de la vista previa, puedes mapear los encabezados de tu CSV a atributos, eventos o propiedades de eventos de Braze. Braze mapea automáticamente los campos de tu archivo CSV a atributos, eventos o propiedades de eventos con nombres idénticos, y crea nuevos campos cuando sea necesario. También tendrás la flexibilidad de ajustar manualmente las sugerencias o seleccionar diferentes atributos, eventos o propiedades.

Para las propiedades de eventos, Braze detecta las propiedades y las asocia con los eventos relevantes en función de si una celda CSV contiene un valor no nulo, o a partir de encabezados que usan el formato heredado de notación de puntos (como <event name>.properties.<property name>).

Estados de mapeo

La columna de estado de mapeo indica la acción que ocurre cuando se importa tu archivo CSV y puede ser cualquiera de los siguientes.

Editar nuevos atributos, eventos y propiedades

Cuando un atributo, evento o propiedad de evento coincidente no existe en tu espacio de trabajo, Braze intenta crear un nuevo atributo, evento o propiedad durante la importación usando el nombre del campo CSV y el tipo de datos detectado. Puedes editar este nuevo campo antes de la importación seleccionando el botón Editar nuevo atributo, Editar nuevo evento o Editar nueva propiedad junto al estado de mapeo.

Nota

No puedes avanzar más allá del paso de mapeo hasta que se mapee un identificador. Braze mapea automáticamente un identificador cuando es posible. Para eventos personalizados, también debes mapear las columnas name y time. Consulta la sección Campos requeridos para más información.

Paso 6: Elegir preferencias de segmentación

Después del mapeo, puedes elegir entre las siguientes preferencias de segmentación en la página de configuración de importación. Si no necesitas crear un nuevo filtro de segmentación o Segment a partir de tu importación, selecciona No hacer que esta lista esté disponible como filtro de segmentación.

Paso 7: Validar tu archivo (opcional)

Antes de iniciar tu importación, puedes ejecutar la validación de archivos para verificar cada fila en busca de errores y advertencias. Para validar tu archivo, selecciona Validar archivo antes de importar en la página de configuración de importación y luego selecciona Siguiente.

La validación puede tardar hasta 2 minutos para archivos del tamaño máximo permitido. Mientras se ejecuta la validación, puedes seleccionar Omitir validación para saltarla y continuar inmediatamente.

Resultados de la validación

Cuando la validación se completa, aparece uno de los siguientes resultados.

Comprender el informe de errores

El informe de errores es un archivo CSV que contiene cada fila señalada junto con sus datos originales y una descripción del problema.

Después de revisar el informe, puedes corregir los problemas en tu archivo original y volver a cargarlo, o continuar con la importación y aceptar los resultados parciales.

Paso 8: Iniciar tu importación CSV

Cuando estés listo, selecciona Iniciar importación. Puedes seguir el progreso actual en la página Importar usuarios, que se actualiza automáticamente cada 5 segundos. El procesamiento puede tardar desde unos minutos hasta varias horas dependiendo del tamaño de tu CSV. Durante este tiempo, el panel puede parecer sin respuesta o responder lentamente, pero la importación sigue en ejecución.

Nota

Puedes importar más de un CSV al mismo tiempo. Las importaciones CSV se ejecutan de forma concurrente, por lo que no se garantiza que el orden de las actualizaciones sea secuencial. Si necesitas que las importaciones CSV se ejecuten una tras otra, espera a que una importación CSV haya finalizado antes de cargar una segunda.

Estados de importación

Después de iniciar tu importación, puedes verificar su estado en la página Importar usuarios.

El informe de errores posterior a la importación incluye filas que fallaron por razones que la validación no cubre, como cuando un usuario no existe en Braze.

Importante

Los archivos CSV cargados previamente están disponibles para descargar desde la página Importar usuarios durante 14 días después de la fecha de carga. Después de 14 días, el archivo se elimina permanentemente y ya no se puede acceder a él.

Consideraciones sobre puntos de datos

Cada dato de cliente importado desde un archivo CSV sobrescribe el valor existente en los perfiles de usuario y registra un punto de datos, excepto los ID externos y los valores en blanco. Si tienes alguna pregunta sobre los matices de los puntos de datos de Braze, tu director de cuentas de Braze puede responderlas.

Importante

Configurar language o country en un usuario a través de una importación de CSV o API evita que Braze capture automáticamente esta información a través del SDK.

Solución de problemas

Si usaste la validación de archivos, comienza con el informe de errores, ya que incluye el problema específico de cada fila marcada y una descripción de cómo solucionarlo. Para las filas que fallaron durante la importación en lugar de la validación, descarga el informe de errores pasando el cursor sobre la fila y seleccionando el botón en la página Importar usuarios.

Para solucionar problemas de importación CSV, revisa estos problemas comunes en las siguientes secciones.

La importación CSV se queda en Calculating

En Importar usuarios, Calculating significa que Braze aún está preparando el archivo para su procesamiento. Durante este paso, el recuento de filas puede mostrarse como 0 / Calculating hasta que la preparación finalice.

Si tu importación parece estar atascada en Calculating:

• Deja que la importación continúe. No canceles ni vuelvas a subir el archivo a menos que soporte de Braze te lo indique.
• Confirma que tu archivo esté dentro de los límites admitidos en Construir tu CSV.
• Revisa el Paso 4: Subir tu archivo y el Paso 8: Iniciar tu importación CSV para conocer el comportamiento esperado del panel y los tiempos de procesamiento.
• Contacta a soporte de Braze si Calculating dura mucho más de lo esperado para el tamaño de tu archivo después de haber confirmado esas verificaciones.

Usar correo electrónico como external_id

Braze no recomienda usar una dirección de correo electrónico como external_id. Si usas correo electrónico como external_id, incluye tanto la columna external_id como la columna email en tu CSV para que los usuarios sigan siendo segmentables en el canal de correo electrónico. Usa una coma (,) como delimitador de columna, no dos puntos (:).

Caracteres de comillas en valores de external_id

Si una celda de external_id contiene comillas dobles, escápalas duplicando el carácter (""), como se describe en Comillas dobles sin escapar o desbalanceadas. La importación CSV no usa escape con barra invertida.

La importación CSV no está disponible como filtro de Segment

Solo puedes usar una importación CSV como filtro de Segment si habilitaste una preferencia de segmentación durante la carga.

Para verificar si la disponibilidad de segmentación está habilitada para una importación existente:

1. En la página Importar usuarios, encuentra tu importación CSV.
2. Verifica si aparece Ir a Segment para esa importación.
3. Si aparece Ir a Segment, tu CSV está disponible en el filtro de Segment Updated/Imported from CSV.
4. Si Ir a Segment no aparece, la disponibilidad de segmentación no fue habilitada para esa importación.

No puedes habilitar la disponibilidad de segmentación después de que se completa una carga CSV. Para usar ese CSV como filtro de Segment, vuelve a subir el archivo y, en el Paso 6: Elegir preferencias de segmentación, selecciona Crear filtro de segmentación o Crear filtro de segmentación y añadir a un nuevo Segment.

Si tu objetivo es crear un Segment sin actualizar datos de perfil, sube un CSV que incluya solo columnas de identificadores (por ejemplo, columnas de external_id o identificadores de alias), y luego selecciona Crear filtro de segmentación y añadir a un nuevo Segment.

Problemas de formato de archivo

Fila malformada

Si tu carga se completó con errores, puede haber una fila malformada en tu archivo CSV.

Para importar datos correctamente, debe haber una fila de encabezado. Cada fila debe tener la misma cantidad de celdas que la fila de encabezado. Las filas con más o menos valores que la fila de encabezado serán excluidas de la importación. Las comas dentro de un valor se interpretarán como un separador y pueden provocar este error.

Además, todos los datos deben estar codificados en UTF-8. Si el archivo se guarda con una codificación heredada (por ejemplo, algunos valores predeterminados de Excel), los caracteres especiales y las URL en las celdas pueden corromperse y aparecer como signos de interrogación (?) en Braze o en los mensajes enviados.

Si tu archivo CSV tiene filas en blanco e importa menos filas que el total de líneas en el archivo CSV, esto podría no indicar un problema con la importación, ya que las filas en blanco no necesitarían ser importadas. Verifica el número de líneas que se importaron correctamente y asegúrate de que coincida con el número de usuarios que estás intentando importar.

Fila faltante

Hay algunas razones por las que el número de usuarios importados podría no coincidir con el total de filas en tu archivo CSV:

Entrecomillado de cadenas

Los valores encapsulados en comillas simples ('') o dobles ("") se leerán como cadenas en la importación.

Fechas con formato incorrecto

Las fechas que no estén en formato ISO-8601 no se leerán como datetimes en la importación.

Problemas de estructura de datos

Direcciones de correo electrónico no válidas

Si tu carga se completó con errores, puede haber una o más direcciones de correo electrónico cifradas no válidas. Confirma que todas las direcciones de correo electrónico estén cifradas correctamente antes de importarlas en Braze.

• Al actualizar o importar direcciones de correo electrónico en Braze, usa el valor de correo electrónico con hash dondequiera que se incluya un correo electrónico. Estos valores de correo electrónico con hash son proporcionados por tu equipo interno.
• Al crear un nuevo usuario, debes agregar email_encrypted con el valor de correo electrónico cifrado del usuario. De lo contrario, Braze no creará al usuario. De manera similar, si estás agregando una dirección de correo electrónico a un usuario existente que no tiene correo electrónico, debes agregar email_encrypted. De lo contrario, Braze no actualizará al usuario.

Datos importados como atributo personalizado

Si un dato de usuario predeterminado (como email o first_name) se importa como atributo personalizado, verifica las mayúsculas y el espaciado de tu archivo CSV. Por ejemplo, First_name se importa como atributo personalizado, mientras que first_name se importa correctamente en el campo “nombre” del perfil de un usuario.

Cambiar el tipo de datos de un atributo personalizado

Si necesitas cambiar el tipo de datos de un atributo personalizado existente (por ejemplo, de cadena a booleano), actualiza el tipo de datos en la página Atributos personalizados en el panel antes de importar tu CSV. Si el tipo de datos en tu CSV no coincide con el tipo de datos actualmente definido del atributo, la importación fallará con un error.

Múltiples tipos de datos

Braze espera que cada valor en una columna sea del mismo tipo de datos. Los valores que no coincidan con el tipo de datos de su atributo causarán errores en la segmentación.

Además, iniciar un atributo numérico con cero causará problemas porque los números que comienzan con ceros se consideran cadenas. Cuando Braze convierte esa cadena, puede tratarla como un valor octal (que usa dígitos del cero al siete), lo que significa que se convierte a su valor decimal correspondiente. Por ejemplo, si el valor en el archivo CSV es 0130, el perfil de Braze mostrará 88. Para evitar este problema, usa atributos con tipos de datos de cadena. Sin embargo, este tipo de datos no está disponible en la comparación numérica de segmentación.

Tipos de atributos predeterminados

Algunos atributos predeterminados pueden aceptar solo ciertos valores como válidos para actualizaciones de usuarios. Para orientación, consulta Construir tu CSV.

Los espacios al final y las diferencias en mayúsculas pueden hacer que un valor se interprete como no válido. Por ejemplo, en el siguiente archivo CSV, solo el usuario de la primera fila (brazetest1) tiene sus estados de correo electrónico y push actualizados con éxito porque los valores aceptados son unsubscribed, subscribed y 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” no funciona

Hay varias razones por las que el botón Select CSV File puede no funcionar: