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

# Amplitude

> Integre o OneSignal com Amplitude para sincronizar coortes comportamentais, rastrear eventos de mensagens e segmentar Usuários nos canais de push, email, SMS e no aplicativo.

Integre o OneSignal com [Amplitude](https://amplitude.com) para habilitar segmentação em tempo real baseada em comportamento em push, no aplicativo, email e SMS. Esta integração no nível do aplicativo suporta três fluxos de dados:

* **Eventos de mensagens → Amplitude**: Rastreie entrega, cliques, falhas e muito mais para todos os canais.
* **Eventos personalizados → OneSignal**: Envie eventos do Amplitude para o OneSignal para acionar Jornadas ou Segmentos.
* **Coortes → OneSignal**: Sincronize coortes do Amplitude baseadas em comportamento como filtros de segmentação no OneSignal.

***

## Requisitos

* [Conta Amplitude](https://amplitude.com/pricing)
* [Plano Pago OneSignal](https://onesignal.com/pricing)
* Aplicativo OneSignal com [Usuários](./users) e ID Externo definidos.

<Warning>
  Esta integração não cria Usuários. Ela mapeia Usuários no Amplitude para Usuários existentes no OneSignal por meio de correspondência de identificadores.
</Warning>

***

## Configuração

### Adicionar Amplitude ao OneSignal (Saída)

Envia eventos de mensagens do OneSignal para seu projeto Amplitude.

1. No OneSignal, navegue até **Dados > Integrações > Catálogo** e selecione **Amplitude**.
2. Clique em **Configurações** e abra a aba **Saída**.
3. Insira seu token de API do Amplitude, selecione os eventos de mensagem que deseja enviar e clique em **Salvar**.

#### No Amplitude

1. Encontre sua chave de API do projeto e copie-cole no OneSignal.
2. Se estiver usando os servidores EU do Amplitude, marque **Enviar eventos exclusivamente para o Endpoint de Residência EU do Amplitude**. Você pode verificar isso pela sua URL do Amplitude. Se você ver `eu.amplitude.com`, então está usando os servidores EU do Amplitude.

### Adicionar OneSignal ao Amplitude (Entrada)

Nos Destinos do Amplitude, procure por **OneSignal**.

<Frame caption="Adicionar destino OneSignal no Amplitude">
  <img src="https://mintcdn.com/onesignal/TbJ7SH8gAntayRJq/images/integrations/amplitude-destination.png?fit=max&auto=format&n=TbJ7SH8gAntayRJq&q=85&s=fe7b7967e5e219556a6356915b0238fa" alt="Catálogo de destinos do Amplitude com OneSignal selecionado" width="2288" height="1168" data-path="images/integrations/amplitude-destination.png" />
</Frame>

O Amplitude fornece dois tipos de destino OneSignal no catálogo:

* **Coortes**: Sincronizar coortes do Amplitude para o OneSignal.
* **Propriedades de Usuário de Eventos**: Enviar eventos personalizados do Amplitude para o OneSignal.

<Note>
  Se você planeja usar tanto sincronização de coortes quanto eventos personalizados, adicione ambos os destinos OneSignal. Cada destino é configurado separadamente no Amplitude, então você inserirá suas credenciais OneSignal para cada um.
</Note>

### Mapeamento de User ID

O **[ID Externo](./users)** no OneSignal deve corresponder à propriedade de usuário do Amplitude que você selecionar (por exemplo, `user_id`). Verifique se essa propriedade está preenchida em ambos os sistemas — a sincronização de coortes e o rastreamento de eventos dependem de uma correspondência exata.

#### Propriedades adicionais

Você pode incluir propriedades extras que serão anexadas aos [eventos personalizados](./custom-events) no OneSignal. Isso é útil para processamento condicional de eventos.

<Check>
  Clique em **Salvar** quando terminar. Agora você deve conseguir exportar coortes e eventos personalizados do Amplitude para o OneSignal e coletar eventos de mensagens do OneSignal para o Amplitude.
</Check>

***

## Testando eventos personalizados

1. No Destino de Eventos Amplitude > OneSignal, clique no botão Testar Conexão.

<Frame caption="Amplitude > Destino de Eventos OneSignal">
  <img src="https://mintcdn.com/onesignal/yt4lRKoquAlWvRvF/images/integrations/amplitude-test-connection.png?fit=max&auto=format&n=yt4lRKoquAlWvRvF&q=85&s=8202b1ee8513456d78777425db4a7753" alt="Página de destino de Eventos do Amplitude com o botão Testar Conexão em destaque" width="1970" height="1160" data-path="images/integrations/amplitude-test-connection.png" />
</Frame>

2. Certifique-se de que o `"user_id"` no payload está definido como um ID Externo de Usuário existente em seu Aplicativo OneSignal.
3. Clique no botão **Enviar Evento de Teste**.
4. A caixa de Resposta deve permanecer vazia e você deve ver `"OneSignal has successfully received test event."`

<Frame caption="Exemplo de resposta">
  <img src="https://mintcdn.com/onesignal/yt4lRKoquAlWvRvF/images/integrations/amplitude-test-connection-response.png?fit=max&auto=format&n=yt4lRKoquAlWvRvF&q=85&s=14b5824d639a748252a36315bc491383" alt="Resposta bem-sucedida do evento de teste mostrando mensagem de confirmação" width="2438" height="1500" data-path="images/integrations/amplitude-test-connection-response.png" />
</Frame>

5. No OneSignal, navegue até **Dados > Eventos Personalizados** e verifique se o evento de teste aparece na lista.

<Frame caption="Evento Personalizado no OneSignal">
  <img src="https://mintcdn.com/onesignal/yt4lRKoquAlWvRvF/images/integrations/onesignal-custom-event.png?fit=max&auto=format&n=yt4lRKoquAlWvRvF&q=85&s=18c287884737e192fde2da0e28d65676" alt="Lista de Eventos Personalizados do OneSignal mostrando o evento de teste do Amplitude" width="2736" height="1032" data-path="images/integrations/onesignal-custom-event.png" />
</Frame>

<Warning>
  Se o teste falhar ou o evento não aparecer no OneSignal, verifique se o App ID do OneSignal e a chave de API REST estão inseridos corretamente no Amplitude, se o aplicativo está configurado para [eventos personalizados](./custom-events), e se o `"user_id"` corresponde ao ID Externo de um Usuário existente em seu Aplicativo OneSignal.
</Warning>

## Exportar coortes do Amplitude para o OneSignal

Sincronize coortes do Amplitude para o OneSignal usando o ID Externo correspondente configurado acima. Exportar **não cria Usuários** — cada Usuário já deve existir no OneSignal.

1. No Amplitude, crie uma coorte. Veja [documentação do Amplitude sobre coortes](https://amplitude.com/docs/analytics/behavioral-cohorts).
2. Clique em **Sincronizar** e escolha **OneSignal** como destino.
3. Escolha a frequência de sincronização.

<Frame caption="Configurando a cadência de sincronização de coortes do Amplitude com OneSignal">
  <img src="https://mintcdn.com/onesignal/yt4lRKoquAlWvRvF/images/integrations/amplitude-sync-cadence.png?fit=max&auto=format&n=yt4lRKoquAlWvRvF&q=85&s=9ba4b69273f73ccdd1f095c2a3ede63c" alt="Configurações de sincronização de coortes do Amplitude mostrando opções de frequência para o destino OneSignal" width="602" height="499" data-path="images/integrations/amplitude-sync-cadence.png" />
</Frame>

### Criação de Segmento OneSignal

A coorte sincronizada aparece como um **filtro de Segmento do Amplitude**. O OneSignal cria automaticamente um Segmento para a coorte se:

* Os Usuários na Coorte do Amplitude também existirem no OneSignal com ID Externo correspondente.
* Você não tiver excedido seu limite de Segmentos no OneSignal.

<Frame caption="Criando um Segmento a partir de uma Coorte do Amplitude">
  <img src="https://mintcdn.com/onesignal/jFWn5xzleD8du3j6/images/docs/526a986-Screenshot_2023-09-22_at_7.01.09_PM.png?fit=max&auto=format&n=jFWn5xzleD8du3j6&q=85&s=e5de1d6896a542a980b9840a05200586" alt="Construtor de Segmentos do OneSignal usando filtro de Coorte do Amplitude" width="1622" height="878" data-path="images/docs/526a986-Screenshot_2023-09-22_at_7.01.09_PM.png" />
</Frame>

***

## Rastrear eventos de mensagens no Amplitude

O OneSignal envia os seguintes eventos de mensagens ao Amplitude em tempo real. Selecione quais eventos enviar em **Dados > Integrações > Amplitude > Saída**.

| Tipo de Evento de Mensagem (OneSignal) | Nome do Evento de Mensagem (Amplitude)                        | Descrição do Evento                                                                         |
| -------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Push Sent                              | \[OneSignal] Push Sent                                        | Notificação push enviada com sucesso.                                                       |
| Push Received                          | \[OneSignal] Push confirmed receipt                           | Notificação push recebida com sucesso                                                       |
| Push Clicked                           | \[OneSignal] Push Clicked                                     | Notificação push tocada no dispositivo                                                      |
| Push Failed                            | \[OneSignal] Push Failed                                      | Falha ao enviar push. Verifique o relatório de mensagens com falha no OneSignal.            |
| Push Unsubscribed                      | \[OneSignal] Push Unsubscribed                                | A [Assinatura](./subscriptions) cancelou a inscrição de push.                               |
| In-App Impression                      | \[OneSignal] IAM Displayed                                    | Mensagem no aplicativo exibida com sucesso no dispositivo                                   |
| In-App Clicked                         | \[OneSignal] IAM Clicked                                      | Mensagem no aplicativo clicada no dispositivo                                               |
| In-App Page Displayed                  | \[OneSignal] IAM Page Displayed                               | Página da mensagem no aplicativo é exibida                                                  |
| Email Sent                             | \[Onesignal] Email Delivered                                  | Email enviado com sucesso                                                                   |
| Email Received                         | \[OneSignal] Email confirmed receipt                          | Email recebido pelo destinatário                                                            |
| Email Opened                           | \[OneSignal] Email Opened                                     | Email aberto pelo destinatário                                                              |
| Email Link Clicked                     | \[OneSignal] Email Clicked                                    | Link do email clicado                                                                       |
| Email Unsubscribed                     | \[OneSignal] Email Unsubscribed                               | Email com cancelamento de inscrição pelo destinatário                                       |
| Email Reported As Spam                 | \[OneSignal] Email Reported As SPAM                           | Email reportado como spam pelo destinatário                                                 |
| Email Bounced                          | \[OneSignal] Email Hard Bounced                               | Email retornado ao remetente devido a erro permanente                                       |
| Email Failed                           | \[OneSignal] Email Failed delivery                            | Não foi possível entregar o email na caixa de entrada do destinatário                       |
| Email Suppressed                       | \[OneSignal] Email Not delivering to suppressed email address | Email não entregue pois o destinatário suprimiu o endereço de email para o qual foi enviado |
| SMS Sent                               | \[OneSignal] SMS Sent                                         | SMS enviado ao destinatário                                                                 |
| SMS Failed                             | \[OneSignal] SMS Failed delivery                              | Falha ao enviar SMS                                                                         |
| SMS Delivered                          | \[OneSignal] SMS Confirmed deliveery                          | SMS entregue com sucesso                                                                    |
| SMS Undelivered                        | \[OneSignal] SMS Undelivered                                  | O SMS não pôde ser enviado.                                                                 |

### Propriedades do evento

Cada evento enviado do OneSignal para o Amplitude inclui estas propriedades:

| NOME DA PROPRIEDADE  | DESCRIÇÃO                                                   |
| -------------------- | ----------------------------------------------------------- |
| **Distinct ID**      | O external\_id associado com a mensagem                     |
| **Message ID**       | O identificador da mensagem discreta                        |
| **Message Name**     | O nome da mensagem                                          |
| **Message Title**    | O título da mensagem                                        |
| **Message Contents** | O conteúdo da mensagem                                      |
| **message\_type**    | O tipo de mensagem enviada: push, no aplicativo, email, SMS |
| **template\_id**     | O template de mensagem usado (Mensagens de API e Jornada)   |
| **subscription\_id** | O identificador OneSignal de dispositivo/email/sms          |
| **device\_type**     | O tipo de dispositivo que recebeu a mensagem                |
| **language**         | O código de idioma de dois caracteres do dispositivo        |
| **source**           | `onesignal` (é indicado como a fonte para todos os eventos) |

<Warning>
  As contagens de entrega podem diferir entre o Amplitude e o OneSignal. Veja [Por que os dados de entrega não correspondem?](#why-doesnt-delivery-data-match) para detalhes.
</Warning>

***

## Perguntas Frequentes

### Por que as contagens de minha coorte e segmento não correspondem?

1. **IDs Externos ausentes ou incompatíveis**
   Apenas usuários com um ID Externo OneSignal e ID de Usuário Amplitude correspondentes são incluídos. Esta integração não cria usuários ou assinaturas.

2. **Usuários não inscritos**
   Segmentos OneSignal exibem apenas a contagem de [Assinaturas](./subscriptions) inscritas. Assinaturas não inscritas estão disponíveis para Jornadas ou Mensagens no Aplicativo.

Por exemplo, se uma coorte do Amplitude tem 10 usuários mas o segmento OneSignal mostra 8 Assinaturas, os 2 usuários faltantes podem:

* Não existir no OneSignal ou ter um ID Externo incorreto.
* Ter assinaturas não inscritas.

Para verificar, confira a aba **Público > Usuários** no OneSignal para ver se os usuários existem e têm assinaturas ativas.

### Usuários não inscritos sincronizam do Amplitude?

Sim, mas eles são excluídos das contagens de segmento OneSignal no momento. Você ainda pode enviar mensagens para eles via Jornadas ou mensagens no aplicativo se eles tiverem outras [Assinaturas](./subscriptions) ou seu tipo de Assinatura suportar isso.

### Por que os dados de entrega não correspondem?

Um único usuário pode ter múltiplas [Assinaturas](./subscriptions) (dispositivos push, endereços de email, números de telefone). Cada Assinatura gera seu próprio evento de entrega. Por exemplo:

* 1 usuário = 2 Android + 1 iOS + 2 Web = 5 Assinaturas push
* 1 mensagem push = até 5 eventos enviados/recebidos/clicados

Use o `subscription_id` nas propriedades do evento para rastrear a fonte exata.

Para solucionar eventos ausentes:

* Certifique-se de que `OneSignal.login` seja chamado sempre que um usuário for identificado para definir o ID Externo.
* Verifique se `OneSignal.logout` não está removendo o ID Externo.
* Verifique solicitações de API ou uploads CSV que possam alterar o ID Externo.

### Como podemos enviar eventos de usuário/assinatura?

Eventos de nível de usuário e assinatura (por exemplo, permissão concedida, login/logout do usuário) não são enviados automaticamente.

O SDK OneSignal tem ouvintes de eventos que podem ser usados para rastrear esses eventos para você enviar ao Amplitude:

* Observador de Estado do Usuário: [SDK Mobile](./mobile-sdk-reference#addobserver-user-state), [SDK Web](./web-sdk-reference#addeventlistener-user-state)
* Observador de Permissão: [SDK Mobile](./mobile-sdk-reference#addpermissionobserver-push), [SDK Web](./web-sdk-reference#permissionchange)

### Por que o ID de Assinatura OneSignal é adicionado ao Amplitude como device\_id?

O Amplitude espera um `device_id` para desduplicação. O OneSignal usa `subscription_id` para isso, que é mapeado automaticamente para `device_id`.

Veja a [documentação do Amplitude](https://amplitude.com/docs/apis/analytics/http-v2#event-deduplication) para mais informações.

***

## Páginas relacionadas

<Columns cols={2}>
  <Card title="Visão geral de análises" icon="chart-line" href="./analytics-overview">
    Visão geral das análises do OneSignal, métricas de entrega e rastreamento de eventos.
  </Card>

  <Card title="Eventos personalizados" icon="bolt" href="./custom-events">
    Rastreie ações do usuário para acionar Jornadas ou potencializar análises.
  </Card>
</Columns>

***

<Info>
  Need help?

  Chat with our Support team or email `support@onesignal.com`

  Please include:

  * Details of the issue you're experiencing and steps to reproduce if available
  * Your OneSignal App ID
  * The External ID or Subscription ID if applicable
  * The URL to the message you tested in the OneSignal Dashboard if applicable
  * Any relevant [logs or error messages](/docs/en/capturing-a-debug-log)

  We're happy to help!
</Info>