Data Clean Room: trabajar con fuentes

Los datos dentro de las fuentes deben cumplir estos requisitos:

• Fecha y hora:
  • Formato: aaaa-MMM-dd hh:mm:ss (por ejemplo, 2023-APR-18 15:30:35)
  • Zona horaria: UTC
• Números: máximo 2 dígitos después del punto decimal
• Longitud de la cadena: máximo 256 caracteres
• Limitaciones de caracteres:
  • Para los nombres de campo (encabezado de columna): sin espacios ni caracteres especiales
  • Todos los demás datos: sin limitaciones (todos los caracteres son válidos)

Además de los datos compartidos para su procesamiento, las tablas de fuentes en BigQuery o Snowflake deben incluir 2 columnas adicionales, una para la fecha y otra para la versión:

• Fecha:
  • Encabezado de columna: dt
  • Tipo de columna: fecha
  • Formato de los datos: aaaa-mm-dd (por ejemplo, 2023-04-18)
  • Adicional: las tablas de BigQuery deben estar particionadas por esta columna
• Versión:
  • Encabezado de columna: v
  • Tipo de columna: cadena
  • Formato de los datos: número (por ejemplo, 1, 2, 3, 10)
  • Importante: Una nueva versión de un reporte se activa cada vez que DCR detecta un nuevo valor en esta columna. Para garantizar la integridad de tu reporte, asegúrate de rellenar la tabla de la fuente con un conjunto completo de datos cada vez que se cambie el valor de la columna.

Los archivos de fuentes almacenados en Amazon S3 o GCS deben cumplir los siguientes requisitos de nombre y formato de archivo:

• El nombre del archivo debe cumplir los requisitos de nomenclatura de DCR
• Formato CSV o GZIP
  • El archivo que se encuentra bajo la compresión GZIP debe ser un archivo CSV.
• Número de archivos de fuentes de datos por carpeta de datos:
  • CSV: máximo 1
  • GZIP: máximo 1 archivo de una sola parte. Los archivos GZIP de varias partes son compatibles cuando se denominan de la siguiente manera: filename_part01.gzip, filename_part02.gzip, etc.

1. Ve a la pestaña Fuentes de Data Clean Room.
2. Haz clic en el botón + Nueva fuente.
   Se abre la página Nueva fuente.
3. Introduce el nombre de la fuente en la esquina superior izquierda.
   • Este puede ser cualquier nombre único que te ayude a identificar la fuente en la plataforma DCR. No es necesario que coincida con el nombre del archivo.
   • ¡Importante! Asegúrate de que el nombre de la fuente sea diferente en todas las demás fuentes de tu cuenta o no podrás guardar la fuente.
   • Requisitos del nombre de la fuente:
     • Longitud: 2-80 caracteres
     • Caracteres válidos:
       • letras (A-Z, a-z)
       • números (0-9), no pueden ser el primer carácter de un nombre; 
     • Caracteres inválidos:
       • espacios
       • todos los demás símbolos o caracteres especiales

Para especificar la ubicación de la fuente:

1. Selecciona la conexión en la que se creará (o se creó) la fuente.
   • Si no hay conexiones definidas en tu cuenta, se abrirá el cuadro de diálogo Nueva conexión, pidiéndote que crees una. Sigue estas instrucciones para crearla.
   • Si tienes conexiones existentes pero deseas usar una nueva, haz clic en el botón  para abrir el cuadro de diálogo Nueva conexión. Sigue estas instrucciones para crearla.
2. Continúa con las instrucciones relevantes a continuación, en función de dónde se encuentren los datos de tu fuente.

Fuentes ubicadas en BigQuery

Para terminar de especificar la ubicación de las fuentes de BigQuery:

1. Selecciona el conjunto de datos en el que se encuentra la tabla de la fuente.
2. Selecciona la tabla en la que se encuentran los datos de la fuente.

Las listas a partir de las que haces estas selecciones contienen los conjuntos de datos y tablas disponibles, respectivamente, en el proyecto de BigQuery que especificaste al crear la conexión.

Fuentes ubicadas en Snowflake

Para terminar de especificar la ubicación de las fuentes de Snowflake:

1. Selecciona el recurso compartido que contiene los datos de la fuente.
2. Selecciona el esquema en el que se encuentra la tabla de la fuente.
3. Selecciona la tabla en la que se encuentran los datos de la fuente.

Las listas a partir de las que haces estas selecciones contienen los recursos compartidos, esquemas y tablas, respectivamente, en la cuenta de Snowflake que especificaste al crear la conexión.

Fuentes ubicadas en buckets de almacenamiento en la nube

Las ubicaciones de fuente en Amazon S3 o GCS consisten en el bucket de almacenamiento en la nube especificado por la conexión y la ruta de la carpeta subyacente desde la que DCR lee el archivo de la fuente cada vez que se actualiza. 

