# Интеграция с Piano Analytics
[Piano Analytics](https://piano.io/product/analytics/) — это инструмент, который помогает компаниям понять, как люди взаимодействуют с их веб-сайтами и приложениями. Он собирает данные о поведении пользователей и предоставляет аналитику в виде отчетов и визуализаций. Эта информация помогает компаниям принимать более обоснованные решения о том, как улучшить свои цифровые продукты и маркетинговые усилия.
Интеграция [Piano Analytics](https://piano.io/product/analytics/) и Pushwoosh позволяет получить подробную информацию о поведении пользователей для создания точных сегментов и отправки высокотаргетированных push-уведомлений, электронных писем и сообщений в приложении нужным пользователям в нужное время.
## Обзор интеграции
### Тип интеграции
* **Назначение**: Данные отправляются из Piano Analytics в Pushwoosh.
* **Источник**: Данные отправляются из Pushwoosh в Piano Analytics.
### Предварительные требования
Платные аккаунты в Pushwoosh и Piano Analytics
### Глоссарий (сопоставление имен сущностей, если они различаются)
При интеграции Pushwoosh и Piano Analytics некоторые имена сущностей могут различаться между двумя платформами. Ниже приведены сопоставления между Pushwoosh и Piano Analytics:
| Pushwoosh | Piano Analytics |
| ----- | ----- |
| UserID/hwid | visitorID |
| PostEvent.EventName | PianoEvent.Name |
| PostEvent.UserID | PianoEvent.PushwooshID |
| PostEvent.CampaignID | PianoEvent.SrcMedium |
| PostEvent.PlatformID | PianoEvent.DeviceType |
### Синхронизированные сущности
**Источник**
* События
* Статистика пушей
* Теги (как атрибуты событий)
**Назначение**
* Сегменты
### Варианты использования
**Единая аналитика**
Объедините данные о вовлеченности из Pushwoosh с Piano Analytics для получения всесторонней аналитики по пользователям. Это позволит вам получить целостное представление о поведении и взаимодействиях пользователей в различных точках контакта.
**Сегментация**
Создавайте целевые сегменты пользователей в Pushwoosh на основе данных из Piano Analytics. Используйте эту расширенную сегментацию для проведения персонализированных и эффективных маркетинговых кампаний.
**Мониторинг производительности**
Отслеживайте эффективность кампаний и взаимодействие пользователей на разных платформах.
### Как работает интеграция?
##### Обзор процесса
1. **Настройка**: Настройте параметры интеграции в аккаунтах Pushwoosh и Piano Analytics.
2. **Сопоставление событий**: Сопоставьте события Pushwoosh с событиями Piano (например, PostEvent.EventName с PianoEvent.Name).
3. **Передача данных**: Pushwoosh отправляет события (Post Events и Tracking Log Events) в Piano Analytics.
4. **Импорт сегментов**: Piano Analytics отправляет данные о сегментах в Pushwoosh для сегментации аудитории.
##### Технический процесс
1. **Post Events**
* Pushwoosh отправляет данные о событиях в Piano Analytics.
* Атрибуты сопоставляются следующим образом:
* UserID (Pushwoosh) > PushwooshID (Piano)
* CampaignID (Pushwoosh) > SrcMedium (Piano)
* PlatformID (Pushwoosh) > DeviceType (Piano)
2. **Tracking Log Events**:
* Pushwoosh отправляет данные отслеживания (например, Push Sent, Push Delivered) в Piano Analytics.
* Эти данные обогащают Piano Analytics метриками доставки и вовлеченности.
3. **Интеграция Piano VisitorID**:
* При необходимости интегрируйте Piano VisitorID с Pushwoosh для единой аналитики по всем SDK.
## Настройка интеграции
Для настройки интеграции перейдите в **Settings > 3rd Party Integrations** в вашем аккаунте Pushwoosh и найдите **Piano**. Нажмите **Configure**.
В открывшемся окне введите следующие учетные данные:
1. Site ID
Чтобы найти ваш Site ID, войдите в свой аккаунт Piano и перейдите в **Analytics > Data Collection Portal > Dashboard.** Найдите соответствующий веб-сайт и скопируйте его ID.
2. Collection Domain
Чтобы найти Collection Domain, перейдите в **Tagging > Collection Domains**. Скопируйте ID Collection Domain. Убедитесь, что вы вводите домен сбора в формате **\*\*\*\*.pa-cd.com** без префикса **https://.**
3. Piano API Access и Secret keys
Чтобы получить ключи:
* В вашем аккаунте Piano нажмите на **See profile** под именем вашего аккаунта.
* Перейдите на вкладку **API Keys** и создайте новый ключ с понятным названием и описанием. Затем нажмите **OK**.
* В открывшемся окне скопируйте ваш **Access Key** и **Secret Key**.
* В поле **API key** в Pushwoosh введите **Access Key** и **Secret Key**, разделенные нижним подчеркиванием. Например: **accesskey_secretkey**.
### Создание событий Piano для сопоставления с событиями Pushwoosh
Чтобы отслеживать события, отправленные из Pushwoosh в Piano, вам необходимо вручную создать соответствующие события в Piano.
Вот как это сделать в вашем аккаунте Piano:
1. Перейдите в **Settings > Data management > Data model**.
2. Выберите **Events** и нажмите на значок плюса, чтобы создать новое событие.
3. В открывшемся окне укажите название и описание события, например, _**"pw\_siteopened"**_.
4. В поле **Type** выберите **On-site**.
5. В поле **Categories** выберите **Events**.
6. Нажмите **Save**.
### Установка часового пояса вашего веб-сайта в Piano
Установка правильного часового пояса для вашего веб-сайта в Piano имеет решающее значение для точного отслеживания и анализа данных. Лучшей практикой является согласование часового пояса с местом, откуда вы отправляете события и проводите анализ. Это устраняет расхождения во времени.
Чтобы изменить часовой пояс в Piano, перейдите в **Dashboard** и нажмите на строку с информацией о вашем сайте. Во всплывающем окне нажмите **Edit** и выберите нужный часовой пояс. Затем нажмите **Save**.
### Создание свойства для идентификации событий, отправленных из Pushwoosh в Piano
Чтобы упростить управление данными, создайте в Piano свойство, которое можно будет связать с событиями Pushwoosh. Это позволит вам легко идентифицировать события, отправленные из Pushwoosh.
Вот как создать свойство:
1. В Piano перейдите в **Settings > Data Management > Properties.**
2. Нажмите **Create Property**.
3. В поле **Name** введите **pushwooshid**.
4. В поле **Property Key** введите **pushwooshid**.
5. Установите **Type** на **String**.
6. Нажмите **Save**.
### Проверка отправки событий Pushwoosh в Piano
Чтобы убедиться, что события, настроенные в Pushwoosh, успешно отправляются в Piano, выполните следующие шаги:
1. В вашем аккаунте Piano перейдите в **Explorer > Audience > Overall Traffic**.
2. Создайте сегмент на основе событий, где свойство **pushwooshid** не пустое.
Отфильтрованное представление покажет общую информацию о трафике, включая все связанные события.
Для более детального просмотра событий, отправленных из Pushwoosh, перейдите в **Content > Events**. Этот раздел предоставляет подробную разбивку всех событий, отправленных из Pushwoosh, включая количество раз, когда каждое событие произошло.
### Создание сегментов в Piano
После завершения настройки интеграции вы можете начать анализировать события, отправленные из Pushwoosh, в Piano. Чтобы получить доступ к этим событиям, перейдите в **Explorer > Content > Events** в вашем аккаунте Piano.
Затем [создайте сегменты](https://support.piano.io/hc/en-us/articles/4467486423570-Create-a-segment), используя эти события. При создании сегментов выберите свойство **`pushwooshid`**, которое вы создали ранее, для фильтрации событий.
Убедитесь, что вы дали вашему сегменту понятное и описательное название. **Segment Key**, который является уникальным идентификатором для сохраненного сегмента, понадобится позже для отправки сегментов в Pushwoosh.
### Отправка сегментов из Piano в Pushwoosh
Чтобы Pushwoosh мог получать сегменты из Piano, предоставьте Pushwoosh созданный вами SegmentKey. Чтобы найти SegmentKey для сегмента, перейдите в **Analysis > Library > Segments**. Нажмите на нужный сегмент и скопируйте **Segment Key**.
В разделе Pushwoosh Integrations найдите **Piano** и нажмите **Import Segment**. Затем введите скопированный Segment key.
Если импорт прошел успешно, вы увидите подтверждающее сообщение.
Вы можете получить доступ к импортированным сегментам в Pushwoosh. После завершения импорта они будут перечислены в разделе **Audience > Segments** вашего аккаунта Pushwoosh.
## Сопоставление Piano VisitorID с Pushwoosh UserID/HWID для накопленной аналитики по всем SDK
Если клиент хочет накапливать аналитику как из Pushwoosh SDK, так и из Piano Analytics SDK, Pushwoosh должен сопоставить Piano VisitorID с Pushwoosh UserID/HWID. Решение заключается в отправке тега Piano VisitorID в Pushwoosh для пользователя/устройства.
Для этого выполните следующее:
1. Создайте тег с названием '**Piano Visitor ID**' на стороне Pushwoosh для приложения. Примечание: название тега должно быть точно таким, как описано.
2. На стороне приложения клиента получите Piano Visitor ID в Piano SDK с помощью метода **getVisitorId**.
3. На стороне приложения клиента используйте Pushwoosh SDK для однократного вызова запроса `setTags` со значением тега.
Если значение тега (Piano Visitor ID) существует для пользователя/устройства, Pushwoosh автоматически включит его как Client ID в запросы к Piano Analytics. На стороне Piano Analytics он будет преобразован в уникальное значение visitor ID.
## Примеры кода
##### Web Push SDK (JavaScript)
```javascript
Pushwoosh.push(function(api) {
// Установить теги для пользователя
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}];
}];
```
В целом, Pushwoosh использует теги устройств для предоставления информации об устройстве и другой информации в Piano Analytics в каждом запросе. Вот список часто используемых тегов:
* **Country**
* **Device Model**
* **OS Version**
* **Browser Type** (в некоторых случаях)
## Как проверить, что интеграция работает
#### Источник: Обнаружение событий, отправленных в Piano Analytics
Есть два простых способа обнаружить события, которые были отправлены в Piano Analytics:
##### Stream Inspector
1. Перейдите в ваш аккаунт **Piano Analytics**.
2. Перейдите в **Settings** > **Data Collection Portal** > **Tools** > **Stream Inspector**.
3. Выберите подключенный сайт, который вы хотите проверить.
4. Выберите события, которые вы хотите проверить, и начните сессию.
5. Убедитесь, что события были получены Piano Analytics.
##### Проверка событий в Overall Traffic
1. Перейдите в ваш аккаунт **Piano Analytics**.
2. Перейдите в **Settings** > **Explorer** > **Audience** > **Overall Traffic**.
3. Выберите сайт и диапазон дат в меню ниже.
#### Назначение: Импорт сегмента Piano
Чтобы проверить интеграцию на стороне назначения:
* Импортируйте сегмент Piano.
* Вы должны увидеть новый сегмент (фильтр) с названием, построенным как `segment_key (Piano Autogenerated)`.
* Пересчитайте сегмент, чтобы получить актуальную информацию о текущей обработке устройств.
## Устранение неполадок: Часто задаваемые вопросы
#### Как я могу убедиться, что события правильно отправляются из Pushwoosh в Piano Analytics?
**Решение**: Используйте Stream Inspector от Piano или проверьте Overall Traffic в Piano Analytics для мониторинга входящих событий из Pushwoosh.
#### Что делать, если данные сегмента не импортируются правильно в Pushwoosh?
**Решение**: Убедитесь, что Segment Key из Piano соответствует настройкам в Pushwoosh. Проверьте наличие ошибок в расчетах размера сегмента или при извлечении данных.
#### Могу ли я интегрировать Piano VisitorID с Pushwoosh для расширенной аналитики?
**Решение**: Да, настроив специальный тег в Pushwoosh и используя SDK Piano для получения VisitorID, вы можете синхронизировать идентификаторы пользователей между платформами.
#### Что делать, если возникли проблемы с конфигурацией API-ключей?
**Решение**: Просмотрите журналы запросов API, убедитесь в правильности URL-адресов конечных точек и токенов аутентификации (API-ключей), а также проверьте наличие ошибок на стороне сервера, о которых сообщает любая из служб.
В открывшемся окне введите следующие учетные данные:
1. Site ID
Чтобы найти ваш Site ID, войдите в свой аккаунт Piano и перейдите в **Analytics > Data Collection Portal > Dashboard.** Найдите соответствующий веб-сайт и скопируйте его ID.
2. Collection Domain
Чтобы найти Collection Domain, перейдите в **Tagging > Collection Domains**. Скопируйте ID Collection Domain. Убедитесь, что вы вводите домен сбора в формате **\*\*\*\*.pa-cd.com** без префикса **https://.**
3. Piano API Access и Secret keys
Чтобы получить ключи:
* В вашем аккаунте Piano нажмите на **See profile** под именем вашего аккаунта.
* Перейдите на вкладку **API Keys** и создайте новый ключ с понятным названием и описанием. Затем нажмите **OK**.
* В открывшемся окне скопируйте ваш **Access Key** и **Secret Key**.
* В поле **API key** в Pushwoosh введите **Access Key** и **Secret Key**, разделенные нижним подчеркиванием. Например: **accesskey_secretkey**.
### Создание событий Piano для сопоставления с событиями Pushwoosh
Чтобы отслеживать события, отправленные из Pushwoosh в Piano, вам необходимо вручную создать соответствующие события в Piano.
Вот как это сделать в вашем аккаунте Piano:
1. Перейдите в **Settings > Data management > Data model**.
2. Выберите **Events** и нажмите на значок плюса, чтобы создать новое событие.
3. В открывшемся окне укажите название и описание события, например, _**"pw\_siteopened"**_.
4. В поле **Type** выберите **On-site**.
5. В поле **Categories** выберите **Events**.
6. Нажмите **Save**.
### Установка часового пояса вашего веб-сайта в Piano
Установка правильного часового пояса для вашего веб-сайта в Piano имеет решающее значение для точного отслеживания и анализа данных. Лучшей практикой является согласование часового пояса с местом, откуда вы отправляете события и проводите анализ. Это устраняет расхождения во времени.
Чтобы изменить часовой пояс в Piano, перейдите в **Dashboard** и нажмите на строку с информацией о вашем сайте. Во всплывающем окне нажмите **Edit** и выберите нужный часовой пояс. Затем нажмите **Save**.
### Создание свойства для идентификации событий, отправленных из Pushwoosh в Piano
Чтобы упростить управление данными, создайте в Piano свойство, которое можно будет связать с событиями Pushwoosh. Это позволит вам легко идентифицировать события, отправленные из Pushwoosh.
Вот как создать свойство:
1. В Piano перейдите в **Settings > Data Management > Properties.**
2. Нажмите **Create Property**.
3. В поле **Name** введите **pushwooshid**.
4. В поле **Property Key** введите **pushwooshid**.
5. Установите **Type** на **String**.
6. Нажмите **Save**.
### Проверка отправки событий Pushwoosh в Piano
Чтобы убедиться, что события, настроенные в Pushwoosh, успешно отправляются в Piano, выполните следующие шаги:
1. В вашем аккаунте Piano перейдите в **Explorer > Audience > Overall Traffic**.
2. Создайте сегмент на основе событий, где свойство **pushwooshid** не пустое.
Отфильтрованное представление покажет общую информацию о трафике, включая все связанные события.
Для более детального просмотра событий, отправленных из Pushwoosh, перейдите в **Content > Events**. Этот раздел предоставляет подробную разбивку всех событий, отправленных из Pushwoosh, включая количество раз, когда каждое событие произошло.
### Создание сегментов в Piano
После завершения настройки интеграции вы можете начать анализировать события, отправленные из Pushwoosh, в Piano. Чтобы получить доступ к этим событиям, перейдите в **Explorer > Content > Events** в вашем аккаунте Piano.
Затем [создайте сегменты](https://support.piano.io/hc/en-us/articles/4467486423570-Create-a-segment), используя эти события. При создании сегментов выберите свойство **`pushwooshid`**, которое вы создали ранее, для фильтрации событий.
Убедитесь, что вы дали вашему сегменту понятное и описательное название. **Segment Key**, который является уникальным идентификатором для сохраненного сегмента, понадобится позже для отправки сегментов в Pushwoosh.
### Отправка сегментов из Piano в Pushwoosh
Чтобы Pushwoosh мог получать сегменты из Piano, предоставьте Pushwoosh созданный вами SegmentKey. Чтобы найти SegmentKey для сегмента, перейдите в **Analysis > Library > Segments**. Нажмите на нужный сегмент и скопируйте **Segment Key**.
В разделе Pushwoosh Integrations найдите **Piano** и нажмите **Import Segment**. Затем введите скопированный Segment key.
Если импорт прошел успешно, вы увидите подтверждающее сообщение.
Вы можете получить доступ к импортированным сегментам в Pushwoosh. После завершения импорта они будут перечислены в разделе **Audience > Segments** вашего аккаунта Pushwoosh.
## Сопоставление Piano VisitorID с Pushwoosh UserID/HWID для накопленной аналитики по всем SDK
Если клиент хочет накапливать аналитику как из Pushwoosh SDK, так и из Piano Analytics SDK, Pushwoosh должен сопоставить Piano VisitorID с Pushwoosh UserID/HWID. Решение заключается в отправке тега Piano VisitorID в Pushwoosh для пользователя/устройства.
Для этого выполните следующее:
1. Создайте тег с названием '**Piano Visitor ID**' на стороне Pushwoosh для приложения. Примечание: название тега должно быть точно таким, как описано.
2. На стороне приложения клиента получите Piano Visitor ID в Piano SDK с помощью метода **getVisitorId**.
3. На стороне приложения клиента используйте Pushwoosh SDK для однократного вызова запроса `setTags` со значением тега.
Если значение тега (Piano Visitor ID) существует для пользователя/устройства, Pushwoosh автоматически включит его как Client ID в запросы к Piano Analytics. На стороне Piano Analytics он будет преобразован в уникальное значение visitor ID.
## Примеры кода
##### Web Push SDK (JavaScript)
```javascript
Pushwoosh.push(function(api) {
// Установить теги для пользователя
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}];
}];
```
В целом, Pushwoosh использует теги устройств для предоставления информации об устройстве и другой информации в Piano Analytics в каждом запросе. Вот список часто используемых тегов:
* **Country**
* **Device Model**
* **OS Version**
* **Browser Type** (в некоторых случаях)
## Как проверить, что интеграция работает
#### Источник: Обнаружение событий, отправленных в Piano Analytics
Есть два простых способа обнаружить события, которые были отправлены в Piano Analytics:
##### Stream Inspector
1. Перейдите в ваш аккаунт **Piano Analytics**.
2. Перейдите в **Settings** > **Data Collection Portal** > **Tools** > **Stream Inspector**.
3. Выберите подключенный сайт, который вы хотите проверить.
4. Выберите события, которые вы хотите проверить, и начните сессию.
5. Убедитесь, что события были получены Piano Analytics.
##### Проверка событий в Overall Traffic
1. Перейдите в ваш аккаунт **Piano Analytics**.
2. Перейдите в **Settings** > **Explorer** > **Audience** > **Overall Traffic**.
3. Выберите сайт и диапазон дат в меню ниже.
#### Назначение: Импорт сегмента Piano
Чтобы проверить интеграцию на стороне назначения:
* Импортируйте сегмент Piano.
* Вы должны увидеть новый сегмент (фильтр) с названием, построенным как `segment_key (Piano Autogenerated)`.
* Пересчитайте сегмент, чтобы получить актуальную информацию о текущей обработке устройств.
## Устранение неполадок: Часто задаваемые вопросы
#### Как я могу убедиться, что события правильно отправляются из Pushwoosh в Piano Analytics?
**Решение**: Используйте Stream Inspector от Piano или проверьте Overall Traffic в Piano Analytics для мониторинга входящих событий из Pushwoosh.
#### Что делать, если данные сегмента не импортируются правильно в Pushwoosh?
**Решение**: Убедитесь, что Segment Key из Piano соответствует настройкам в Pushwoosh. Проверьте наличие ошибок в расчетах размера сегмента или при извлечении данных.
#### Могу ли я интегрировать Piano VisitorID с Pushwoosh для расширенной аналитики?
**Решение**: Да, настроив специальный тег в Pushwoosh и используя SDK Piano для получения VisitorID, вы можете синхронизировать идентификаторы пользователей между платформами.
#### Что делать, если возникли проблемы с конфигурацией API-ключей?
**Решение**: Просмотрите журналы запросов API, убедитесь в правильности URL-адресов конечных точек и токенов аутентификации (API-ключей), а также проверьте наличие ошибок на стороне сервера, о которых сообщает любая из служб.