跳转到主要内容

​
Windows 应用程序设置

​
要求

在为您的 Windows 应用程序设置 OneSignal 之前，请确保您具备：
  • 通用 Windows 平台 (UWP) 应用程序 - OneSignal 目前仅支持 UWP 应用程序
  • Microsoft Store 应用程序注册 - 获取 Package SID 和密钥所需
  • OneSignal 账户 - 已配置应用程序和平台设置的免费账户
OneSignal 目前不支持 Windows App SDK (WinUI 3)。如果您的应用程序使用 Windows App SDK 而不是 UWP，请联系 support@onesignal.com 获取迁移选项的指导。

​
配置您的 OneSignal 应用程序和平台

​
步骤 1：设置您的 OneSignal 账户

如果您的团队已经拥有 OneSignal 账户，请请求管理员访问权限以配置平台设置。否则，创建一个免费账户开始使用。

​
步骤 2：创建或配置您的 OneSignal 应用程序

OneSignal 允许您在单个应用程序中配置多个平台（iOS、Android、华为、亚马逊、Windows）以实现跨平台消息传递。

​
创建新应用程序

  1. 从仪表板点击 New App/Website
  2. 选择可识别的应用名称和组织名称
  3. 选择 Windows (UWP) 作为您的平台
  4. 点击 Next: Configure Your Platform

创建一个具有 Windows 平台的新 OneSignal 应用程序

​
为现有应用程序添加平台

  1. 选择您现有的应用程序
  2. 导航至 Settings > Push & In-App
  3. 点击 Add Platform 并选择 Windows (UWP)

设置您的 OneSignal 应用程序并选择 Windows 平台

​
步骤 3：配置附加平台（可选）

如果您正在构建跨平台应用程序，现在请配置附加平台： 在为每个平台输入凭据后点击 Save & Continue。

​
步骤 4：选择目标 SDK

选择 Windows UWP 作为您的目标 SDK 并点击 Save & Continue。

选择 Windows UWP SDK 以访问特定平台的文档

​
步骤 5：保存您的应用程序 ID

**重要：**复制并安全存储您的 OneSignal 应用 ID - 您将需要此 ID 用于 API 调用和用户注册。

保存您的应用程序 ID 并邀请需要访问权限的团队成员

可选择点击 Invite 邀请团队成员，然后点击 Done 继续。

​
Windows 平台配置

​
获取 Microsoft Store 凭据

由于 OneSignal 使用 Windows 推送通知服务 (WNS)，您需要来自 Microsoft Store 的凭据：
  1. 发布到 Microsoft Store - 您的应用程序必须在 Microsoft Store 中注册（即使不公开可用）
  2. 获取 Package SID 和密钥 - 按照 Microsoft 的详细指南检索这些凭据
  3. 配置 OneSignal 平台：
    • 在您的 OneSignal 仪表板中导航至 Settings > Windows (UWP)
    • 粘贴您的 Package SID 和密钥
    • 点击 Save 激活平台

在 OneSignal 仪表板中配置 Windows 平台凭据

注意： Package SID 和密钥只有在您的应用程序在 Microsoft Store 中注册后才可用。没有这些凭据，您无法在本地测试推送通知。

​
SDK 集成

​
理解架构

OneSignal 不提供专用的 UWP SDK。相反，您将使用以下方式进行集成：
  1. Windows 推送通知服务 (WNS) - Microsoft 的原生推送服务
  2. OneSignal REST API - 用于用户管理和消息发送
  3. 通知通道 URI - 作为推送通知的设备令牌
要全面了解 WNS，请查阅 Microsoft 的 WNS 文档。

​
为推送通知注册用户

​
步骤 1：请求通知通道

按照 Microsoft 的指南创建通知通道。WNS 返回的通道 URI 作为您的设备令牌。 
// 示例：获取通知通道 URI
var channel = await PushNotificationChannelManager.CreatePushNotificationChannelForApplicationAsync();
string channelUri = channel.Uri; // 这是您的 OneSignal 令牌

​
步骤 2：创建 OneSignal 用户记录

调用 OneSignal 的创建用户 API 来注册设备： 必需参数：
  • subscription.type: "WindowsPush"
  • subscription.token: 来自步骤 1 的通道 URI
推荐参数：
  • identity.external_id: 用户的唯一标识符（例如，来自您系统的用户 ID）
  • properties: 用于定向的任何自定义用户属性
{
  "identity": {
    "external_id": "your-user-id-123"
  },
  "subscriptions": [
    {
      "type": "WindowsPush",
      "token": "https://cloud.notify.windows.com/?token=..."
    }
  ],
  "properties": {
    "tags": {
      "user_type": "premium",
      "app_version": "1.2.0"
    }
  }
}
**注意：**通道 URI 可能会过期和更改。实现逻辑以定期刷新通道 URI，并在其更改时更新 OneSignal 用户记录。

​
处理通道 URI 更改

WNS 通道 URI 可能会过期。实现 PushNotificationReceived 事件来检测何时需要刷新： 
channel.PushNotificationReceived += OnPushNotificationReceived;

// 检查通道 URI 是否已更改
if (channel.Uri != storedChannelUri) {
    // 使用新 URI 更新 OneSignal 用户记录
    await UpdateOneSignalUser(channel.Uri);
}

​
发送推送通知

​
使用 OneSignal 仪表板

  1. 在您的 OneSignal 仪表板中导航至 Messages > Push
  2. 创建新的推送通知
  3. 选择您的 Windows 平台
  4. 配置您的消息内容和定向
  5. 立即发送或安排稍后发送

​
使用 OneSignal API

使用创建通知 API 以编程方式发送通知： 
{
  "app_id": "your-onesignal-app-id",
  "contents": {"en": "Your notification message"},
  "headings": {"en": "Notification Title"},
  "include_external_user_ids": ["your-user-id-123"],
  "channel_for_external_user_ids": "push"
}
有关详细的消息选项和高级定向，请参阅发送推送消息。

​
下一步和最佳实践

​
测试您的集成

  1. 测试通知通道创建 - 确保您的应用程序成功创建和维护 WNS 通道
  2. 验证用户注册 - 确认用户在您的 OneSignal 仪表板中正确注册
  3. 发送测试通知 - 使用 OneSignal 仪表板发送测试消息
  4. 处理通知事件 - 对通知接收、打开和关闭事件实现适当的处理

​
常见问题和解决方案

通道 URI 无法工作
  • 验证您的 Package SID 和密钥配置正确
  • 确保您的应用程序在 Microsoft Store 中正确注册
  • 检查通道 URI 是否已过期
用户未收到通知
  • 确认 OneSignal 用户记录成功创建
  • 验证 Windows 平台在 OneSignal 中配置正确
  • 检查通知是否被 Windows 通知设置阻止
API 集成问题
  • 验证您的 OneSignal 应用 ID 正确
  • 确保您使用正确的 API 端点和身份验证
  • 查看 API 响应代码和错误消息以进行故障排除

​
生产考虑事项

  • 为所有 OneSignal API 调用实现适当的错误处理
  • 设置通道 URI 刷新失败的监控
  • 考虑在网络问题期间为 API 调用实现离线队列
  • 规划在应用使用高峰期间扩展用户注册
要获得额外支持和高级实施指导，请联系 OneSignal 支持或探索我们全面的 API 文档。