Una vez especificada la conexión, AppsFlyer puede generar automáticamente la ruta de la carpeta subyacente requerida como parte del proceso de creación de la fuente.

• Permitir que AppsFlyer genere las carpetas facilita el proceso. Sin embargo, puedes optar por crearlas manualmente en su lugar, de acuerdo con las instrucciones detalladas aquí.

Si AppsFlyer genera las carpetas, la única información adicional requerida es el nombre que deseas dar a la carpeta fuente. (Esta es la carpeta de nivel superior en la que se actualiza la fuente cada vez que desees utilizarla para ejecutar una nueva versión del reporte). También puedes indicar si deseas que la carpeta fuente se cree debajo de una carpeta principal, a menudo denominada input.

Para terminar de especificar la ubicación de la fuente en un bucket de almacenamiento de datos, introduce el nombre de la carpeta de la fuente.

• Por defecto, el nombre de la carpeta fuente mostrada:
  • Se basa en el nombre que le diste a la fuente. Puedes cambiar el nombre de la carpeta para adaptarlo a tus necesidades, siempre que cumpla los requisitos de nomenclatura de DCR.
  • Indica que se generará dentro de una carpeta principal denominada input. Esta carpeta sirve como carpeta principal para todas las fuentes que cargues en DCR.
    • La carpeta input no es obligatoria y puedes eliminarla o asignarle un nombre diferente, siempre y cuando cumpla con los requisitos de nomenclatura de DCR.
    • Aunque esta carpeta no es obligatoria, se considera una buena práctica disponer de una carpeta input (o una carpeta equivalente con un nombre diferente). Se recomienda aún más cuando se utiliza el mismo bucket de almacenamiento en la nube, tanto para subir archivos de datos (entrada) como para recibir reportes (salida).

Para todas las fuentes que compartas con DCR para su procesamiento, AppsFlyer necesita saber cómo se debe usar cada campo de datos con el fin de crear los reportes. La definición de la estructura de la fuente consiste en:

• Cargar los campos de la fuente
• Categorizar cada campo (columna) como uno de los siguientes tipos:
  • Identificador: Campo que identifica a un usuario único de la aplicación (ejemplos: CUID, ID de AppsFlyer, etc.)
    • El objetivo principal de los identificadores en el contexto de DCR es unir las fuentes de datos para poder cotejar los datos de nivel de usuario correspondientes.
  • Dimensión: Un atributo por el que se categoriza a los usuarios de la aplicación (algunos ejemplos pueden ser la geolocalización, la fecha de instalación, la campaña, etc.)
  • Métrica: Datos numéricos que has recopilado con respecto a un usuario de la aplicación (algunos ejemplos podrían ser los ingresos, el número de aperturas de la aplicación, el valor de vida útil (LTV), etc.)
    • Un campo de datos identificado como métrica puede contener solo valores numéricos.

Cargar los campos de la fuente

Carga los campos de la fuente siguiendo las instrucciones correspondientes a continuación:

Fuentes de almacén de datos

Para cargar los campos de una fuente ubicada en un almacén de datos (BigQuery o Snowflake), haz clic en el botón .

Fuentes de bucket de almacenamiento en la nube

Para cargar los campos de una fuente ubicada en un bucket de almacenamiento en la nube (Amazon S3 o GCS), debes subir un archivo de fuente prototipo.

Para definir la estructura de la fuente: 

• Puedes cargar una versión prototipo de la fuente desde un archivo local.
  • Si seleccionas esta opción, AppsFlyer siempre crea la ruta de la carpeta fuente automáticamente.

                                                                - o -

• Puedes subir una versión de prototipo del archivo fuente directamente desde su conexión.
  • Si seleccionas esta opción, tendrás que hacer una elección adicional:
    • Permitir que AppsFlyer cree automáticamente la estructura de carpetas fuente; o
    • Crear la estructura de carpetas de fuente manualmente

Para cargar el archivo fuente de prototipo, sigue las instrucciones de la pestaña correspondiente a continuación:

Clasificar los campos

Después de cargar los campos, AppsFlyer analiza el archivo y se muestra una lista de todos los campos de datos (columnas) en la lista Campos disponibles.

Para clasificar los campos:

1. Selecciona uno o varios campos en la lista Campos disponibles de la izquierda y utiliza los botones del centro de la pantalla para clasificarlos como identificadores, dimensiones o métricas.
   • Una vez categorizado un campo, se muestra en la lista de categorías relevantes en el lado derecho de la pantalla.
   • Puedes utilizar la barra de búsqueda para buscar campos en las listas.
   • Para eliminar un campo de una categoría a la que ha sido asignado, selecciónalo en la lista de categorías correspondiente y utiliza el botón Eliminar para devolverlo a la lista Campos disponibles.
