# iOS SDK 常见问题解答

### iOS 集成常见问题解答

#### 问：如何将 Pushwoosh SDK 安装到我的 iOS 项目中？
您可以使用 Swift Package Manager 或 CocoaPods 来集成 Pushwoosh SDK。

#### 问：如何使用 Swift Package Manager 安装 Pushwoosh SDK？
在 Xcode 中，导航至 **Package Dependencies** 部分，并使用以下 URL 添加包：`https://github.com/Pushwoosh/Pushwoosh-XCFramework`。

#### 问：如何使用 CocoaPods 安装 Pushwoosh SDK？
打开您项目的 `Podfile` 并添加 `pod 'PushwooshXCFramework'` 这一行。然后，在终端中运行 `pod install` 命令。

#### 问：我需要向项目中添加哪些功能来启用推送通知？
在您项目设置的 Signing & Capabilities 部分，您需要添加 `Push Notifications` 和 `Background Modes` 功能。添加 `Background Modes` 时，请确保勾选 `Remote notifications` 复选框。

#### 问：时间敏感通知需要哪些额外功能？
如果您打算使用时间敏感通知 (iOS 15+)，您还需要添加 `Time Sensitive Notifications` 功能。

#### 问：我需要在哪里添加 Pushwoosh 初始化代码？
初始化代码需要添加到您的 `AppDelegate` 类中。

