跳转到主要内容

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 文档
I