> ## 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

> Sincronize eventos personalizados de arquivos CSV do Amazon S3 para o OneSignal para acionar Journeys automatizadas e campanhas de mensagens personalizadas com base no comportamento do usuário.

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"

## Visão geral

A integração OneSignal + Amazon S3 permite a sincronização automática de eventos personalizados de arquivos CSV armazenados em seu bucket S3 diretamente para a API de Eventos Personalizados do OneSignal. Isso permite que você acione Journeys automatizadas e campanhas de mensagens personalizadas com base no comportamento real do usuário armazenado em seu data warehouse.

Você pode sincronizar eventos como compras, visualizações de produtos, mudanças de assinatura ou quaisquer ações personalizadas do usuário para acionar automaticamente sequências de onboarding, campanhas de reengajamento, mensagens transacionais e promoções direcionadas através de notificações push, e-mail, mensagens in-app e SMS.

***

## Requisitos

### OneSignal

* Recurso de **Eventos Personalizados** habilitado

### Amazon S3

* **Conta AWS** com acesso ao bucket S3
* **Permissões IAM** para criar funções e políticas
* **Arquivos CSV** com dados de eventos formatados de acordo com os requisitos do OneSignal
* Arquivos delimitados por vírgula **codificados em UTF-8** com extensão `.csv`

***

## Configuração

### Prepare seus arquivos CSV de eventos

Seu bucket S3 deve conter arquivos CSV formatados corretamente com dados de eventos que o OneSignal possa processar:

**Requisitos de formato de arquivo:**

* CSV descompactado, codificado em UTF-8, delimitado por vírgula com extensão de arquivo `.csv`
* Inclua uma linha de cabeçalho (o OneSignal usará os cabeçalhos como nomes de campos de eventos)
* Represente valores nulos com a string `#N/A`
* Valores contendo vírgulas devem ser envolvidos em aspas duplas
* Valores contendo aspas duplas devem ser escapados com uma segunda aspa dupla

**Estrutura de arquivo:**
O OneSignal trata cada **caminho de pasta como uma fonte de dados exclusiva** e considera o nome do arquivo como uma versão dos dados dentro desse caminho. Ao processar eventos, o OneSignal sempre selecionará os dados mais recentes no caminho de pasta selecionado com base no timestamp.

Ao atualizar dados de eventos no S3, você pode substituir o arquivo existente ou adicionar uma versão mais recente. O OneSignal processará os novos eventos e os enviará para a API de Eventos Personalizados.

### Crie a função IAM para o OneSignal

O OneSignal usa autenticação baseada em função para se conectar ao seu bucket S3, seguindo as melhores práticas de segurança da AWS.

<Steps>
  <Step title="Crie a função IAM">
    Crie uma função IAM em sua conta AWS que forneça acesso somente leitura ao seu bucket S3 para o ID de Conta AWS do 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>
      Salve o ARN da Função retornado, pois você precisará dele para a configuração do OneSignal.
    </Info>
  </Step>

  <Step title="Conceda permissões S3">
    Conceda à sua função recém-criada acesso somente leitura ao seu 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>
      Substitua `YOUR_BUCKET_NAME` pelo nome real do seu bucket S3.
    </Warning>
  </Step>
</Steps>

### Configure a conexão S3 do OneSignal

<Steps>
  <Step title="Navegue até Fontes de Dados">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.
  </Step>

  <Step title="Selecione Amazon S3">
    Escolha **Amazon S3** da lista de integrações disponíveis.
  </Step>

  <Step title="Digite os detalhes da conexão">
    Forneça as seguintes informações:

    * **Região:** Região do seu bucket S3
    * **Nome do Bucket:** Nome do seu bucket S3
    * **ARN da Função:** O ARN da função IAM da Etapa 1
    * **Prefixo:** O caminho da pasta contendo seus arquivos CSV de eventos (opcional)
  </Step>

  <Step title="Complete o handshake de segurança">
    O OneSignal gerará um ID externo exclusivo e o exibirá na próxima tela. Atualize sua função IAM para exigir 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>
      Substitua `GENERATED_EXTERNAL_ID` pelo ID externo mostrado no dashboard do OneSignal.
    </Info>
  </Step>

  <Step title="Teste a conexão">
    Clique em **Testar Conexão** no OneSignal para verificar se a configuração está funcionando corretamente.
  </Step>
</Steps>

***

## Modos de processamento de CSV

O OneSignal oferece dois modos ao ler arquivos CSV de eventos do seu bucket S3:

### Mais Recente (Padrão)

O OneSignal processa apenas o arquivo mais recente no prefixo S3 e grupo de pastas configurado. O arquivo único é interpretado como o conjunto completo de eventos a processar. Este modo funciona bem quando:

* Um único arquivo contém todos os eventos para um período de tempo
* Novas versões de arquivos são adicionadas ao longo do tempo com dados de eventos atualizados
* Você deseja processar um lote completo de eventos de uma só vez

### Mesclar Todos

O OneSignal pega todos os arquivos no prefixo S3 e grupo de pastas configurado e os mescla em um único conjunto de dados antes de processar eventos. Este modo é útil quando:

* Seus dados de eventos foram divididos em vários arquivos
* Você deseja processar eventos de várias fontes
* Arquivos estão sendo adicionados incrementalmente com novos eventos

<Warning>
  No modo Mesclar Todos, todos os arquivos CSV devem ter exatamente os mesmos nomes de colunas e ordem.
</Warning>

***

## Mapeamento de dados de eventos

Uma vez conectado, você precisará mapear suas colunas CSV para os campos de eventos personalizados do OneSignal:

<Steps>
  <Step title="Revise os campos detectados">
    O OneSignal detectará automaticamente as colunas dos seus arquivos CSV de eventos e sugerirá mapeamentos.
  </Step>

  <Step title="Mapeie os campos de evento obrigatórios">
    Mapeie os campos obrigatórios para eventos personalizados:

    * **Nome do Evento** (obrigatório): O nome/tipo do evento
    * **ID Externo** (obrigatório): ID de Usuário Externo
    * **Timestamp do Evento** (opcional): Quando o evento ocorreu. Caso contrário, assume-se que é agora.
  </Step>

  <Step title="Configure as configurações de sincronização">
    Defina a frequência de processamento de eventos e preferências 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       |

***

## Limitações

* **Consultas SQL:** Fontes S3 não suportam consultas SQL ou transformações avançadas em dados de eventos
* **Tamanho do Arquivo:** Arquivos CSV individuais não devem exceder 1GB
* **Frequência de Atualização:** O intervalo mínimo de sincronização é de 15 minutos
* **Tipos de Arquivo:** Apenas arquivos CSV são suportados (sem JSON, Parquet, etc.)

***

## Perguntas frequentes

### O que acontece se meu arquivo CSV tiver erros de formatação?

O OneSignal ignorará linhas malformadas e fornecerá logs de erro detalhados no dashboard de integrações. Problemas comuns incluem colunas obrigatórias ausentes, formatos de timestamp inválidos e contagens de colunas inconsistentes.

### Com que frequência o OneSignal verifica novos arquivos?

O OneSignal verifica seu bucket S3 com base na frequência de sincronização configurada, com um intervalo mínimo de 15 minutos.

***

## Precisa de ajuda?

Entre em contato com nossa equipe de suporte em `support@onesignal.com` ou use o chat no aplicativo para obter assistência com a configuração da sua integração S3.