# iOS SDK 高级集成指南

import { Badge } from '@astrojs/starlight/components';

本节提供有关 Pushwoosh iOS SDK 高级集成的信息。

## 后台模式

<Aside type="caution" title="">
默认情况下，iOS 不允许应用在后台时处理推送通知。这包括静默推送通知，它对于在没有用户交互的情况下更新应用数据非常有用。
</Aside>

要启用此功能，您必须将后台模式 (Background Modes) 添加到您的项目中。

#### 启用后台模式的步骤

1. 在 **Xcode** 中打开您的项目，并在 **项目导航器 (Project Navigator)** 中选择它。
2. 从左侧面板中选择您的应用目标。
3. 导航到 **Signing & Capabilities** 选项卡。
4. 点击左上角的 **+ Capability** 按钮。
5. 从列表中搜索并选择 **Background Modes**。
6. 在 **Background Modes** 部分，通过勾选复选框启用 **远程通知 (Remote notifications)**。

完成后，您的应用将能够在后台运行时处理推送通知，包括静默推送。

## 前台模式

默认情况下，当应用在前台运行时，Pushwoosh iOS SDK 会显示通知横幅。

您可以通过在代码中（例如，在您的 `AppDelegate` 中）设置以下布尔标志来控制此行为：

<Tabs syncKey="code-example">
    <TabItem label="Swift">
    ```swift
    // 设置为 false 禁用前台通知，设置为 true 启用
    Pushwoosh.sharedInstance().showPushnotificationAlert = true
    ```

    <LinkCard
        title="示例 (Swift)"
        href="https://github.com/Pushwoosh/pushwoosh-quickstart-ios/blob/main/customizing/customizing/ViewController.swift#L30"
    />

  </TabItem>

  <TabItem label="Objective-C">

  ```objective-c
  // 设置为 0 禁用前台通知，设置为 1 启用
  [[Pushwoosh sharedInstance] setShowPushnotificationAlert:0];
  ```

    <LinkCard
        title="示例 (Objective-C)"
        href="https://github.com/Pushwoosh/pushwoosh-quickstart-ios/blob/main/customizing/customizingObjC/customizingObjC/ViewController.m#L35"
    />

  </TabItem>
</Tabs>

## 日志级别

Pushwoosh iOS SDK 支持以下日志记录级别：

- `NONE` - SDK 不记录任何日志。
- `ERROR` - 仅在控制台中显示错误消息。
- `WARNING` - 除错误外，还显示警告。
- `INFO` - 包括信息性消息（默认设置）。
- `DEBUG` - 包括详细的调试信息。

默认情况下，日志记录级别设置为 INFO，以确保 SDK 提供相关信息而不会使开发者控制台变得混乱。

要修改日志记录级别，请更新应用 `Info.plist` 文件中的 `Pushwoosh_LOG_LEVEL` 键：

```xml
<key>Pushwoosh_LOG_LEVEL</key>
<string>YOUR_LOG_LEVEL</string>
```

或者，您可以使用下面的代码片段更改日志级别：

```swift
Pushwoosh.Debug.setLogLevel(.PW_LL_DEBUG)
```

将 `YOUR_LOG_LEVEL` 替换为所需的级别（例如，`DEBUG` 或 `ERROR`）。

## 自定义 `UNNotificationCenterDelegate`

如果您想使用自己的 `UNNotificationCenterDelegate`（例如，用于本地通知），您应该告知 Pushwoosh SDK 以确保其正常运行。您可以通过 Pushwoosh 实例的 `notificationCenterDelegateProxy` 属性来完成此操作：

<Tabs syncKey="code-example">
    <TabItem label="Swift">
    ```swift
    Pushwoosh.sharedInstance().notificationCenterDelegateProxy?.add(my_delegate)
    ```

    <LinkCard
        title="示例 (Swift)"
        href="https://github.com/Pushwoosh/pushwoosh-quickstart-ios/blob/main/customizing/customizing/Custom%20UNNotificationCenterDelegate/CustomNotificationCDViewConrtoller.swift#L23"
    />

    </TabItem>

    <TabItem label="Objective-C">
    ```objective-c
    [Pushwoosh.sharedInstance.notificationCenterDelegateProxy addNotificationCenterDelegate:my_delegate];
    ```

    <LinkCard
        title="示例 (Objective-C)"
        href="https://github.com/Pushwoosh/pushwoosh-quickstart-ios/blob/main/customizing/customizingObjC/customizingObjC/Custom%20UNNotificationCenterDelegate/PWCustomNotificationCDViewConrtoller.m#L28"
    />

    </TabItem>
</Tabs>

然后，在您的委托中实现 `UNNotificationCenterDelegate` 方法：

