# Piano Analytics 集成
[Piano Analytics](https://piano.io/product/analytics/) 是一款帮助企业了解人们如何与其网站和应用互动的工具。它收集有关用户行为的数据，并通过报告和可视化提供洞察。这些信息帮助企业就如何改进其数字产品和营销工作做出更好的决策。
集成 [Piano Analytics](https://piano.io/product/analytics/) 和 Pushwoosh 可以获得详细的用户行为洞察，以创建精确的细分，并在正确的时间向正确的用户发送高度定向的推送通知、电子邮件和应用内消息。
## 集成概述
### 集成类型
* **目标**：数据从 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 相结合，以获得全面的用户洞察。这使您能够全面了解用户在多个触点上的行为和互动。
**细分**
基于 Piano Analytics 数据，在 Pushwoosh 中创建有针对性的用户细分。利用这种增强的细分来提供个性化且有效的营销活动。
**性能监控**
跨平台跟踪活动效果和用户互动。
### 集成如何工作？
##### 流程概述
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 将跟踪数据（例如，推送已发送、推送已送达）发送到 Piano Analytics。
* 这些数据通过交付和互动指标丰富了 Piano Analytics。
3. **Piano VisitorID 集成**：
* 可选地，将 Piano VisitorID 与 Pushwoosh 集成，以实现跨 SDK 的统一分析。
## 设置集成
要设置集成，请在您的 Pushwoosh 账户中前往 **Settings > 3rd Party Integrations**，找到 **Piano**。点击 **Configure**。
在打开的窗口中，提供以下凭据：
1. 站点 ID
要找到您的站点 ID，请登录您的 Piano 账户，然后前往 **Analytics > Data Collection Portal > Dashboard**。找到相关网站并复制其 ID。
2. 收集域
要找到收集域，请导航至 **Tagging > Collection Domains**。复制收集域 ID。请确保以 **\*\*\*\*.pa-cd.com** 格式输入收集域，不带 **https:// 前缀**。
3. Piano API 访问密钥和私钥
要获取密钥：
* 在您的 Piano 账户中，点击您账户名称下方的 **See profile**。
* 导航至 **API Keys** 选项卡，并创建一个具有清晰名称和描述的新密钥。然后点击 **OK**。
* 在打开的窗口中，复制您的 **Access Key** 和 **Secret Key**。
* 在 Pushwoosh 的 **API key** 字段中，输入 **Access Key** 和 **Secret Key**，并用下划线分隔。例如：**accesskey_secretkey**。
### 创建 Piano 事件以匹配 Pushwoosh 事件
要在 Piano 中跟踪从 Pushwoosh 发送的事件，您需要在 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**。
### 为在 Piano 中识别从 Pushwoosh 发送的事件创建属性
为了使数据管理更容易，请在 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 中创建细分
完成集成设置后，您就可以开始在 Piano 中分析从 Pushwoosh 发送的事件。要访问这些事件，请在您的 Piano 账户中导航至 **Explorer > Content > Events**。
然后使用这些事件[创建细分](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 集成部分，找到 **Piano** 并点击 **Import Segment**。然后，输入您复制的 Segment key。
如果导入成功，您将看到一条确认消息。
您可以在 Pushwoosh 中访问您导入的细分。导入完成后，它们将列在您 Pushwoosh 账户的 **Audience > Segments** 部分。
## 跨 SDK 映射 Piano VisitorID 到 Pushwoosh UserID/HWID 以进行累积分析
如果客户希望累积来自 Pushwoosh SDK 和 Piano Analytics SDK 的分析数据，Pushwoosh 需要将 Piano VisitorID 映射到 Pushwoosh UserID/HWID。解决方案是为用户/设备向 Pushwoosh 发送一个 Piano VisitorID 标签。
为此，请执行以下操作：
1. 在 Pushwoosh 端为应用程序创建一个名为“**Piano Visitor ID**”的标签。注意：标签名称必须与描述完全一致。
2. 在客户端的应用程序端，使用 **getVisitorId** 方法在 Piano SDK 中获取 Piano Visitor ID。
3. 在客户端的应用程序端，使用 Pushwoosh SDK 调用一次带有标签值的 `setTags` 请求。
如果用户/设备存在该标签值（Piano Visitor ID），Pushwoosh 将在向 Piano Analytics 的请求中自动将其作为客户端 ID 包含。在 Piano Analytics 端，它将被转换为唯一的访客 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 接收。
##### 在总体流量中检查事件
1. 前往您的 **Piano Analytics** 账户。
2. 导航至 **Settings** > **Explorer** > **Audience** > **Overall Traffic**。
3. 在下方的菜单中选择站点和日期范围。
#### 目标：导入 Piano 的细分
要验证目标端的集成：
* 导入 Piano 的细分。
* 您应该会看到一个名为 `segment_key (Piano Autogenerated)` 的新细分（过滤器）。
* 重新计算细分以获取有关当前设备处理的最新信息。
## FAQ 故障排除：常见问题
#### 如何确保事件从 Pushwoosh 正确发送到 Piano Analytics？
**解决方案**：使用 Piano 的 Stream Inspector 或在 Piano Analytics 中检查总体流量，以监控来自 Pushwoosh 的传入事件。
#### 如果细分数据未正确导入到 Pushwoosh 中，我该怎么办？
**解决方案**：确保来自 Piano 的 Segment Key 与 Pushwoosh 中的设置匹配。检查细分大小计算或数据检索中是否有任何错误。
#### 我可以将 Piano VisitorID 与 Pushwoosh 集成以增强分析吗？
**解决方案**：是的，通过在 Pushwoosh 中设置特定标签并使用 Piano 的 SDK 获取 VisitorID，您可以在平台之间同步用户 ID。
#### 如果 API 密钥配置出现问题，我该怎么办？
**解决方案**：审查 API 请求日志，确保端点 URL 和身份验证令牌（API 密钥）正确，并检查任一服务报告的任何服务器端错误。