2. Repite este proceso hasta que hayas categorizado cada campo que desees incluir en los reportes de DCR.
   • No es necesario categorizar cada campo en la lista Campos disponibles. Sin embargo, un campo debe ser categorizado para poder utilizarlo posteriormente en un reporte.
3. Si editas la fuente antes de guardarla y deseas utilizar campos de los datos de la fuente editados, haz clic en el enlace Recargar campos en la parte inferior de la lista Campos disponibles.
   • Ten en cuenta que al volver a cargar la fuente se sobrescribirán los nombres de los campos en la lista Campos disponibles. Los campos que hayas categorizado previamente permanecerán en las listas Identificadores, Dimensiones, o Métricas.
   • Si un campo previamente categorizado no se encuentra en los datos de la fuente recargados, seguirá apareciendo en la lista de categorías correspondiente, pero se marcará con un icono de error.

1. [Opcional] Haz clic en para comprobar si hay errores en el formato o la validez de los campos de la fuente.
2. Haz clic en Guardar para guardar la fuente.

   Se crea la fuente y aparece un mensaje de confirmación.

   • Si has cargado la fuente desde un archivo local, al guardar la fuente se activa la creación automática de la estructura de carpetas, y el mensaje de confirmación que aparece incluye un enlace a la carpeta de la fuente.

   La nueva fuente se muestra en la lista de todas las fuentes existentes en la pestaña Fuentes de Data Clean Room.

La estructura de las subcarpetas anidadas es la siguiente:

• Dentro de la carpeta fuente --> 1 subcarpeta para cada fecha ("carpeta de fecha")
  • Formato: dt=yyyy-mm-dd/
  • Ejemplo: dt=2022-12-15/
• Dentro de cada carpeta de fecha --> 1 subcarpeta para cada versión en esa fecha ("carpeta de versión")
  • Formato: v=n/
  • Ejemplo:v=1/
  • Nota: La carpeta de versión es necesaria aunque solo se cargue el archivo una vez al día.
• Dentro de cada carpeta de versión --> 1 subcarpeta para indicar la ubicación de los datos ("carpeta de datos")
  • Formato: data/
  • La carpeta de datos es la ubicación a la que se carga el archivo fuente.

En la mayoría de los casos, usarías llamadas a la API u otros medios programáticos disponibles para crear las carpetas de fecha/versión/datos automáticamente cada vez que se cargue el archivo fuente de datos. Para obtener más información, consulta la referencia de la API para tu servicio en la nube: AWS, GCS.

Una vez completada la carga de un archivo de fuente de datos en la carpeta de datos, se debe cargar un archivo vacío denominado _SUCCESS en la carpeta de versiones. Esto alerta a AppsFlyer de que hay un nuevo archivo disponible para procesar. En la mayoría de los casos, usarías un script de API para generar y cargar automáticamente este archivo.

¡Importante! El archivo _SUCCESS se carga en la carpeta de versión, fuera de la carpeta de datos.

El nombre del archivo _SUCCESS:

• Debe estar todo en MAYÚSCULAS
• Debe ir precedido de un guión bajo (_)
• No debe tener una extensión de archivo

Para archivos GZIP de varias partes:

• Solo debe cargarse un archivo _SUCCESS para todas las partes del archivo.
• El archivo _SUCCESS debe cargarse solo después de que se haya completado la carga de todas las partes del archivo.

Después de cargar los archivos fuente en 2 días (y de crear programáticamente carpetas de fecha/versión/datos y archivos _SUCCESS), tu estructura de bucket/carpetas podría tener este aspecto:

Para editar el nombre de la fuente:

1. Ve a la pestaña Fuentes de Data Clean Room.
2. En la lista de fuentes, pasa el cursor por encima de la fila de la fuente que desees editar.
3. Haz clic en el botón de edición que aparece a la derecha de la fila.
4. En la página Editar fuente, edita el nombre de la fuente.
5. Haz clic en el botón Guardar para guardar la fuente con el nuevo nombre o en Cancelar para deshacer los cambios.

Para editar la estructura de la fuente:

1. Ve a la pestaña Fuentes de Data Clean Room.
2. En la lista de fuentes, pasa el cursor por encima de la fila de la fuente que desees editar.
3. Haz clic en el botón de edición que aparece a la derecha de la fila.
4. En la página Editar fuente, los campos que antes estaban categorizados como identificadores, dimensiones o métricas se mostrarán en las listas de categorías correspondientes en la parte derecha de la pantalla.
5. Puedes mover un campo categorizado anteriormente a una categoría diferente sin volver a cargar los campos del archivo de fuente. Para ello:
   1. En primer lugar, selecciónalo en la lista de categorías correspondiente y utiliza el botón Eliminar para devolverlo a la lista Campos disponibles.
   2. A continuación, selecciónalo en la lista Campos disponibles y utiliza los botones del centro de la pantalla para clasificarlo como identificador, dimensión o métrica.
