> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Amazon S3

> Sincroniza eventos personalizados desde archivos CSV de Amazon S3 a OneSignal para activar Journeys automatizados y campañas de mensajería personalizadas basadas en el comportamiento del usuario.

export const PLATFORM_0 = "S3 CSV"

export const DATA_TYPE_0 = "file columns"

export const COLUMN_HEADER_0 = "CSV Column Example"

export const PROPERTIES_DESCRIPTION_0 = "Event properties as JSON string"

## Descripción general

La integración OneSignal + Amazon S3 habilita la sincronización automática de eventos personalizados desde archivos CSV almacenados en tu bucket S3 directamente al API de Eventos Personalizados de OneSignal. Esto te permite activar Journeys automatizados y campañas de mensajería personalizadas basadas en el comportamiento real del usuario almacenado en tu almacén de datos.

Puedes sincronizar eventos como compras, vistas de productos, cambios de suscripción o cualquier acción personalizada del usuario para activar automáticamente secuencias de onboarding, campañas de reenganche, mensajes transaccionales y promociones dirigidas a través de notificaciones push, email, mensajes in-app y SMS.

***

## Requisitos

### OneSignal

* Función **Eventos Personalizados** habilitada

### Amazon S3

* **Cuenta AWS** con acceso a bucket S3
* **Permisos IAM** para crear roles y políticas
* **Archivos CSV** con datos de eventos formateados según los requisitos de OneSignal
* Archivos delimitados por comas **codificados UTF-8** con extensión `.csv`

***

## Configuración

### Prepara tus archivos CSV de eventos

Tu bucket S3 debe contener archivos CSV correctamente formateados con datos de eventos que OneSignal pueda procesar:

**Requisitos de formato de archivo:**

* CSV sin comprimir, codificado UTF-8, delimitado por comas con extensión de archivo `.csv`
* Incluye una fila de encabezado (OneSignal usará los encabezados como nombres de campos de evento)
* Representa valores nulos con la cadena `#N/A`
* Los valores que contienen comas deben estar envueltos en comillas dobles
* Los valores que contienen comillas dobles deben escaparse con una segunda comilla doble

**Estructura de archivo:**
OneSignal trata cada **ruta de carpeta como una fuente de datos única** y considera que el nombre del archivo es una versión de los datos dentro de esa ruta. Al procesar eventos, OneSignal siempre seleccionará los datos más nuevos en la ruta de carpeta seleccionada basándose en la marca de tiempo.

Al actualizar datos de eventos en S3, puedes reemplazar el archivo existente o agregar una versión más nueva. OneSignal procesará los nuevos eventos y los enviará al API de Eventos Personalizados.

### Crear rol IAM para OneSignal

OneSignal usa autenticación basada en roles para conectarse a tu bucket S3, siguiendo las mejores prácticas de seguridad de AWS.

<Steps>
  <Step title="Crear el rol IAM">
    Crea un rol IAM en tu cuenta AWS que proporcione acceso de solo lectura a tu bucket S3 para el ID de Cuenta AWS de OneSignal (`341876425553`):

    ```bash theme={null}
    aws iam create-role \
      --role-name OneSignalS3DataImport \
      --assume-role-policy-document '{
        "Version": "2012-10-17",
        "Statement": [{
          "Effect": "Allow",
          "Principal": {"AWS": "arn:aws:iam::341876425553:root"},
          "Action": "sts:AssumeRole"
        }]
      }'
    ```

    <Info>
      Guarda el Role ARN devuelto ya que lo necesitarás para la configuración de OneSignal.
    </Info>
  </Step>

  <Step title="Otorgar permisos S3">
    Otorga a tu rol recién creado acceso de solo lectura a tu bucket S3:

    ```bash theme={null}
    aws iam put-role-policy \
      --role-name OneSignalS3DataImport \
      --policy-name OneSignalS3Access \
      --policy-document '{
        "Version": "2012-10-17",
        "Statement": [{
          "Effect": "Allow",
          "Action": [
            "s3:ListBucket",
            "s3:GetObject",
            "s3:GetObjectVersion",
            "s3:GetBucketLocation"
          ],
          "Resource": [
            "arn:aws:s3:::YOUR_BUCKET_NAME",
            "arn:aws:s3:::YOUR_BUCKET_NAME/*"
          ]
        }]
      }'
    ```

    <Warning>
      Reemplaza `YOUR_BUCKET_NAME` con el nombre real de tu bucket S3.
    </Warning>
  </Step>
</Steps>

### Configurar conexión S3 de OneSignal

