# Integração com o Piano Analytics
O [Piano Analytics](https://piano.io/product/analytics/) é uma ferramenta que ajuda as empresas a entender como as pessoas interagem com seus sites e aplicativos. Ele coleta dados sobre o comportamento do usuário e fornece insights por meio de relatórios e visualizações. Essas informações ajudam as empresas a tomar melhores decisões sobre como aprimorar seus produtos digitais e esforços de marketing.
A integração do [Piano Analytics](https://piano.io/product/analytics/) com o Pushwoosh permite obter insights detalhados sobre o comportamento do usuário para criar segmentos precisos e enviar notificações push, e-mails e mensagens no aplicativo altamente direcionados para os usuários certos, no momento certo.
## Visão geral da integração
### Tipo de integração
* **Destino**: Os dados são enviados do Piano Analytics para o Pushwoosh.
* **Fonte**: Os dados são enviados do Pushwoosh para o Piano Analytics.
### Pré-requisitos
Contas pagas tanto no Pushwoosh quanto no Piano Analytics
### Glossário (mapeamento de nomes de entidades, se forem diferentes)
Ao integrar o Pushwoosh e o Piano Analytics, certos nomes de entidades podem variar entre as duas plataformas. Aqui estão os mapeamentos entre o Pushwoosh e o Piano Analytics:
| Pushwoosh | Piano Analytics |
| --- | --- |
| UserID/hwid | visitorID |
| PostEvent.EventName | PianoEvent.Name |
| PostEvent.UserID | PianoEvent.PushwooshID |
| PostEvent.CampaignID | PianoEvent.SrcMedium |
| PostEvent.PlatformID | PianoEvent.DeviceType |
### Entidades sincronizadas
**Fonte**
* Eventos
* Estatísticas de Push
* Tags (como atributos de evento)
**Destino**
* Segmentos
### Casos de uso
**Análise unificada**
Combine dados de engajamento do Pushwoosh com o Piano Analytics para obter insights abrangentes sobre o usuário. Isso permite que você tenha uma visão holística do comportamento e das interações do usuário em múltiplos pontos de contato.
**Segmentação**
Crie segmentos de usuários direcionados no Pushwoosh com base nos dados do Piano Analytics. Use essa segmentação aprimorada para entregar campanhas de marketing personalizadas e eficazes.
**Monitoramento de desempenho**
Acompanhe a eficácia da campanha e a interação do usuário entre plataformas.
### Como funciona a integração?
##### Visão geral do fluxo
1. **Configuração**: Configure as definições de integração nas contas do Pushwoosh e do Piano Analytics.
2. **Mapeamento de eventos**: Mapeie eventos do Pushwoosh para eventos do Piano (por exemplo, PostEvent.EventName para PianoEvent.Name).
3. **Transferência de dados**: O Pushwoosh envia eventos (Post Events e Tracking Log Events) para o Piano Analytics.
4. **Importação de segmentos**: O Piano Analytics envia dados de segmentos para o Pushwoosh para segmentação de público.
##### Fluxo técnico
1. **Post Events**
* O Pushwoosh envia dados de eventos para o Piano Analytics.
* Os atributos são mapeados da seguinte forma:
* UserID (Pushwoosh) > PushwooshID (Piano)
* CampaignID (Pushwoosh) > SrcMedium (Piano)
* PlatformID (Pushwoosh) > DeviceType (Piano)
2. **Tracking Log Events**:
* O Pushwoosh envia dados de rastreamento (por exemplo, Push Enviado, Push Entregue) para o Piano Analytics.
* Esses dados enriquecem o Piano Analytics com métricas de entrega e engajamento.
3. **Integração do Piano VisitorID**:
* Opcionalmente, integre o Piano VisitorID com o Pushwoosh para análises unificadas em todos os SDKs.
## Configurando a integração
Para configurar a integração, vá para **Settings > 3rd Party Integrations** na sua conta Pushwoosh e localize **Piano**. Clique em **Configure**.
Na janela que se abre, forneça as seguintes credenciais:
1. Site ID
Para localizar seu Site ID, faça login na sua conta do Piano e vá para **Analytics > Data Collection Portal > Dashboard.** Encontre o site relevante e copie seu ID.
2. Collection Domain
Para encontrar o Collection Domain, navegue até **Tagging > Collection Domains**. Copie o ID do Collection Domain. Certifique-se de inserir o domínio de coleta no formato **\*\*\*\*.pa-cd.com** sem o prefixo **https://.**
3. Chaves de Acesso e Secreta da API do Piano
Para obter as chaves:
* Na sua conta do Piano, clique em **See profile** abaixo do nome da sua conta.
* Navegue até a aba **API Keys** e crie uma nova chave com um nome e descrição claros. Em seguida, clique em **OK**.
* Na janela que se abre, copie sua **Access Key** e a **Secret Key**.
* No campo **API key** no Pushwoosh, insira tanto a **Access Key** quanto a **Secret Key**, separadas por um underscore. Por exemplo: **accesskey_secretkey**.
### Criando eventos no Piano para corresponder aos eventos do Pushwoosh
Para rastrear eventos enviados do Pushwoosh no Piano, você precisa criar os eventos correspondentes manualmente dentro do Piano.
Veja como fazer isso na sua conta do Piano:
1. Vá para **Settings > Data management > Data model**.
2. Selecione **Events** e clique no ícone de mais para criar um novo evento.
3. Na janela que se abre, forneça o nome e a descrição do evento, por exemplo, _**"pw\_siteopened"**_.
4. No campo **Type**, selecione **On-site**.
5. No campo **Categories**, selecione **Events**.
6. Clique em **Save**.
### Definindo o fuso horário do seu site no Piano
Definir o fuso horário correto para o seu site no Piano é crucial para o rastreamento e análise de dados precisos. A melhor prática é corresponder o fuso horário com o local onde você está enviando eventos e realizando análises. Isso elimina discrepâncias de tempo.
Para editar o fuso horário no Piano, vá para o **Dashboard** e clique na linha que contém as informações do seu site. Na janela pop-up, clique em **Edit** e selecione o fuso horário desejado. Em seguida, clique em **Save**.
### Criando uma propriedade para identificar eventos enviados do Pushwoosh no Piano
Para facilitar o gerenciamento de dados, crie uma propriedade no Piano que possa ser associada aos eventos do Pushwoosh. Isso permitirá que você identifique facilmente os eventos enviados do Pushwoosh.
Veja como criar a propriedade:
1. No Piano, vá para **Settings > Data Management > Properties.**
2. Clique em **Create Property**.
3. No campo **Name**, insira **pushwooshid**.
4. No campo **Property Key**, insira **pushwooshid**.
5. Defina o **Type** como **String**.
6. Clique em **Save**.
### Verificando se os eventos do Pushwoosh são enviados para o Piano
Para verificar se os eventos configurados no Pushwoosh são enviados com sucesso para o Piano, siga estes passos:
1. Na sua conta do Piano, vá para **Explorer > Audience > Overall Traffic**.
2. Crie um segmento com base em eventos onde a propriedade **pushwooshid** não está vazia.
A visualização filtrada exibirá informações gerais de tráfego, incluindo quaisquer eventos associados.
Para uma visão mais detalhada dos eventos enviados do Pushwoosh, navegue até **Content > Events**. Esta seção fornece uma análise detalhada de todos os eventos enviados do Pushwoosh, incluindo o número de vezes que cada evento ocorreu.
### Criando segmentos no Piano
Depois de concluir a configuração da integração, você pode começar a analisar os eventos enviados do Pushwoosh dentro do Piano. Para acessar esses eventos, navegue até **Explorer > Content > Events** na sua conta do Piano.
Em seguida, [crie Segmentos](https://support.piano.io/hc/en-us/articles/4467486423570-Create-a-segment) usando esses eventos. Ao criar segmentos, selecione a propriedade **`pushwooshid`** que você criou anteriormente para filtrar os eventos.
Certifique-se de dar ao seu segmento um nome claro e descritivo. A **Segment Key**, que é um identificador único para o segmento salvo, será necessária mais tarde para enviar segmentos para o Pushwoosh.
### Enviando segmentos do Piano para o Pushwoosh
Para permitir que o Pushwoosh recupere segmentos do Piano, forneça ao Pushwoosh a SegmentKey que você criou. Para encontrar a SegmentKey de um segmento, vá para **Analysis > Library > Segments**. Clique no segmento que você precisa e copie a **Segment Key**.
Na seção de Integrações do Pushwoosh, localize **Piano** e clique em **Import Segment**. Em seguida, insira a Segment key que você copiou.
Se a importação for bem-sucedida, você verá uma mensagem de confirmação.
Você pode acessar seus segmentos importados no Pushwoosh. Assim que a importação for concluída, eles serão listados na seção **Audience > Segments** da sua conta Pushwoosh.
## Mapeando o Piano VisitorID para o Pushwoosh UserID/HWID para análises acumuladas em todos os SDKs
Se um cliente deseja acumular análises tanto do SDK do Pushwoosh quanto do SDK do Piano Analytics, o Pushwoosh precisa mapear o Piano VisitorID para o Pushwoosh UserID/HWID. A solução é enviar uma tag de Piano VisitorID para o Pushwoosh para o usuário/dispositivo.
Para isso, faça o seguinte:
1. Crie uma tag chamada '**Piano Visitor ID**' no lado do Pushwoosh para o aplicativo. Nota: O nome da tag deve ser exatamente como descrito.
2. No lado do aplicativo do cliente, obtenha o Piano Visitor ID dentro do SDK do Piano usando o método **getVisitorId**.
3. No lado do aplicativo do cliente, use o SDK do Pushwoosh para chamar a requisição `setTags` com o valor da tag uma vez.
Se o valor da tag (Piano Visitor ID) existir para o usuário/dispositivo, o Pushwoosh o incluirá automaticamente como Client ID nas requisições para o Piano Analytics. No lado do Piano Analytics, ele será transformado em um valor de ID de visitante único.
## Exemplos de código
##### Web Push SDK (JavaScript)
```javascript
Pushwoosh.push(function(api) {
// Set tags for a user
api.setTags({
'Piano Visitor ID': pa.getVisitorID(),
});
```
##### Android (Java)
```java
String value1 = PianoAnalytics.getInstance().visitorId();
TagsBundle pianoTag = new TagsBundle.Builder()
.putString("Piano Visitor ID", value1)
.build();
Pushwoosh.getInstance().setTags(pianoTag);
```
##### iOS (Swift)
```swift
var pianoId: String = pa.getVisitorId(completionHandler: { visitorId in
Pushwoosh.sharedInstance().setTags([
"Piano Visitor ID": visitorId
])
})
```
##### iOS (Objective-C)
```objective-c
__block NSString *pianoId;
[pa getVisitorIdWithCompletionHandler:^(NSString *visitorId) {
Piano Visitor ID = visitorId;
[[Pushwoosh sharedInstance] setTags:@{@"Piano Visitor ID": visitorId}];
}];
```
Em geral, o Pushwoosh usa tags de dispositivo para fornecer informações do dispositivo e outras informações ao Piano Analytics em cada requisição. Aqui está uma lista de tags comuns usadas:
* **Country**
* **Device Model**
* **OS Version**
* **Browser Type** (em alguns casos)
## Como verificar se a integração está funcionando
#### Fonte: Detectando eventos enviados para o Piano Analytics
Existem duas maneiras fáceis de detectar eventos que foram enviados para o Piano Analytics:
##### Stream Inspector
1. Vá para sua conta do **Piano Analytics**.
2. Navegue para **Settings** > **Data Collection Portal** > **Tools** > **Stream Inspector**.
3. Escolha o site conectado que você deseja verificar.
4. Selecione os eventos que deseja inspecionar e inicie uma sessão.
5. Verifique se os eventos foram recebidos pelo Piano Analytics.
##### Verificar Eventos no Tráfego Geral
1. Vá para sua conta do **Piano Analytics**.
2. Navegue para **Settings** > **Explorer** > **Audience** > **Overall Traffic**.
3. Escolha o site e o intervalo de datas no menu abaixo.
#### Destino: Importando o Segmento do Piano
Para verificar a integração no lado do destino:
* Importe o segmento do Piano.
* Você deve ver um novo segmento (filtro) com um nome construído como `segment_key (Gerado automaticamente pelo Piano)`.
* Recalcule o segmento para obter informações atualizadas sobre o processamento atual dos dispositivos.
## FAQ de solução de problemas: Problemas comuns
#### Como posso garantir que os eventos sejam enviados corretamente do Pushwoosh para o Piano Analytics?
**Solução**: Use o Stream Inspector do Piano ou verifique o Overall Traffic no Piano Analytics para monitorar os eventos recebidos do Pushwoosh.
#### O que devo fazer se os dados do segmento não forem importados corretamente para o Pushwoosh?
**Solução**: Certifique-se de que a Segment Key do Piano corresponde à configuração no Pushwoosh. Verifique se há erros nos cálculos de tamanho do segmento ou na recuperação de dados.
#### Posso integrar o Piano VisitorID com o Pushwoosh para análises aprimoradas?
**Solução**: Sim, configurando uma tag específica no Pushwoosh e usando o SDK do Piano para buscar o VisitorID, você pode sincronizar os IDs de usuário entre as plataformas.
#### O que devo fazer se houver problemas com as configurações da chave de API?
**Solução**: Revise os logs de requisição da API, garanta que os URLs de endpoint e os tokens de autenticação (chaves de API) estejam corretos e verifique se há erros do lado do servidor relatados por qualquer um dos serviços.
Na janela que se abre, forneça as seguintes credenciais:
1. Site ID
Para localizar seu Site ID, faça login na sua conta do Piano e vá para **Analytics > Data Collection Portal > Dashboard.** Encontre o site relevante e copie seu ID.
2. Collection Domain
Para encontrar o Collection Domain, navegue até **Tagging > Collection Domains**. Copie o ID do Collection Domain. Certifique-se de inserir o domínio de coleta no formato **\*\*\*\*.pa-cd.com** sem o prefixo **https://.**
3. Chaves de Acesso e Secreta da API do Piano
Para obter as chaves:
* Na sua conta do Piano, clique em **See profile** abaixo do nome da sua conta.
* Navegue até a aba **API Keys** e crie uma nova chave com um nome e descrição claros. Em seguida, clique em **OK**.
* Na janela que se abre, copie sua **Access Key** e a **Secret Key**.
* No campo **API key** no Pushwoosh, insira tanto a **Access Key** quanto a **Secret Key**, separadas por um underscore. Por exemplo: **accesskey_secretkey**.
### Criando eventos no Piano para corresponder aos eventos do Pushwoosh
Para rastrear eventos enviados do Pushwoosh no Piano, você precisa criar os eventos correspondentes manualmente dentro do Piano.
Veja como fazer isso na sua conta do Piano:
1. Vá para **Settings > Data management > Data model**.
2. Selecione **Events** e clique no ícone de mais para criar um novo evento.
3. Na janela que se abre, forneça o nome e a descrição do evento, por exemplo, _**"pw\_siteopened"**_.
4. No campo **Type**, selecione **On-site**.
5. No campo **Categories**, selecione **Events**.
6. Clique em **Save**.
### Definindo o fuso horário do seu site no Piano
Definir o fuso horário correto para o seu site no Piano é crucial para o rastreamento e análise de dados precisos. A melhor prática é corresponder o fuso horário com o local onde você está enviando eventos e realizando análises. Isso elimina discrepâncias de tempo.
Para editar o fuso horário no Piano, vá para o **Dashboard** e clique na linha que contém as informações do seu site. Na janela pop-up, clique em **Edit** e selecione o fuso horário desejado. Em seguida, clique em **Save**.
### Criando uma propriedade para identificar eventos enviados do Pushwoosh no Piano
Para facilitar o gerenciamento de dados, crie uma propriedade no Piano que possa ser associada aos eventos do Pushwoosh. Isso permitirá que você identifique facilmente os eventos enviados do Pushwoosh.
Veja como criar a propriedade:
1. No Piano, vá para **Settings > Data Management > Properties.**
2. Clique em **Create Property**.
3. No campo **Name**, insira **pushwooshid**.
4. No campo **Property Key**, insira **pushwooshid**.
5. Defina o **Type** como **String**.
6. Clique em **Save**.
### Verificando se os eventos do Pushwoosh são enviados para o Piano
Para verificar se os eventos configurados no Pushwoosh são enviados com sucesso para o Piano, siga estes passos:
1. Na sua conta do Piano, vá para **Explorer > Audience > Overall Traffic**.
2. Crie um segmento com base em eventos onde a propriedade **pushwooshid** não está vazia.
A visualização filtrada exibirá informações gerais de tráfego, incluindo quaisquer eventos associados.
Para uma visão mais detalhada dos eventos enviados do Pushwoosh, navegue até **Content > Events**. Esta seção fornece uma análise detalhada de todos os eventos enviados do Pushwoosh, incluindo o número de vezes que cada evento ocorreu.
### Criando segmentos no Piano
Depois de concluir a configuração da integração, você pode começar a analisar os eventos enviados do Pushwoosh dentro do Piano. Para acessar esses eventos, navegue até **Explorer > Content > Events** na sua conta do Piano.
Em seguida, [crie Segmentos](https://support.piano.io/hc/en-us/articles/4467486423570-Create-a-segment) usando esses eventos. Ao criar segmentos, selecione a propriedade **`pushwooshid`** que você criou anteriormente para filtrar os eventos.
Certifique-se de dar ao seu segmento um nome claro e descritivo. A **Segment Key**, que é um identificador único para o segmento salvo, será necessária mais tarde para enviar segmentos para o Pushwoosh.
### Enviando segmentos do Piano para o Pushwoosh
Para permitir que o Pushwoosh recupere segmentos do Piano, forneça ao Pushwoosh a SegmentKey que você criou. Para encontrar a SegmentKey de um segmento, vá para **Analysis > Library > Segments**. Clique no segmento que você precisa e copie a **Segment Key**.
Na seção de Integrações do Pushwoosh, localize **Piano** e clique em **Import Segment**. Em seguida, insira a Segment key que você copiou.
Se a importação for bem-sucedida, você verá uma mensagem de confirmação.
Você pode acessar seus segmentos importados no Pushwoosh. Assim que a importação for concluída, eles serão listados na seção **Audience > Segments** da sua conta Pushwoosh.
## Mapeando o Piano VisitorID para o Pushwoosh UserID/HWID para análises acumuladas em todos os SDKs
Se um cliente deseja acumular análises tanto do SDK do Pushwoosh quanto do SDK do Piano Analytics, o Pushwoosh precisa mapear o Piano VisitorID para o Pushwoosh UserID/HWID. A solução é enviar uma tag de Piano VisitorID para o Pushwoosh para o usuário/dispositivo.
Para isso, faça o seguinte:
1. Crie uma tag chamada '**Piano Visitor ID**' no lado do Pushwoosh para o aplicativo. Nota: O nome da tag deve ser exatamente como descrito.
2. No lado do aplicativo do cliente, obtenha o Piano Visitor ID dentro do SDK do Piano usando o método **getVisitorId**.
3. No lado do aplicativo do cliente, use o SDK do Pushwoosh para chamar a requisição `setTags` com o valor da tag uma vez.
Se o valor da tag (Piano Visitor ID) existir para o usuário/dispositivo, o Pushwoosh o incluirá automaticamente como Client ID nas requisições para o Piano Analytics. No lado do Piano Analytics, ele será transformado em um valor de ID de visitante único.
## Exemplos de código
##### Web Push SDK (JavaScript)
```javascript
Pushwoosh.push(function(api) {
// Set tags for a user
api.setTags({
'Piano Visitor ID': pa.getVisitorID(),
});
```
##### Android (Java)
```java
String value1 = PianoAnalytics.getInstance().visitorId();
TagsBundle pianoTag = new TagsBundle.Builder()
.putString("Piano Visitor ID", value1)
.build();
Pushwoosh.getInstance().setTags(pianoTag);
```
##### iOS (Swift)
```swift
var pianoId: String = pa.getVisitorId(completionHandler: { visitorId in
Pushwoosh.sharedInstance().setTags([
"Piano Visitor ID": visitorId
])
})
```
##### iOS (Objective-C)
```objective-c
__block NSString *pianoId;
[pa getVisitorIdWithCompletionHandler:^(NSString *visitorId) {
Piano Visitor ID = visitorId;
[[Pushwoosh sharedInstance] setTags:@{@"Piano Visitor ID": visitorId}];
}];
```
Em geral, o Pushwoosh usa tags de dispositivo para fornecer informações do dispositivo e outras informações ao Piano Analytics em cada requisição. Aqui está uma lista de tags comuns usadas:
* **Country**
* **Device Model**
* **OS Version**
* **Browser Type** (em alguns casos)
## Como verificar se a integração está funcionando
#### Fonte: Detectando eventos enviados para o Piano Analytics
Existem duas maneiras fáceis de detectar eventos que foram enviados para o Piano Analytics:
##### Stream Inspector
1. Vá para sua conta do **Piano Analytics**.
2. Navegue para **Settings** > **Data Collection Portal** > **Tools** > **Stream Inspector**.
3. Escolha o site conectado que você deseja verificar.
4. Selecione os eventos que deseja inspecionar e inicie uma sessão.
5. Verifique se os eventos foram recebidos pelo Piano Analytics.
##### Verificar Eventos no Tráfego Geral
1. Vá para sua conta do **Piano Analytics**.
2. Navegue para **Settings** > **Explorer** > **Audience** > **Overall Traffic**.
3. Escolha o site e o intervalo de datas no menu abaixo.
#### Destino: Importando o Segmento do Piano
Para verificar a integração no lado do destino:
* Importe o segmento do Piano.
* Você deve ver um novo segmento (filtro) com um nome construído como `segment_key (Gerado automaticamente pelo Piano)`.
* Recalcule o segmento para obter informações atualizadas sobre o processamento atual dos dispositivos.
## FAQ de solução de problemas: Problemas comuns
#### Como posso garantir que os eventos sejam enviados corretamente do Pushwoosh para o Piano Analytics?
**Solução**: Use o Stream Inspector do Piano ou verifique o Overall Traffic no Piano Analytics para monitorar os eventos recebidos do Pushwoosh.
#### O que devo fazer se os dados do segmento não forem importados corretamente para o Pushwoosh?
**Solução**: Certifique-se de que a Segment Key do Piano corresponde à configuração no Pushwoosh. Verifique se há erros nos cálculos de tamanho do segmento ou na recuperação de dados.
#### Posso integrar o Piano VisitorID com o Pushwoosh para análises aprimoradas?
**Solução**: Sim, configurando uma tag específica no Pushwoosh e usando o SDK do Piano para buscar o VisitorID, você pode sincronizar os IDs de usuário entre as plataformas.
#### O que devo fazer se houver problemas com as configurações da chave de API?
**Solução**: Revise os logs de requisição da API, garanta que os URLs de endpoint e os tokens de autenticação (chaves de API) estejam corretos e verifique se há erros do lado do servidor relatados por qualquer um dos serviços.