<Tabs syncKey="code-example">
  <TabItem label="Swift">

  ```swift
  func userNotificationCenter(
      _ center: UNUserNotificationCenter,
      willPresent notification: UNNotification,
      withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
  ) {
      if (!PWMessage.isPushwooshMessage(notification.request.content.userInfo)) {
          // 处理您的通知
          completionHandler(UNNotificationPresentationOptions.alert)
      }
  }

  func userNotificationCenter(
      _ center: UNUserNotificationCenter,
      didReceive response: UNNotificationResponse,
      withCompletionHandler completionHandler: @escaping () -> Void
  ) {
      if (!PWMessage.isPushwooshMessage(response.notification.request.content.userInfo)) {
          // 处理您的通知
          completionHandler()
      }
  }
  ```

  <LinkCard title="示例 (Swift)" href="https://github.com/Pushwoosh/pushwoosh-quickstart-ios/blob/main/customizing/customizing/Custom%20UNNotificationCenterDelegate/CustomNotificationCDViewConrtoller.swift" />

  </TabItem>

  <TabItem label="Objective-C">

  ```objective-c
  - (void)userNotificationCenter:(UNNotificationCenter *)center
          willPresentNotification:(UNNotification *)notification
          withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler {
      if (![PWMessage isPushwooshMessage:notification.request.content.userInfo]) {
          // 处理您的消息
          completionHandler(UNNotificationPresentationOptionAlert);
      }
  }

  - (void)userNotificationCenter:(UNNotificationCenter *)center
          didReceiveNotificationResponse:(UNNotificationResponse *)response
          withCompletionHandler:(void (^)(void))completionHandler {
      if (![PWMessage.isPushwooshMessage:response.notification.request.content.userInfo]) {
          // 处理您的消息
          completionHandler();
      }
  }
  ```

  <LinkCard title="示例 (Objective-C)" href="https://github.com/Pushwoosh/pushwoosh-quickstart-ios/blob/main/customizing/customizingObjC/customizingObjC/Custom%20UNNotificationCenterDelegate/PWCustomNotificationCDViewConrtoller.m" />

  </TabItem>
</Tabs>

## Pushwoosh 延迟初始化

`Pushwoosh_LAZY_INITIALIZATION` 标志可防止应用启动时自动初始化 Pushwoosh SDK。这使得您可以更好地控制 Pushwoosh SDK 服务的启动时间。

启用此标志后，Pushwoosh SDK 在显式调用 Pushwoosh iOS SDK 方法之前不会启动其服务。

将以下条目添加到 Info.plist 中：

```xml
<key>Pushwoosh_LAZY_INITIALIZATION</key>
<true/>
```

**用例**
1. **受控的 SDK 初始化** – `Pushwoosh_LAZY_INITIALIZATION` 标志允许延迟 Pushwoosh SDK 的启动，从而更好地控制推送服务的激活时间。

2. **延迟推送激活** – 在某些应用中，推送通知只应在特定条件下初始化。启用此标志可确保 Pushwoosh SDK 仅在明确请求时启动。

3. **用户特定的推送配置** – 某些应用可能需要根据用户偏好或账户设置自定义推送通知设置。通过延迟初始化，Pushwoosh SDK 仅在确定适当的配置后才启动。
## Info.plist 属性完整列表

| 属性 | 描述 | 可能的值 |
|---|---|---|
| `Pushwoosh_APPID` | 为生产版本设置 Pushwoosh 应用 ID。 | `XXXXX-XXXXX` <br /> **类型**：字符串 |
| `Pushwoosh_APPID_Dev` | 为开发版本设置 Pushwoosh 应用 ID。 | `XXXXX-XXXXX` <br /> **类型**：字符串 |
| `Pushwoosh_SHOW_ALERT` | 显示通知前台提醒。 | `YES` *（默认）* / `NO` <br /> **类型**：布尔值 |
| `Pushwoosh_ALERT_TYPE` | 设置通知提醒样式。 | `BANNER` *（默认）* / `ALERT` / `NONE` <br /> **类型**：字符串 |
| `Pushwoosh_BASEURL` | 覆盖 Pushwoosh 服务器基础 URL。 | [`https://cp.pushwoosh.com/json/1.3/`](https://cp.pushwoosh.com/json/1.3/) *（默认）* <br /> **类型**：字符串 |
| `Pushwoosh_AUTO_ACCEPT_DEEP_LINK_FOR_SILENT_PUSH` | 如果为 `YES`，在静默推送中收到的 Deep Link 将被自动处理。 | `YES` *（默认）* / `NO` <br /> **类型**：布尔值 |
| `Pushwoosh_ALLOW_SERVER_COMMUNICATION` | 允许 SDK 向 Pushwoosh 服务器发送网络请求。 | `YES` *（默认）* / `NO` <br /> **类型**：布尔值 |
| `Pushwoosh_ALLOW_COLLECTING_DEVICE_DATA` | 允许 SDK 收集设备数据（操作系统版本、区域设置和型号）并发送到服务器。 | `YES` *（默认）* / `NO` <br /> **类型**：布尔值 |
| `Pushwoosh_ALLOW_COLLECTING_DEVICE_OS_VERSION` | 允许 SDK 收集设备的操作系统版本并发送到服务器。 | `YES` *（默认）* / `NO` <br /> **类型**：布尔值 |
| `Pushwoosh_ALLOW_COLLECTING_DEVICE_LOCALE` | 允许 SDK 收集设备区域设置并发送到服务器。 | `YES` *（默认）* / `NO` <br /> **类型**：布尔值 |
| `Pushwoosh_ALLOW_COLLECTING_DEVICE_MODEL` | 允许 SDK 收集设备型号并发送到服务器。 | `YES` *（默认）* / `NO` <br /> **类型**：布尔值 |
| `Pushwoosh_LOG_LEVEL` | Pushwoosh SDK 日志记录级别。有关详细信息，请参阅[控制日志级别](#log-level)。 | `NONE` / `ERROR` / `WARNING` / `INFO` *（默认）* / `DEBUG` / `VERBOSE` <br /> **类型**：字符串 |
| `Pushwoosh_PURCHASE_TRACKING_ENABLED` | 允许 SDK 跟踪应用内购买。Customer Journey Builder 需要此功能。 | `YES` / `NO` *（默认）* <br /> **类型**：布尔值 |