# App Store 订阅跟踪

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

## 集成概述

[App Store 服务器通知](https://developer.apple.com/documentation/appstoreservernotifications)是 Apple 的服务器到服务器服务，每当订阅状态发生变化时，它会向您的后端发送实时消息。

通过将 App Store 服务器通知连接到 Pushwoosh，您可以对整个订阅生命周期做出反应，包括购买、续订、取消、账单问题、到期和退款——而无需构建自己的后端基础设施。每当用户 App Store 帐户中的订阅状态发生变化时，Apple 都会通知 Pushwoosh，然后 Pushwoosh 会在用户个人资料上触发匹配的 [`PW_Subscription*`](#tracked-events) 事件。

<Aside type="note">
此集成支持 **iOS 订阅**（App Store 服务器通知 V2）。要跟踪 Android 订阅，请参阅 [Google Play 订阅跟踪](/zh/product/integrations/google-play-subscription-tracking/)。
</Aside>

### 集成类型

**来源：** App Store 服务器通知从 Apple 发送到 Pushwoosh。

### 跟踪的事件

Pushwoosh 将每个支持的 App Store 通知映射到一个统一的 `PW_Subscription*` 事件集，因此您可以在订阅生命周期的任何阶段触发营销活动。

| 事件 | 触发时机 |
| ----- | ---------- |
| `PW_SubscriptionStart` | 用户首次购买订阅。 |
| `PW_SubscriptionRenew` | 订阅自动续订一个新的计费周期。 |
| `PW_SubscriptionCancel` | 用户关闭自动续订。订阅在到期前保持有效。 |
| `PW_SubscriptionResume` | 用户重新启用自动续订，或在订阅失效前重新订阅。 |
| `PW_SubscriptionBillingIssue` | 续订付款失败，订阅进入 Apple 的账单重试期。 |
| `PW_SubscriptionRecovered` | 之前失败的续订成功，订阅再次变为有效状态。 |
| `PW_SubscriptionExpired` | 订阅已完全失效，不再有效。 |
| `PW_SubscriptionRefund` | Apple 退还购买款项或撤销访问权限。 |

每个事件都带有相同的属性：

- **productID：** 订阅的 App Store 产品标识符。
- **expiresAt：** 当前付费周期结束的时间，以秒为单位的 Unix 时间戳。当 Apple 提供此信息时包含在内。

<details>

<summary>事件如何映射到 App Store 服务器通知</summary>

对于验证集成的开发者，每个 Pushwoosh 事件对应这些 App Store `notificationType`（和 `subtype`）值：

| Pushwoosh 事件 | `notificationType` / `subtype` |
| --------------- | ------------------------------ |
| `PW_SubscriptionStart` | `SUBSCRIBED` / `INITIAL_BUY` |
| `PW_SubscriptionRenew` | `DID_RENEW` |
| `PW_SubscriptionCancel` | `DID_CHANGE_RENEWAL_STATUS` / `AUTO_RENEW_DISABLED` |
| `PW_SubscriptionResume` | `DID_CHANGE_RENEWAL_STATUS` / `AUTO_RENEW_ENABLED`, `SUBSCRIBED` / `RESUBSCRIBE` |
| `PW_SubscriptionBillingIssue` | `DID_FAIL_TO_RENEW` |
| `PW_SubscriptionRecovered` | `DID_RENEW` / `BILLING_RECOVERY` |
| `PW_SubscriptionExpired` | `EXPIRED` |
| `PW_SubscriptionRefund` | `REFUND`, `REVOKE` |

其他通知类型，如价格上涨、计划变更、暂停和消费请求，会被确认但不会发布事件。

</details>


### 工作原理

1.  用户 App Store 帐户中的订阅状态发生变化（购买、续订、取消等）。
2.  Apple 向您的 Pushwoosh 通知 URL 发送一个 App Store 服务器通知 (V2)。
3.  Pushwoosh 解码签名的有效负载并从交易中读取 `appAccountToken`。
4.  Pushwoosh 查找 HWID 与该令牌匹配的设备，找到与其绑定的用户，并为该用户发布匹配的 `PW_Subscription*` 事件。

<Aside type="caution" title="重要">
App Store 交易与 Pushwoosh 用户之间的匹配依赖于 `appAccountToken`。如果您的应用在购买时未设置此令牌，Pushwoosh 会收到通知，但**不会发布任何事件**。请参阅[如何设置 `appAccountToken`](#set-appaccounttoken-to-the-devices-pushwoosh-hwid)。
</Aside>

### 使用案例

**赢回流失的订阅者：** 禁用自动续订并不会立即终止访问权限。订阅在付费周期结束前保持有效，这是您赢回用户的窗口。在 `PW_SubscriptionCancel` 事件发生时，启动一个 [Customer Journey](/zh/product/customer-journey/pushwoosh-journey-overview/)，发送一个挽留推送、一封关于他们将失去的功能的[电子邮件](/zh/product/messaging-channels/emails/)，或在访问权限失效前发送一个带有续订折扣的[应用内消息](/zh/product/messaging-channels/in-apps/)。

**引导新订阅者：** 在 `PW_SubscriptionStart` 事件发生时触发一个欢迎系列，帮助用户尽早从他们的计划中获得价值，并为续订做好准备。

**挽救失败的付款：** 当 `PW_SubscriptionBillingIssue` 事件触发时，表示续订付款未成功，订阅正处于 Apple 的重试窗口期。提示用户在失去访问权限前更新他们的支付方式，并在问题解决后通过 `PW_SubscriptionRecovered` 事件跟进确认。

**重新吸引失效用户：** 在 `PW_SubscriptionExpired` 事件发生时，为已完全流失的订阅者启动一个重新激活活动，提供回归客户优惠。


## 设置集成

### 将 `appAccountToken` 设置为设备的 Pushwoosh HWID

Pushwoosh 通过设备的 **HWID** 识别正确的用户，因此您的应用在通过 StoreKit 购买订阅时，必须将设备的 Pushwoosh HWID 作为 `appAccountToken` 附加。

默认情况下，Pushwoosh iOS SDK 使用设备的 `identifierForVendor` (IDFV) 作为 HWID。IDFV 已经是一个 `UUID`，这正是 Apple 对 `appAccountToken` 要求的格式。然后，Pushwoosh 会自动解析当前绑定到该设备的用户，因此无论您是否使用 `setUserId` 分配自己的用户 ID，此方法都有效。

<Tabs>
<TabItem label="StoreKit 2">
```swift
// 将设备的 Pushwoosh HWID（默认为 IDFV）作为 appAccountToken 附加
var options: Set<Product.PurchaseOption> = []
if let hwid = UIDevice.current.identifierForVendor {
    options.insert(.appAccountToken(hwid))
}

let result = try await product.purchase(options: options)
```
</TabItem>
<TabItem label="StoreKit 1">
```swift
// applicationUsername 必须是 UUID 字符串才能填充 appAccountToken
let payment = SKMutablePayment(product: product)
payment.applicationUsername = UIDevice.current.identifierForVendor?.uuidString
SKPaymentQueue.default().add(payment)
```
</TabItem>
</Tabs>

<Aside type="caution">
如果您的应用覆盖了 Pushwoosh HWID（例如，通过 [`PushwooshKeychain`](/zh/developer/pushwoosh-sdk/ios-sdk/ios-keychain/) 持久化 HWID 模块或自定义值），请将 `appAccountToken` 设置为相同的 HWID。该令牌必须与 Pushwoosh 中的设备 HWID 匹配，否则无法归因事件。
</Aside>

### 查找您的 Pushwoosh 应用代码

在 Pushwoosh 控制面板中打开您的应用。您的**应用代码**（格式为 `XXXXX-XXXXX`）显示在侧边栏的项目名称下方。

您将需要应用代码来构建通知 URL。

### 在 App Store Connect 中添加通知 URL

1.  在 [App Store Connect](https://appstoreconnect.apple.com/) 中，转到 **应用 → 您的应用 → App 信息**（在*通用*下），然后滚动到 **App Store 服务器通知**。
2.  选择**版本 2** 通知。
3.  将**生产服务器 URL** 和**沙盒服务器 URL** 都设置为：

```
https://appstore-notifications.pushwoosh.com/appstore/YOUR_APPLICATION_CODE/
```

4.  将 `YOUR_APPLICATION_CODE` 替换为上一步中的应用代码。保留末尾的斜杠。

<Aside type="note">
如果您的帐户托管在**美国数据中心**，请改用 `https://appstore-notifications.pushwoosh.us/appstore/YOUR_APPLICATION_CODE/`。如果您不确定您的帐户使用哪个数据中心，请联系您的客户成功经理或 [Pushwoosh 支持](https://www.pushwoosh.com/contact-us/)。
</Aside>

### 在 Pushwoosh 中确认事件

Pushwoosh 会在您的项目中首次发生时注册每个 `PW_Subscription*` 事件，并附带 `productID` 和 `expiresAt` 属性。在沙盒测试后，打开**受众 → 事件**以验证事件是否出现。然后它们就可以用于分群、统计和 Customer Journey。

### 构建您的营销活动

创建一个 [Customer Journey](/zh/product/customer-journey/pushwoosh-journey-overview/)，在任何 `PW_Subscription*` 事件上设置[基于触发器的入口](/zh/product/customer-journey/journey-elements/entry-elements/trigger-based-entry/)，例如用于赢回的 `PW_SubscriptionCancel` 或用于引导的 `PW_SubscriptionStart`，并添加您想要发送的消息。

## 测试

App Store 服务器通知可以在 Apple 的**沙盒**环境中触发。要验证集成：

1.  按照上述说明设置 `appAccountToken`，进行一次沙盒订阅购买。这将触发 `PW_SubscriptionStart`。
2.  从设备的订阅管理屏幕禁用自动续订。这将触发 `PW_SubscriptionCancel`。
3.  在 Pushwoosh 控制面板中，打开用户个人资料并转到[事件历史](/zh/product/audience-data-and-segmentation/user-explorer/#events-history-tab)。
4.  确认事件在片刻之内出现。