# Singular 集成

<Aside type="caution" icon="setting" title="需要开发者协助">
您将需要开发团队的帮助来设置此集成。请与他们分享本指南。
</Aside>

## 集成概述

[Singular](https://www.singular.net/) 是一个营销分析和归因平台。将其与 Pushwoosh 连接，可以对来自您的推送营销活动的应用程序打开进行归因，并在 Singular 中与其他营销渠道一起衡量推送性能。您还可以通过回传将归因数据从 Singular 发送到 Pushwoosh，并将其用于细分和消息传递。

### 使用场景

*   **推送通知归因：** 当用户点击您的通知时，在 Singular 中对来自 Pushwoosh 推送营销活动的应用程序打开进行归因。
*   **营销活动性能分析：** 在 Singular 分析仪表板中，将推送营销活动的结果与其他营销渠道进行比较。
*   **ROI 优化：** 在 Singular 中识别您表现最佳的推送营销活动，并在 Pushwoosh 中规划新营销活动时应用这些见解。
*   **在 Pushwoosh 中进行细分：** 使用来自 Singular 回传的安装和应用内事件数据，在 Pushwoosh 中构建细分并个性化营销活动。

### 前提条件

*   有效的 Pushwoosh 帐户
*   有效的 Singular 帐户
*   已将 Singular SDK 集成到您的应用程序中
*   来自您 Pushwoosh 帐户的 [Application Code](/zh/developer/api-reference/api-identifiers/#application-code) 和 [API Access Token](/zh/developer/api-reference/api-identifiers/#api-access-token)

<Aside type="note" title="最低 Singular SDK 版本">
*   Android：Singular Android SDK 12.11.0 或更高版本（旧版本不支持推送有效负载归因）
*   iOS：Singular iOS SDK 12.0.5 或更高版本
</Aside>

### 集成类型

*   **源 (Pushwoosh → Singular)：** 归因数据通过 Singular 跟踪链接从设备上的推送有效负载传递到 Singular。
*   **目标 (Singular → Pushwoosh)：** Singular 通过回传将归因数据发送到 Pushwoosh。Pushwoosh 将其存储为标签和事件，用于细分和分析。

### 工作原理

##### 推送归因 (Pushwoosh → Singular)

1.  Pushwoosh 发送一个带有 Singular 跟踪链接作为深层链接的推送。
2.  用户点击通知。
3.  应用程序将链接传递给 Singular SDK。
4.  Singular 将此次打开记录为归因于您的推送营销活动。

##### 回传 (Singular → Pushwoosh)

1.  用户安装应用程序，通过跟踪链接重新互动，或触发 Singular 归因的应用内事件。
2.  Singular 向 Pushwoosh 发送带有归因数据的回传。
3.  Pushwoosh 将数据作为标签和事件存储在用户个人资料中。
4.  您在 Pushwoosh 中使用这些数据进行细分、分析和营销活动。

## 为您的应用程序配置链接

通过在 Singular 中创建合作伙伴链接来开始 Pushwoosh 和 Singular 的集成。无论您使用回传、推送归因还是两者都用，此步骤都是必需的。

1.  在您的 Singular 帐户中，转到 **Attribution Setup** → **Manage Links**。

<img src="/integrations-singular-integration-2.webp" alt="用于创建合作伙伴跟踪链接的 Singular 归因设置管理链接页面"/>

2.  选择 **Link Type** → **Partner**，并选择 **Pushwoosh** 作为 **Source Name**。输入一个 **Tracking Link Name**，以便您可以在 Singular 分析中识别此链接。它在报告中显示为 **Tracker Name**。

<img src="/integrations-singular-integration-3.webp" alt="Singular 合作伙伴链接表单，其中包含 Pushwoosh 源、跟踪链接名称字段和生成按钮"/>

3.  在 **Link Settings and Redirects** 中，定义此链接适用于哪个应用程序以及用户点击后会跳转到哪里。[了解更多](https://support.singular.net/hc/en-us/articles/13000445013531-How-to-Build-Tracking-Links)。

4.  在 **Attribution Settings** 中，为此链接配置归因方法和窗口。[了解更多](https://support.singular.net/hc/en-us/articles/13000445013531-How-to-Build-Tracking-Links#links_attribution_settings)。

5.  点击 **Generate**。

6.  在 **Link Summary** 中，查看生成的链接。如果您正在设置[推送归因](#set-up-push-attribution-in-pushwoosh)，请复制 **Click-through tracking link**。您将在 Pushwoosh 中使用它。

<img src="/integrations-singular-integration-6.webp" alt="Singular 链接摘要部分，其中突出显示了点击跟踪链接"/>

## 在 Pushwoosh 中设置推送归因

将 Singular 跟踪链接添加到您的推送通知中。

将您的 **Link Summary** 中的 **Click-through tracking link** 粘贴到 [Push preset](/zh/product/content/push-presets/#define-the-next-step-for-users-who-click-on-the-notification) 的 **On-click actions** → **Deep link in application** 中。

<img src="/integrations-singular-integration-1.webp" alt="推送通知的点击操作，其中 Singular 跟踪链接作为应用程序中的深层链接输入"/>

## 配置回传

Singular 收集关于用户来源和他们在应用内行为的归因数据。通过回传，您可以自动将这些数据发送到 Pushwoosh。

例如，如果 Singular 记录到用户从某个特定的广告活动安装了应用，Pushwoosh 可以将其作为标签或事件接收。然后，您可以构建一个来自该活动的用户细分，并在 Pushwoosh 中向他们发送有针对性的推送。

1.  在 Singular 中，转到 **Partner Configuration**。
2.  创建一个新配置或编辑现有配置。

<img src="/integrations-singular-integration-4.webp" alt="用于创建或编辑 Pushwoosh 回传配置的 Singular 合作伙伴配置页面"/>

3.  输入您的 Pushwoosh **Application Code** 和 **API Access Token**。

<Aside type="note" title="在哪里找到您的凭据">
*   **Application Code** (XXXXX-XXXXX)：显示在 Pushwoosh 控制面板中您的应用程序名称下方。
*   **API Access Token：** 转到 **Settings** → **API Access** 并复制令牌。有关详细信息，请参阅 [API Access Token](/zh/developer/api-reference/api-access-token/)。
</Aside>

<img src="/integrations-singular-integration-5.webp" alt="Singular 回传配置表单，其中包含 Pushwoosh Application Code 和 API Access Token 字段"/>

4.  在 **Attribution Postbacks** 中，选择 Singular 发送给 Pushwoosh 的事件：

*   **Install：** 在 Singular 中归因的新应用安装。Pushwoosh 使用此数据记录用户来源。
*   **Re-engagement：** 归因于跟踪链接的应用打开。如果您希望在 Pushwoosh 中获取再互动来源数据以进行细分，请启用此选项。

   在 Singular 帮助中心[了解如何配置合作伙伴设置和回传](https://support.singular.net/hc/en-us/articles/360053018851-How-to-Configure-Partner-Settings-and-Postbacks)。

<img src="/integrations-singular-integration-7.webp" alt="Singular 归因回传表，其中包含 Pushwoosh 的安装和再互动选项"/>

5.  在 **Attribution Windows Settings** 的 **Installs** 下，选择在用户点击您的跟踪链接或查看广告后，Singular 可以等待多长时间才停止将安装归因于 Pushwoosh。[了解更多](https://support.singular.net/hc/en-us/articles/115000526963-Understanding-Singular-Mobile-App-Attribution)。

6.  在 **Re-engagements** 下，选择在点击或广告查看后，Singular 可以等待多长时间才停止将打开归因于 Pushwoosh。启用 **Override app level inactivity window for this partner** 以设置用户必须处于非活动状态多长时间，该打开才算作一次再互动。[了解更多](https://support.singular.net/hc/en-us/articles/360044494651-Re-engagement-FAQ)。

7.  打开 **In app Events Postback** 选项卡，并添加 Pushwoosh 应接收的事件（例如，会话的 `__SESSION__*`）。启用 **Send All** 以包含来自任何来源的用户。

8.  保存配置。

### Pushwoosh 接收的内容

保存后，当配置的事件发生时，Singular 会发送回传。Pushwoosh 将每个回传处理为设备 **Tags** 和用户个人资料上的一个 **Event**。

<Tabs>
<TabItem label="标签">

Pushwoosh 在匹配的设备上写入或更新这些标签：

| 标签 | 来源 |
| :-- | :----- |
| OS Version | 设备操作系统版本 |
| Application Version | 应用版本 |
| Device Model | 设备型号 |
| Country | 归因国家 |
| City | 归因城市 |

</TabItem>
<TabItem label="事件">

Pushwoosh 在用户个人资料上记录一个事件。事件名称取决于回传类型：

*   **应用内事件：** 您配置的 Singular 事件名称（例如，会话事件）。
*   **安装或归因回传：** 如果回传不带事件名称，Pushwoosh 会记录 `Singular Attribution Event`。当您构建新归因用户的细分时，请使用此事件名称。

营销活动和收入数据作为**事件属性**随事件一起传输。您可以在 Pushwoosh 中对它们进行细分和筛选：

| 属性 | 描述 |
| :-------- | :---------- |
| Campaign name / Campaign ID | 归因的营销活动 |
| Subcampaign name / Subcampaign ID | 归因的子营销活动 |
| Creative name / Creative ID | 归因的创意 |
| Amount / Revenue / Currency | 事件的货币价值（如果有） |
| Country / City | 事件报告的位置 |

</TabItem>
</Tabs>

<Aside type="note" title="设备匹配">
Pushwoosh 使用 Singular 发送的标识符将每个回传与设备匹配：iOS 上的 IDFV，或 Android 上的 GAID、AIFA 或 Android ID。回传还必须包含您的 Application Code 和平台。如果 Pushwoosh 无法匹配设备，则不会应用该回传。
</Aside>

### 验证回传

在 Singular 为配置的事件发送回传后，请检查 Pushwoosh 是否已收到它：

1.  打开 **Audience → Events** 并确认事件出现。
2.  在 [User Explorer](/zh/product/audience-data-and-segmentation/user-explorer/) 中打开用户个人资料，然后转到 [Events history](/zh/product/audience-data-and-segmentation/user-explorer/#events-history-tab)。确认该事件及其属性（例如，Campaign name）已为该用户记录。
3.  事件通常在几分钟内出现。

## 问题排查

### 未捕获 Singular 跟踪链接

*   验证 **Click-through tracking link** 是否设置在 **On-click actions** → **Deep link in application** 中，而不是在 **Custom Data** 中。
*   确认 Singular SDK 已配置为处理推送通知有效负载。请参阅 [Android](https://support.singular.net/hc/en-us/articles/35427027157275-Android-SDK-Supporting-Push-Notifications) 和 [iOS](https://support.singular.net/hc/en-us/articles/42098616285339-iOS-SDK-Configuration-Methods-Reference) 指南。

### 深层链接打开了应用但导航至主屏幕

*   确认 Singular 跟踪链接中的 `_dl` 参数已正确进行 URL 编码。
*   验证您的应用的深层链接处理程序是否已为所用方案（例如 `myapp://`）正确注册。
*   在 Android 上，检查 `AndroidManifest.xml` 中正确的 `Activity` 是否具有您的深层链接方案的意图过滤器。

### 归因出现在 Singular 中但归因到了错误的营销活动

*   确保 Singular SDK 在初始化之前或期间处理推送有效负载，如 Singular SDK 指南中所述。
*   确认您正在为此营销活动使用来自 **Link Summary** 的正确 **Click-through tracking link**。

### 温启动（应用已打开）：未记录归因

*   确认您的应用在后台运行时能处理推送通知点击，如 Singular SDK 指南中所述。
*   这是温启动归因缺失的最常见原因。