# iOS SDK 7.0+ 高级集成指南

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

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

## 后台模式

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

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


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

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.configure.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 configure] 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 以确保其正常运行。您可以使用 `addNotificationCenterDelegate` 方法来执行此操作：

<Tabs syncKey="code-example">
    <TabItem label="Swift">
    ```swift
    Pushwoosh.configure.addNotificationCenterDelegate(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.configure 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 /> **类型**: 布尔值                                                 |