<Steps>
  <Step title="Navegar a Fuentes de Datos">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.
  </Step>

  <Step title="Seleccionar Amazon S3">
    Elige **Amazon S3** de la lista de integraciones disponibles.
  </Step>

  <Step title="Ingresar detalles de conexión">
    Proporciona la siguiente información:

    * **Region:** La región de tu bucket S3
    * **Bucket Name:** El nombre de tu bucket S3
    * **Role ARN:** El ARN del rol IAM del Paso 1
    * **Prefix:** La ruta de carpeta que contiene tus archivos CSV de eventos (opcional)
  </Step>

  <Step title="Completar el apretón de manos de seguridad">
    OneSignal generará un ID externo único y lo mostrará en la siguiente pantalla. Actualiza tu rol IAM para requerir este ID externo:

    ```bash theme={null}
    aws iam update-assume-role-policy \
      --role-name OneSignalS3DataImport \
      --policy-document '{
        "Version": "2012-10-17",
        "Statement": [{
          "Effect": "Allow",
          "Principal": {"AWS": "arn:aws:iam::341876425553:root"},
          "Action": "sts:AssumeRole",
          "Condition": {"StringEquals": {"sts:ExternalId": "GENERATED_EXTERNAL_ID"}}
        }]
      }'
    ```

    <Info>
      Reemplaza `GENERATED_EXTERNAL_ID` con el ID externo mostrado en el dashboard de OneSignal.
    </Info>
  </Step>

  <Step title="Probar la conexión">
    Haz clic en **Test Connection** en OneSignal para verificar que la configuración funcione correctamente.
  </Step>
</Steps>

***

## Modos de procesamiento CSV

OneSignal soporta dos modos al leer archivos CSV de eventos desde tu bucket S3:

### Más reciente (Predeterminado)

OneSignal procesa solo el archivo más reciente en el prefijo S3 configurado y grupo de carpetas. El archivo único se interpreta como el conjunto completo de eventos a procesar. Este modo funciona bien cuando:

* Un solo archivo contiene todos los eventos para un período de tiempo
* Se agregan nuevas versiones de archivos con el tiempo con datos de eventos actualizados
* Quieres procesar un lote completo de eventos a la vez

### Fusionar todo

OneSignal toma cada archivo en el prefijo S3 configurado y grupo de carpetas y los fusiona en un solo conjunto de datos antes de procesar eventos. Este modo es útil cuando:

* Tus datos de eventos se han dividido en múltiples archivos
* Quieres procesar eventos de múltiples fuentes
* Los archivos se agregan incrementalmente con nuevos eventos

<Warning>
  En modo Fusionar todo, todos los archivos CSV deben tener exactamente los mismos nombres de columna y orden.
</Warning>

***

## Mapeo de datos de eventos

Una vez conectado, necesitarás mapear tus columnas CSV a campos de eventos personalizados de OneSignal:

<Steps>
  <Step title="Revisar campos detectados">
    OneSignal detectará automáticamente columnas de tus archivos CSV de eventos y sugerirá mapeos.
  </Step>

  <Step title="Mapear campos de eventos requeridos">
    Mapea los campos requeridos para eventos personalizados:

    * **Event Name** (requerido): El nombre/tipo del evento
    * **External ID** (requerido): ID de Usuario Externo
    * **Event Timestamp** (opcional): Cuándo ocurrió el evento. De lo contrario, se asume que es ahora.
  </Step>

  <Step title="Configurar ajustes de sincronización">
    Establece tu frecuencia de procesamiento de eventos y preferencias de entrega.
  </Step>
</Steps>

***

### Event data mapping

Map your {PLATFORM_0} {DATA_TYPE_0} to OneSignal's custom events format:

| OneSignal Field | {COLUMN_HEADER_0} | Description                | Required |
| --------------- | ----------------- | -------------------------- | -------- |
| `name`          | `event_name`      | Event identifier           | Yes      |
| `external_id`   | `user_id`         | User identifier            | Yes      |
| `timestamp`     | `event_timestamp` | When event occurred        | No       |
| `properties`    | `event_data`      | {PROPERTIES_DESCRIPTION_0} | No       |

***

## Limitaciones

* **Consultas SQL:** Las fuentes S3 no soportan consultas SQL o transformaciones avanzadas en datos de eventos
* **Tamaño de archivo:** Los archivos CSV individuales no deben exceder 1GB
* **Frecuencia de actualización:** El intervalo de sincronización mínimo es de 15 minutos
* **Tipos de archivo:** Solo se soportan archivos CSV (no JSON, Parquet, etc.)

***

## FAQ

### ¿Qué sucede si mi archivo CSV tiene errores de formato?

OneSignal omitirá las filas mal formadas y proporcionará registros de error detallados en el dashboard de integraciones. Los problemas comunes incluyen columnas requeridas faltantes, formatos de marca de tiempo inválidos y conteos de columnas inconsistentes.

### ¿Con qué frecuencia verifica OneSignal archivos nuevos?

OneSignal verifica tu bucket S3 basándose en tu frecuencia de sincronización configurada, con un intervalo mínimo de 15 minutos.

***

## ¿Necesitas ayuda?

Contacta a nuestro equipo de soporte en `support@onesignal.com` o usa el chat en la app para asistencia con tu configuración de integración S3.