> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 移动 SDK 故障排除

> 解决常见的 OneSignal 移动 SDK 问题，包括 iOS、Android 和跨平台框架中的推送传递失败、APNS 错误和应用内消息问题。

<Note>
  如果您的网站出现问题，请参阅[网页推送故障排除指南](./troubleshooting-web-push)。
</Note>

## 故障排除步骤

### 查看设置说明并更新 SDK

我们经常[发布更新](https://github.com/OneSignal/sdks)，包含错误修复、改进和对最新操作系统更改的支持。确保您使用的是最新 SDK 版本并已遵循设置说明。

<Card title="移动 SDK 设置" icon="wrench" href="./mobile-sdk-setup">
  旨在帮助预防常见问题并测试集成的设置说明。
</Card>

### 查看常见故障排除指南

<Columns cols={2}>
  <Card title="通知未显示或延迟" icon="bell-slash" href="./notifications-show-successful-but-are-not-being-shown">
    推送通知未出现在设备上或有延迟。
  </Card>

  <Card title="通知图像未显示" icon="image" href="./notification-images-not-showing">
    图像未出现在通知的展开视图中。
  </Card>

  <Card title="通知点击率" icon="arrow-pointer" href="./notification-ctr">
    通知的点击率低或无点击。
  </Card>

  <Card title="重复通知" icon="copy" href="./duplicated-notifications">
    通知在设备上多次显示。
  </Card>

  <Card title="应用内消息故障排除" icon="message" href="./in-app-message-troubleshooting">
    应用内消息未按预期显示或运行。
  </Card>
</Columns>

### 检查您的应用是否存在常见问题

#### 阻止推送显示的 OneSignal 方法

检查您的应用是否有 `optOut()` 之类的方法，例如 `OneSignal.User.pushSubscription.optOut()`，或者您是否通过 REST API 设置了 `enabled: false`。这会将推送订阅状态设置为 `unsubscribed`。详情请参阅 [Mobile SDK 参考](./mobile-sdk-reference#optout-%2C-optin-%2C-optedin)。

如果在发送推送时应用处于打开状态，您可能通过 `preventDefault()` 方法阻止了推送显示。这通常在[前台事件监听器](./mobile-sdk-reference#addforegroundlifecyclelistener-push)或 [Android 通知服务扩展](./service-extensions)中设置。

#### Firebase Messaging 或其他 SDK 冲突

如果您的应用还包含 Firebase Messaging SDK 或其他推送通知 SDK，请验证它不会在 OneSignal 处理消息之前拦截消息。

此问题通常发生在以下情况：

* 通知在 OneSignal 中显示为**已送达**，但从未出现在设备上。
* 应用同时包含 OneSignal 和 `firebase_messaging`（或自定义 `FirebaseMessagingService`）。
* 移除 Firebase Messaging 后推送正常，但两个 SDK 同时存在时失败。

1. 检查您的 `AndroidManifest.xml` 中是否有旧版 Firebase 接收器，例如 `com.google.firebase.iid.FirebaseInstanceIdReceiver`，如果 OneSignal 负责推送传递，请将其删除/有条件地排除。

2. 检查是否有覆盖 `onMessageReceived` 的自定义 `FirebaseMessagingService` 实现（或 Flutter 中的 `firebase_messaging` 等库）。如果另一个服务完全处理或抑制了消息，它可能会在 OneSignal 显示通知之前消费 FCM 有效载荷。

3. 避免调用 Firebase 令牌管理 API，例如：`FirebaseMessaging.getToken()` 或 `FirebaseMessaging.deleteToken()`。

如果 OneSignal 负责推送传递，它应该是唯一管理推送令牌生命周期的 SDK。直接获取或管理 FCM 令牌可能导致令牌所有权冲突和不一致的传递行为。

如果您需要为其他系统获取设备推送令牌，请从 OneSignal 读取（例如 `User.pushSubscription.token`），并使用 [SDK 的观察者 API](./mobile-sdk-reference#addobserver-push-subscription-changes) 监听订阅/令牌变化。

### 测试您 SDK 的示例项目

检查您的问题是否可以使用我们工程团队为每个 SDK 维护的示例项目重现。

* [iOS example project](https://github.com/OneSignal/OneSignal-iOS-SDK/tree/main/OneSignalSwiftUIExample)
* [Android example project](https://github.com/OneSignal/OneSignal-Android-SDK/tree/main/examples)
* [Cordova variants example project](https://github.com/OneSignal/OneSignal-Cordova-SDK/tree/main/examples)
* [React Native example project](https://github.com/OneSignal/react-native-onesignal/tree/main/examples)
* [Flutter example project](https://github.com/OneSignal/OneSignal-Flutter-SDK/tree/main/examples)
* [Unity example project](https://github.com/OneSignal/OneSignal-Unity-SDK/tree/main/examples)
* [.NET MAUI example project](https://github.com/OneSignal/OneSignal-DotNet-SDK/tree/main/examples)

### 检查错误日志

在进一步诊断之前收集日志数据：

* 遵循[捕获调试日志](./capturing-a-debug-log)指南。
* 查找可能解释该行为的错误、警告或弃用通知。

<Card title="捕获调试日志" icon="bug" href="./capturing-a-debug-log">
  如何启用详细日志记录并捕获 SDK 输出以进行故障排除。
</Card>

### 联系支持

如果您仍遇到问题，请联系 `support@onesignal.com` 并提供：

* 您的 OneSignal 应用 ID
* 受影响设备的外部 ID 和/或订阅 ID
* 通知 ID 或仪表板中通知的链接（如适用）
* 重现问题的[设备调试日志](./capturing-a-debug-log)

***

## 常见错误

### APNS 委托从未触发

"APNS Delegate Never Fired"和"APNS 3000"等错误是 Apple 的超时消息，表示设备无法连接到 Apple 的 APNS 服务器。最常见于以下情况：

* 在 APNS 开发环境中测试
* 将多个推送通知依赖项或原生 iOS 推送 API 与 OneSignal 一起使用
* 临时连接问题——通常在用户下次开始新会话时自动解决（应用在后台运行 30 秒以上，然后重新打开）

**解决步骤：**

1. 删除所有其他推送通知依赖项或原生 iOS 推送 API，仅使用 OneSignal。错误解决后，可以重新添加其他代码。联系 `support@onesignal.com` 获取共存最佳实践。
2. 检查[设备调试日志](./capturing-a-debug-log)了解更多详情。
3. 如果错误持续存在，请[联系支持](#故障排除步骤)。

如果您使用 Capacitor，请添加此配置以让 OneSignal 处理推送通知。

<CodeGroup>
  ```json json theme={null}
  {
    "ios": {
      "handleApplicationNotifications": false
    }
  }
  ```

  ```typescript capacitor.config.ts theme={null}
  const config: CapacitorConfig = {
    // ... additional configuration

    ios: {
      // ... additional configuration
      handleApplicationNotifications: false
    }
  };
  ```
</CodeGroup>

### 强制关闭后点击通知时应用无法打开

确保您不是在 `Debug` 构建上进行测试。例如，对于 Flutter 应用，您可以：

* 通过 Flutter 使用发布构建，例如 `flutter run --release`（需要物理设备）
* 将 Xcode scheme 更新为 `Release` 而不是 `Debug`

***

## 相关页面

<Columns cols={2}>
  <Card title="移动 SDK 设置" icon="wrench" href="./mobile-sdk-setup">
    所有受支持的移动和跨平台 SDK 的设置说明。
  </Card>

  <Card title="捕获调试日志" icon="bug" href="./capturing-a-debug-log">
    如何捕获 SDK 日志以进行故障排除。
  </Card>

  <Card title="网页推送故障排除" icon="globe" href="./troubleshooting-web-push">
    排除网页推送通知问题。
  </Card>

  <Card title="移动 SDK 参考" icon="book" href="./mobile-sdk-reference">
    OneSignal 移动 SDK 的完整 API 参考。
  </Card>
</Columns>

***

## 常见问题

### 如果我在应用中更改 OneSignal 应用 ID 会发生什么？

在您应用的初始化代码中更改 OneSignal 应用 ID 将在用户更新并打开应用到最新版本时在新应用 ID 下创建全新的用户和推送订阅。

如果您的 iOS bundle ID 和/或 Android package ID 相同，那么设备将继续保持相同的推送订阅状态。用户数据将是全新的，即您需要在新记录上重新添加您的别名、标签、电子邮件地址、电话号码。

如果 iOS bundle ID 或 Android package ID 不同，那么这是一个全新的应用，应该有不同的推送证书/密钥。

### OneSignal 可以在本地部署的封闭网络中发送推送通知吗？

只要您封闭网络上的计算机可以访问您要支持的推送网关服务器，这就可以工作：

* [https://support.apple.com/en-us/HT203609](https://support.apple.com/en-us/HT203609)
* [https://firebase.google.com/docs/cloud-messaging/concept-options#messaging-ports-and-your-firewall](https://firebase.google.com/docs/cloud-messaging/concept-options#messaging-ports-and-your-firewall)

如果网络完全与互联网断开连接，则无法通过标准操作系统/浏览器服务传递推送通知，这是我们支持的。

***