6. Para trabajar con campos en el archivo de fuente que aún no se han categorizado, se deben volver a cargar desde la ubicación de la fuente o desde un archivo local. Realiza esta selección haciendo clic en el enlace Volver a cargar campos en la parte inferior de la lista Campos disponibles.
7. AppsFlyer analiza el archivo y se muestra una lista de todos los campos de datos no categorizados anteriormente (columnas) en la lista Campos disponibles.
   • Los campos que se categorizaron previamente como identificadores, dimensiones o métricas seguirán apareciendo en las listas de categorías correspondientes en la parte derecha de la pantalla.
   • Si un campo previamente categorizado no se encuentra en el archivo de fuente recargado, seguirá apareciendo en la lista de categorías correspondiente, pero se marcará con un icono de error.
8. Selecciona uno o varios de los campos en la lista Campos disponibles de la izquierda y utiliza los botones del centro de la pantalla para clasificarlos como identificadores, dimensiones o métricas.
9. Una vez que hayas realizado todos los cambios necesarios, haz clic en el botón Guardar para guardar la fuente con la estructura actualizada o en Cancelar para deshacer los cambios.

1. Ve a la pestaña Fuentes de Data Clean Room.
2. En la lista de fuentes, pasa el cursor por encima de la fila de la fuente que desees eliminar.
3. Haz clic en el botón de eliminación  que aparece a la derecha de la fila.
4. En el cuadro de diálogo, confirma que deseas eliminar la fuente.
   • No puedes eliminar una fuente que esté siendo utilizada por un reporte. Si este es el caso, un mensaje enumerará los reportes en los que se está utilizando la fuente. Para eliminar la fuente, puedes:
     • Eliminar los reportes en los que se está utilizando; o
     • Eliminar los campos de fuente de las definiciones de los reportes en los que se utilizan.

En general, es más fácil permitir que AppsFlyer genere automáticamente la estructura de carpetas requerida como parte del proceso de creación de la fuente. Sin embargo, si deseas crear estas carpetas manualmente, puedes hacerlo de la siguiente manera.

Crear una carpeta de claves de DCR

Para garantizar la máxima seguridad, la carpeta directamente debajo del bucket (la "carpeta de clave DCR") debe tener el nombre de la clave DCR alfanumérica de 8 caracteres asignada a tu cuenta (por ejemplo, 01bcc5fb). Ten en cuenta que esta es diferente de cualquier otra contraseña o clave asociada a tu cuenta de AppsFlyer.

Por lo general, la carpeta de claves DCR se crea manualmente utilizando la interfaz del servicio en la nube seleccionado.

Para obtener la clave de DCR de tu cuenta, haz clic en el botón de clave de DCR en la parte superior de la página principal de DCR.

Después de crear la carpeta de clave DCR, tu estructura de bucket/carpetas se verá así:

Carpeta de entrada de nivel superior

Aunque no es obligatorio, la práctica recomendada es crear una carpeta de entrada de nivel superior directamente debajo de la carpeta de claves DCR. Esta carpeta estará dedicada a los archivos que subas a DCR.

Por lo general, la carpeta de entrada de nivel superior se crea manualmente utilizando la interfaz del servicio en la nube seleccionado.

• Esta práctica es aún más recomendable cuando se utiliza el mismo bucket tanto para cargar archivos de datos (entrada) como para recibir reportes (salida).
• Puedes nombrar esta carpeta como quieras, siempre y cuando cumpla con los requisitos de denominación de DCR. Para facilitar su identificación, suele denominarse input/.

Después de crear la carpeta de entrada de nivel superior, tu estructura de bucket/carpetas se verá así:

Carpeta de segundo nivel para cada fuente de datos

Puedes cargar regularmente diferentes archivos de origen de datos en DCR para su procesamiento. A cada una de estas fuentes de datos se le debe asignar una carpeta separada ("carpetas de origen de datos").

Por ejemplo, si planeas cargar 2 archivos a DCR para procesarlos todos los días: BI-data.csv y CRM-data.gzip, asignarías una carpeta a cada una de estas fuentes de datos. Puedes denominar estas carpetas BI-data/ y CRM-data/.

Por lo general, las carpetas de origen de datos se crean manualmente utilizando la interfaz del servicio en la nube seleccionado.

Después de crear 2 carpetas de origen de datos, tu estructura de bucket/carpetas se verá así:

Debajo de cada carpeta de fuente de datos, se deben crear subcarpetas anidadas por fecha y versión cada vez que se actualice la fuente.