# Integración con Piano Analytics
[Piano Analytics](https://piano.io/product/analytics/) es una herramienta que ayuda a las empresas a comprender cómo las personas interactúan con sus sitios web y aplicaciones. Recopila datos sobre el comportamiento del usuario y proporciona información a través de informes y visualizaciones. Esta información ayuda a las empresas a tomar mejores decisiones sobre cómo mejorar sus productos digitales y esfuerzos de marketing.
La integración de [Piano Analytics](https://piano.io/product/analytics/) y Pushwoosh permite obtener información detallada sobre el comportamiento del usuario para crear segmentos precisos y enviar notificaciones push, correos electrónicos y mensajes in-app altamente dirigidos a los usuarios correctos en el momento adecuado.
## Resumen de la integración
### Tipo de integración
* **Destino**: Los datos se envían desde Piano Analytics a Pushwoosh.
* **Fuente**: Los datos se envían desde Pushwoosh a Piano Analytics.
### Requisitos previos
Cuentas de pago tanto en Pushwoosh como en Piano Analytics
### Glosario (mapeo de nombres de entidades si son diferentes)
Al integrar Pushwoosh y Piano Analytics, ciertos nombres de entidades pueden variar entre las dos plataformas. Aquí están los mapeos entre Pushwoosh y 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
**Fuente**
* Eventos
* Estadísticas de Push
* Tags (como atributos de eventos)
**Destino**
* Segmentos
### Casos de uso
**Analítica unificada**
Combine los datos de interacción de Pushwoosh con Piano Analytics para obtener una visión completa del usuario. Esto le permite obtener una visión holística del comportamiento e interacciones del usuario a través de múltiples puntos de contacto.
**Segmentación**
Cree segmentos de usuarios dirigidos en Pushwoosh basados en los datos de Piano Analytics. Utilice esta segmentación mejorada para ofrecer campañas de marketing personalizadas y efectivas.
**Monitoreo del rendimiento**
Realice un seguimiento de la efectividad de la campaña y la interacción del usuario en todas las plataformas.
### ¿Cómo funciona la integración?
##### Resumen del flujo
1. **Configuración**: Configure los ajustes de integración en las cuentas de Pushwoosh y Piano Analytics.
2. **Mapeo de eventos**: Mapee los eventos de Pushwoosh a los eventos de Piano (por ejemplo, PostEvent.EventName a PianoEvent.Name).
3. **Transferencia de datos**: Pushwoosh envía eventos (Post Events y Tracking Log Events) a Piano Analytics.
4. **Importación de segmentos**: Piano Analytics envía datos de segmentos a Pushwoosh para la segmentación de la audiencia.
##### Flujo técnico
1. **Post Events**
* Pushwoosh envía datos de eventos a Piano Analytics.
* Los atributos se mapean de la siguiente manera:
* UserID (Pushwoosh) > PushwooshID (Piano)
* CampaignID (Pushwoosh) > SrcMedium (Piano)
* PlatformID (Pushwoosh) > DeviceType (Piano)
2. **Tracking Log Events**:
* Pushwoosh envía datos de seguimiento (por ejemplo, Push Enviado, Push Entregado) a Piano Analytics.
* Estos datos enriquecen Piano Analytics con métricas de entrega e interacción.
3. **Integración de Piano VisitorID**:
* Opcionalmente, integre Piano VisitorID con Pushwoosh para una analítica unificada en todos los SDK.
## Configuración de la integración
Para configurar la integración, vaya a **Settings > 3rd Party Integrations** en su cuenta de Pushwoosh y localice **Piano**. Haga clic en **Configure**.
En la ventana que se abre, proporcione las siguientes credenciales:
1. Site ID
Para localizar su Site ID, inicie sesión en su cuenta de Piano y vaya a **Analytics > Data Collection Portal > Dashboard.** Encuentre el sitio web relevante y copie su ID.
2. Collection Domain
Para encontrar el Collection Domain, navegue a **Tagging > Collection Domains**. Copie el ID del Collection Domain. Asegúrese de introducir el dominio de colección en el formato **\*\*\*\*.pa-cd.com** sin el prefijo **https://.**
3. Claves de acceso y secretas de la API de Piano
Para obtener las claves:
* En su cuenta de Piano, haga clic en **See profile** debajo del nombre de su cuenta.
* Navegue a la pestaña **API Keys** y cree una nueva clave con un nombre y descripción claros. Luego haga clic en **OK**.
* En la ventana que se abre, copie su **Access Key** y la **Secret Key**.
* En el campo **API key** en Pushwoosh, introduzca tanto la **Access Key** como la **Secret Key**, separadas por un guion bajo. Por ejemplo: **accesskey_secretkey**.
### Creación de eventos de Piano para que coincidan con los eventos de Pushwoosh
Para rastrear los eventos enviados desde Pushwoosh en Piano, necesita crear los eventos correspondientes manualmente dentro de Piano.
Así es como se hace en su cuenta de Piano:
1. Vaya a **Settings > Data management > Data model**.
2. Seleccione **Events** y haga clic en el icono de más para crear un nuevo evento.
3. En la ventana que se abre, proporcione el nombre y la descripción del evento, por ejemplo, _**"pw\_siteopened"**_.
4. En el campo **Type**, seleccione **On-site**.
5. En el campo **Categories**, seleccione **Events**.
6. Haga clic en **Save**.
### Configuración de la zona horaria de su sitio web en Piano
Establecer la zona horaria correcta para su sitio web en Piano es crucial para un seguimiento y análisis de datos precisos. La mejor práctica es hacer coincidir la zona horaria con la ubicación donde está enviando eventos y realizando análisis. Esto elimina las discrepancias de tiempo.
Para editar la zona horaria en Piano, vaya a **Dashboard** y haga clic en la línea que contiene la información de su sitio. En la ventana emergente, haga clic en **Edit** y seleccione la zona horaria deseada. Luego, haga clic en **Save**.
### Creación de una propiedad para identificar eventos enviados desde Pushwoosh en Piano
Para facilitar la gestión de datos, cree una propiedad en Piano que pueda asociarse con los eventos de Pushwoosh. Esto le permitirá identificar fácilmente los eventos enviados desde Pushwoosh.
Así es como se crea la propiedad:
1. En Piano, vaya a **Settings > Data Management > Properties.**
2. Haga clic en **Create Property**.
3. En el campo **Name**, introduzca **pushwooshid**.
4. En el campo **Property Key**, introduzca **pushwooshid**.
5. Establezca el **Type** en **String**.
6. Haga clic en **Save**.
### Comprobación de si los eventos de Pushwoosh se envían a Piano
Para verificar que los eventos configurados en Pushwoosh se envían correctamente a Piano, siga estos pasos:
1. En su cuenta de Piano, vaya a **Explorer > Audience > Overall Traffic**.
2. Cree un segmento basado en eventos donde la propiedad **pushwooshid** no esté vacía.
La vista filtrada mostrará información general del tráfico, incluyendo cualquier evento asociado.
Para una vista más granular de los eventos enviados desde Pushwoosh, navegue a **Content > Events**. Esta sección proporciona un desglose detallado de todos los eventos enviados desde Pushwoosh, incluyendo el número de veces que ocurrió cada evento.
### Creación de segmentos en Piano
Una vez que haya completado la configuración de la integración, puede comenzar a analizar los eventos enviados desde Pushwoosh dentro de Piano. Para acceder a estos eventos, navegue a **Explorer > Content > Events** en su cuenta de Piano.
Luego [cree Segmentos](https://support.piano.io/hc/en-us/articles/4467486423570-Create-a-segment) usando estos eventos. Al crear segmentos, seleccione la propiedad **`pushwooshid`** que ha creado anteriormente para filtrar eventos.
Asegúrese de darle a su segmento un nombre claro y descriptivo. La **Segment Key**, que es un identificador único para el segmento guardado, se necesitará más tarde para enviar segmentos a Pushwoosh.
### Envío de segmentos de Piano a Pushwoosh
Para permitir que Pushwoosh recupere segmentos de Piano, proporcione a Pushwoosh la SegmentKey que creó. Para encontrar la SegmentKey de un segmento, vaya a **Analysis > Library > Segments**. Haga clic en el segmento que necesita y copie la **Segment Key**.
En la sección de Integraciones de Pushwoosh, localice **Piano** y haga clic en **Import Segment**. Luego, introduzca la Segment key que copió.
Si la importación es exitosa, verá un mensaje de confirmación.
Puede acceder a sus segmentos importados en Pushwoosh. Una vez que la importación esté completa, se listarán en la sección **Audience > Segments** de su cuenta de Pushwoosh.
## Mapeo de Piano VisitorID a Pushwoosh UserID/HWID para analíticas acumuladas en todos los SDK
Si un cliente quiere acumular analíticas tanto del SDK de Pushwoosh como del SDK de Piano Analytics, Pushwoosh necesita mapear el Piano VisitorID al UserID/HWID de Pushwoosh. La solución es enviar un tag de Piano VisitorID a Pushwoosh para el usuario/dispositivo.
Para ello, haga lo siguiente:
1. Cree un tag llamado '**Piano Visitor ID**' en el lado de Pushwoosh para la aplicación. Nota: El nombre del tag debe ser exactamente como se describe.
2. En el lado de la aplicación del cliente, obtenga el Piano Visitor ID dentro del SDK de Piano usando el método **getVisitorId**.
3. En el lado de la aplicación del cliente, use el SDK de Pushwoosh para llamar a la solicitud `setTags` con el valor del tag una vez.
Si el valor del tag (Piano Visitor ID) existe para el usuario/dispositivo, Pushwoosh lo incluirá automáticamente como Client ID en las solicitudes a Piano Analytics. En el lado de Piano Analytics, se transformará en un valor de ID de visitante único.
## Ejemplos 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}];
}];
```
En general, Pushwoosh utiliza tags de dispositivo para proporcionar información del dispositivo y otra información a Piano Analytics en cada solicitud. Aquí hay una lista de tags comunes utilizados:
* **Country**
* **Device Model**
* **OS Version**
* **Browser Type** (en algunos casos)
## Cómo verificar que la integración funciona
#### Fuente: Detección de eventos enviados a Piano Analytics
Hay dos formas fáciles de detectar eventos que se enviaron a Piano Analytics:
##### Stream Inspector
1. Vaya a su cuenta de **Piano Analytics**.
2. Navegue a **Settings** > **Data Collection Portal** > **Tools** > **Stream Inspector**.
3. Elija el sitio conectado que desea verificar.
4. Seleccione los eventos que desea inspeccionar e inicie una sesión.
5. Verifique que los eventos fueron recibidos por Piano Analytics.
##### Comprobar eventos en Overall Traffic
1. Vaya a su cuenta de **Piano Analytics**.
2. Navegue a **Settings** > **Explorer** > **Audience** > **Overall Traffic**.
3. Elija el sitio y el rango de fechas en el menú de abajo.
#### Destino: Importación del segmento de Piano
Para verificar la integración en el lado del destino:
* Importe el segmento de Piano.
* Debería ver un nuevo segmento (filtro) con un nombre construido como `segment_key (Piano Autogenerated)`.
* Recalcule el segmento para obtener información actualizada sobre el procesamiento actual de los dispositivos.
## Solución de problemas de preguntas frecuentes: Problemas comunes
#### ¿Cómo puedo asegurarme de que los eventos se envíen correctamente de Pushwoosh a Piano Analytics?
**Solución**: Utilice el Stream Inspector de Piano o compruebe el Overall Traffic en Piano Analytics para monitorear los eventos entrantes de Pushwoosh.
#### ¿Qué debo hacer si los datos del segmento no se importan correctamente en Pushwoosh?
**Solución**: Asegúrese de que la Segment Key de Piano coincida con la configuración en Pushwoosh. Verifique si hay errores en los cálculos del tamaño del segmento o en la recuperación de datos.
#### ¿Puedo integrar Piano VisitorID con Pushwoosh para análisis mejorados?
**Solución**: Sí, configurando un tag específico en Pushwoosh y usando el SDK de Piano para obtener el VisitorID, puede sincronizar los ID de usuario en todas las plataformas.
#### ¿Qué debo hacer si hay problemas con las configuraciones de la clave de API?
**Solución**: Revise los registros de solicitudes de la API, asegúrese de que las URL de los puntos finales y los tokens de autenticación (claves de API) sean correctos, y verifique si hay errores del lado del servidor informados por cualquiera de los servicios.
En la ventana que se abre, proporcione las siguientes credenciales:
1. Site ID
Para localizar su Site ID, inicie sesión en su cuenta de Piano y vaya a **Analytics > Data Collection Portal > Dashboard.** Encuentre el sitio web relevante y copie su ID.
2. Collection Domain
Para encontrar el Collection Domain, navegue a **Tagging > Collection Domains**. Copie el ID del Collection Domain. Asegúrese de introducir el dominio de colección en el formato **\*\*\*\*.pa-cd.com** sin el prefijo **https://.**
3. Claves de acceso y secretas de la API de Piano
Para obtener las claves:
* En su cuenta de Piano, haga clic en **See profile** debajo del nombre de su cuenta.
* Navegue a la pestaña **API Keys** y cree una nueva clave con un nombre y descripción claros. Luego haga clic en **OK**.
* En la ventana que se abre, copie su **Access Key** y la **Secret Key**.
* En el campo **API key** en Pushwoosh, introduzca tanto la **Access Key** como la **Secret Key**, separadas por un guion bajo. Por ejemplo: **accesskey_secretkey**.
### Creación de eventos de Piano para que coincidan con los eventos de Pushwoosh
Para rastrear los eventos enviados desde Pushwoosh en Piano, necesita crear los eventos correspondientes manualmente dentro de Piano.
Así es como se hace en su cuenta de Piano:
1. Vaya a **Settings > Data management > Data model**.
2. Seleccione **Events** y haga clic en el icono de más para crear un nuevo evento.
3. En la ventana que se abre, proporcione el nombre y la descripción del evento, por ejemplo, _**"pw\_siteopened"**_.
4. En el campo **Type**, seleccione **On-site**.
5. En el campo **Categories**, seleccione **Events**.
6. Haga clic en **Save**.
### Configuración de la zona horaria de su sitio web en Piano
Establecer la zona horaria correcta para su sitio web en Piano es crucial para un seguimiento y análisis de datos precisos. La mejor práctica es hacer coincidir la zona horaria con la ubicación donde está enviando eventos y realizando análisis. Esto elimina las discrepancias de tiempo.
Para editar la zona horaria en Piano, vaya a **Dashboard** y haga clic en la línea que contiene la información de su sitio. En la ventana emergente, haga clic en **Edit** y seleccione la zona horaria deseada. Luego, haga clic en **Save**.
### Creación de una propiedad para identificar eventos enviados desde Pushwoosh en Piano
Para facilitar la gestión de datos, cree una propiedad en Piano que pueda asociarse con los eventos de Pushwoosh. Esto le permitirá identificar fácilmente los eventos enviados desde Pushwoosh.
Así es como se crea la propiedad:
1. En Piano, vaya a **Settings > Data Management > Properties.**
2. Haga clic en **Create Property**.
3. En el campo **Name**, introduzca **pushwooshid**.
4. En el campo **Property Key**, introduzca **pushwooshid**.
5. Establezca el **Type** en **String**.
6. Haga clic en **Save**.
### Comprobación de si los eventos de Pushwoosh se envían a Piano
Para verificar que los eventos configurados en Pushwoosh se envían correctamente a Piano, siga estos pasos:
1. En su cuenta de Piano, vaya a **Explorer > Audience > Overall Traffic**.
2. Cree un segmento basado en eventos donde la propiedad **pushwooshid** no esté vacía.
La vista filtrada mostrará información general del tráfico, incluyendo cualquier evento asociado.
Para una vista más granular de los eventos enviados desde Pushwoosh, navegue a **Content > Events**. Esta sección proporciona un desglose detallado de todos los eventos enviados desde Pushwoosh, incluyendo el número de veces que ocurrió cada evento.
### Creación de segmentos en Piano
Una vez que haya completado la configuración de la integración, puede comenzar a analizar los eventos enviados desde Pushwoosh dentro de Piano. Para acceder a estos eventos, navegue a **Explorer > Content > Events** en su cuenta de Piano.
Luego [cree Segmentos](https://support.piano.io/hc/en-us/articles/4467486423570-Create-a-segment) usando estos eventos. Al crear segmentos, seleccione la propiedad **`pushwooshid`** que ha creado anteriormente para filtrar eventos.
Asegúrese de darle a su segmento un nombre claro y descriptivo. La **Segment Key**, que es un identificador único para el segmento guardado, se necesitará más tarde para enviar segmentos a Pushwoosh.
### Envío de segmentos de Piano a Pushwoosh
Para permitir que Pushwoosh recupere segmentos de Piano, proporcione a Pushwoosh la SegmentKey que creó. Para encontrar la SegmentKey de un segmento, vaya a **Analysis > Library > Segments**. Haga clic en el segmento que necesita y copie la **Segment Key**.
En la sección de Integraciones de Pushwoosh, localice **Piano** y haga clic en **Import Segment**. Luego, introduzca la Segment key que copió.
Si la importación es exitosa, verá un mensaje de confirmación.
Puede acceder a sus segmentos importados en Pushwoosh. Una vez que la importación esté completa, se listarán en la sección **Audience > Segments** de su cuenta de Pushwoosh.
## Mapeo de Piano VisitorID a Pushwoosh UserID/HWID para analíticas acumuladas en todos los SDK
Si un cliente quiere acumular analíticas tanto del SDK de Pushwoosh como del SDK de Piano Analytics, Pushwoosh necesita mapear el Piano VisitorID al UserID/HWID de Pushwoosh. La solución es enviar un tag de Piano VisitorID a Pushwoosh para el usuario/dispositivo.
Para ello, haga lo siguiente:
1. Cree un tag llamado '**Piano Visitor ID**' en el lado de Pushwoosh para la aplicación. Nota: El nombre del tag debe ser exactamente como se describe.
2. En el lado de la aplicación del cliente, obtenga el Piano Visitor ID dentro del SDK de Piano usando el método **getVisitorId**.
3. En el lado de la aplicación del cliente, use el SDK de Pushwoosh para llamar a la solicitud `setTags` con el valor del tag una vez.
Si el valor del tag (Piano Visitor ID) existe para el usuario/dispositivo, Pushwoosh lo incluirá automáticamente como Client ID en las solicitudes a Piano Analytics. En el lado de Piano Analytics, se transformará en un valor de ID de visitante único.
## Ejemplos 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}];
}];
```
En general, Pushwoosh utiliza tags de dispositivo para proporcionar información del dispositivo y otra información a Piano Analytics en cada solicitud. Aquí hay una lista de tags comunes utilizados:
* **Country**
* **Device Model**
* **OS Version**
* **Browser Type** (en algunos casos)
## Cómo verificar que la integración funciona
#### Fuente: Detección de eventos enviados a Piano Analytics
Hay dos formas fáciles de detectar eventos que se enviaron a Piano Analytics:
##### Stream Inspector
1. Vaya a su cuenta de **Piano Analytics**.
2. Navegue a **Settings** > **Data Collection Portal** > **Tools** > **Stream Inspector**.
3. Elija el sitio conectado que desea verificar.
4. Seleccione los eventos que desea inspeccionar e inicie una sesión.
5. Verifique que los eventos fueron recibidos por Piano Analytics.
##### Comprobar eventos en Overall Traffic
1. Vaya a su cuenta de **Piano Analytics**.
2. Navegue a **Settings** > **Explorer** > **Audience** > **Overall Traffic**.
3. Elija el sitio y el rango de fechas en el menú de abajo.
#### Destino: Importación del segmento de Piano
Para verificar la integración en el lado del destino:
* Importe el segmento de Piano.
* Debería ver un nuevo segmento (filtro) con un nombre construido como `segment_key (Piano Autogenerated)`.
* Recalcule el segmento para obtener información actualizada sobre el procesamiento actual de los dispositivos.
## Solución de problemas de preguntas frecuentes: Problemas comunes
#### ¿Cómo puedo asegurarme de que los eventos se envíen correctamente de Pushwoosh a Piano Analytics?
**Solución**: Utilice el Stream Inspector de Piano o compruebe el Overall Traffic en Piano Analytics para monitorear los eventos entrantes de Pushwoosh.
#### ¿Qué debo hacer si los datos del segmento no se importan correctamente en Pushwoosh?
**Solución**: Asegúrese de que la Segment Key de Piano coincida con la configuración en Pushwoosh. Verifique si hay errores en los cálculos del tamaño del segmento o en la recuperación de datos.
#### ¿Puedo integrar Piano VisitorID con Pushwoosh para análisis mejorados?
**Solución**: Sí, configurando un tag específico en Pushwoosh y usando el SDK de Piano para obtener el VisitorID, puede sincronizar los ID de usuario en todas las plataformas.
#### ¿Qué debo hacer si hay problemas con las configuraciones de la clave de API?
**Solución**: Revise los registros de solicitudes de la API, asegúrese de que las URL de los puntos finales y los tokens de autenticación (claves de API) sean correctos, y verifique si hay errores del lado del servidor informados por cualquiera de los servicios.