#### 问：在 SwiftUI 的 AppDelegate 中我应该添加什么初始化代码？
请参考[提供的在 SwiftUI 项目中集成 Pushwoosh 的 Swift 代码示例](/zh/developer/pushwoosh-sdk/ios-sdk/setting-up-pushwoosh-ios-sdk/basic-integration-guide/#appdelegate)。


#### 问：在标准的 Swift AppDelegate 中我应该添加什么初始化代码？
请参考[提供的在标准 Swift 项目中集成 Pushwoosh 的 Swift 代码示例](/zh/developer/pushwoosh-sdk/ios-sdk/setting-up-pushwoosh-ios-sdk/basic-integration-guide/#appdelegate)。

#### 问：在 Objective-C AppDelegate 中我应该添加什么初始化代码？
请参考[提供的在 Objective-C 项目中集成 Pushwoosh 的 Objective-C 代码示例](/zh/developer/pushwoosh-sdk/ios-sdk/setting-up-pushwoosh-ios-sdk/basic-integration-guide/#appdelegate)。

#### 问：我需要在我的 Info.plist 文件中添加哪些键？
您需要在应用的 `Info.plist` 文件中添加 `Pushwoosh_APPID` 键（设置为您的 Application Code）和 `PW_API_TOKEN` 键（设置为您的 API Token）。

#### 问：消息送达跟踪的目的是什么？
Pushwoosh 支持使用 Notification Service Extension 跟踪推送通知的送达事件。

#### 问：如何向我的项目中添加 Notification Service Extension？
在 Xcode 中，前往 **File** > **New** > **Target...**，选择 **Notification Service Extension**，然后按 **Next**。输入目标名称并按 **Finish**。当提示激活时，按 **Cancel**。

#### 问：如何将 Pushwoosh SDK 添加到 Notification Service Extension 中？
将[提供的 Swift 或 Objective-C 代码片段](/zh/developer/pushwoosh-sdk/ios-sdk/setting-up-pushwoosh-ios-sdk/basic-integration-guide/#add-pushwoosh-sdk-to-notification-service-extension)添加到您的 Notification Service Extension 的主 `.swift` 或 `.m` 文件中。此代码利用 `PWNotificationExtensionManager` 来处理通知请求。

#### 问：App Groups 的目的是什么？
需要 App Groups 功能以允许 Notification Service Extension 与主应用程序通信。

#### 问：如何为我的主目标和 Notification Service Extension 启用 App Groups？
对于这两个目标，前往 **Signing & Capabilities**，添加 **App Groups** 功能，然后按 + 按钮创建一个新组。确保组名以 `group.` 开头，并为两个目标使用相同的组名。

#### 问：我需要在主目标的 Info.plist 中为 App Groups 添加哪些键？
在您的主目标的 `Info.plist` 中，添加 `PW_APP_GROUPS_NAME` 键，并将其值设置为您的 App Groups 组的名称。

#### 问：我需要在 Notification Service Extension 的 Info.plist 中添加哪些键？
在您的 Notification Service Extension 的 `Info.plist` 中，添加 `PW_APP_GROUPS_NAME` 键（设置为您的 App Groups 名称）和 `Pushwoosh_APPID` 键（设置为您的 Application Code）。

#### 问：如何验证 Pushwoosh 集成？
构建并运行您的项目后，前往 Pushwoosh 控制面板并向您的应用程序发送一条推送通知。您应该会在您的设备上看到该通知。

#### 问：Pushwoosh SDK 中用于处理推送通知的两个主要回调是什么？
两个主要回调是 `onMessageReceived` 和 `onMessageOpened`。

#### 问：`onMessageReceived` 回调何时被调用？
当应用程序接收到推送通知时，会调用 `onMessageReceived` 方法。

#### 问：`onMessageOpened` 回调何时被调用？
当用户与推送通知交互并打开它时，会调用 `onMessageOpened` 方法。

#### 问：如何访问已接收或已打开的推送通知的有效负载？
可以通过 `PWMessage` 对象（传递给 `onMessageReceived` 和 `onMessageOpened` 回调）的 `payload` 属性来访问其有效负载。

#### 问：如何在 Pushwoosh 中设置用户 ID？
使用 `Pushwoosh.sharedInstance()` 对象的 `setUserId(_:)` 方法，将用户 ID 作为参数传递。

#### 问：如何在 Pushwoosh 中设置用户的电子邮件地址？
使用 `Pushwoosh.sharedInstance()` 对象的 `setEmail(_:)` 方法，提供用户的电子邮件。

#### 如何在 Pushwoosh 中将其他用户信息设置为标签？
使用 `Pushwoosh.sharedInstance()` 对象的 `setTags(_:)` 方法，传递一个字典，其中键是标签名，值是相应的标签值。

#### 如何跟踪带有附加属性的用户事件？**
使用 `PWInAppManager.shared()` 的 `postEvent(_:withAttributes:)` 方法，提供事件名称（例如 `"login"`）和属性字典（例如 `"name"`、`"last_login"`）。

#### 问：如何跟踪带有产品详情的用户购买事件？
使用 `PWInAppManager.shared()` 的 `postEvent(_:withAttributes:)` 方法，事件名称为 `"purchase"`，并附带一个包含产品详情的字典，如 `"product_id"`、`"product_name"`、`"price"` 和 `"quantity"`。

#### 问：如何设置一个代理来处理富媒体的呈现？
在您的视图控制器或其他适当的类中，遵循 `PWRichMediaPresentingDelegate` 协议，并将 `PWRichMediaManager.shared()` 的 `delegate` 属性设置为您的遵循实例。

#### 问：如何配置富媒体的呈现样式？
使用 `PWModalWindowConfiguration.shared()` 对象来配置属性，如模态窗口位置，并使用 `configureModalWindow(with:present:dismiss:)` 方法配置呈现/消失动画。

#### 问：在富媒体代理方法中我可以访问哪些信息？**
代理方法提供了对 `PWRichMedia` 对象的访问，该对象包含有关富媒体内容的信息，包括其 `pushPayload`。`presentingDidFailForRichMedia:withError:` 方法还提供一个描述失败的 `Error` 对象。


### 故障排除

<Aside type="caution">
出于负载均衡的目的，我们可能需要更改您应用程序中的 API 端点。这个过程是自动的，并由我们的 SDK 处理。**请确保您应用中没有任何东西阻止访问任何包含 \*.pushwoosh.com 的 URL。**
</Aside>

<Aside type="note">
#### 如果您位于防火墙之后或您的 WiFi 路由器充当防火墙

如果您的设备通过 WiFi 连接到互联网，而消息无法送达设备，请**确保您的防火墙没有阻止 APNs 端口。**\
推送提供商、iOS 设备和 Mac 电脑通常位于防火墙之后。要发送通知，您需要允许通过端口 2195 的入站和出站 TCP 数据包。通过 **Wi-Fi 连接到推送服务的设备和电脑需要允许通过端口 5223 的入站和出站 TCP 数据包。**\
推送服务的 IP 地址范围可能会更改；提供商应通过主机名而不是 IP 地址连接。推送服务使用负载均衡方案，为同一主机名产生不同的 IP 地址。但是，整个 17.0.0.0/8 地址块都分配给了 Apple，因此您可以在防火墙规则中指定该范围。
</Aside>

#### 问：“您的置备配置文件没有 APS 条目”错误

如果您看到“您的置备配置文件没有 APS 条目。”错误消息，请确保您的置备配置文件与推送兼容，并且其中包含 `aps-environment` 字符串，其值为 `production` 或 `development`。最简单的检查方法是在任何文本编辑器中打开移动置备配置文件，并查找 `aps-environment` 字符串。它应该在那里。

如果它存在，而您仍然收到该错误，这意味着 XCode 仍然选择了一个“不兼容推送”的配置文件。请确保您使用正确的配置文件进行签名——有时如果您有同一个 App ID 的两个配置文件，XCode 会搞混并使用旧的配置文件进行签名。

推荐的步骤是：

1. [移除](https://stackoverflow.com/questions/18923095/delete-provisioning-profile-from-xcode-5)所有 XCode 配置文件；
2. 添加唯一的那个新配置文件；
3. 重新构建应用。

#### 问：iOS 推送令牌和 hwid 是什么样的？

iOS 设备推送令牌是包含 64 个十六进制符号的字符串。推送令牌示例：\
`03df25c845d460bcdad7802d2vf6fc1dfde97283bf75cc993eb6dca835ea2e2f`\
在 API 请求中针对特定设备时，请确保您使用的 iOS 推送令牌是**小写**的。

Pushwoosh 使用 IDFV 作为设备 HWID。请注意，如果用户重新安装来自特定供应商的所有应用，它可能会更改。

`CBAF8ED1-17FB-49A3-73BD-DC79B63AEF93`

#### 问：当我的应用运行时，如何开启和关闭横幅？

默认情况下，我们最新的 iOS SDK 会在应用在前台运行时显示通知横幅。\
您可以通过更改 Info.plist 中的以下标志来控制此行为：

标志 `Pushwoosh_ALERT_TYPE` – 字符串类型，值为：

* `BANNER` – 默认值，显示横幅应用内提醒
* `ALERT` – 提醒通知
* `NONE` – 应用在前台时不显示通知

#### 问：如何获取我的 iOS 设备推送令牌以在测试设备中使用？

要获取您的 iOS 设备推送令牌，

1. 打开 Xcode => Devices & Simulators；
2. 将测试设备连接到您的电脑；
3. 在左侧的设备列表中选择您连接的设备；
4. 点击 Open Console 按钮。

<img src="/ios-push-notifications-ios-faq-1.webp" alt=""/>

启动您需要设备推送令牌的应用程序，并在“Registered for push notifications”行中找到您的 64 个十六进制字符的设备推送令牌：

<img src="/ios-push-notifications-ios-faq-2.webp" alt=""/>

#### 问：为什么在我卸载应用并在短时间内重新安装后，角标没有被清除？

这是预期行为——角标由 iOS 本身处理，其值存储在应用程序首选项中，当您卸载应用时不会立即移除。在立即重新安装的情况下，角标值会保留一段时间，导致应用重新安装后显示相同的角标。