> ## 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.

# Windows 应用程序设置

> 将 OneSignal 推送通知集成到您的通用 Windows 平台 (UWP) 应用程序中的完整指南，使用 Windows 推送通知服务 (WNS) 和 OneSignal 的 REST API

# Windows 应用程序设置

## 要求

在为您的 Windows 应用程序设置 OneSignal 之前，请确保您具备：

* **通用 Windows 平台 (UWP) 应用程序** - OneSignal 目前仅支持 UWP 应用程序
* **Microsoft Store 应用程序注册** - 获取 Package SID 和密钥所需
* **OneSignal 账户** - 已配置应用程序和平台设置的免费账户

<Info>OneSignal 目前不支持 Windows App SDK (WinUI 3)。如果您的应用程序使用 Windows App SDK 而不是 UWP，请联系 `support@onesignal.com` 获取[迁移选项](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/guides/notifications)的指导。</Info>

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

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

如果您的团队已经拥有 OneSignal 账户，请[请求管理员访问权限](./manage-team-members)以配置平台设置。否则，[创建一个免费账户](https://onesignal.com)开始使用。

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

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

#### 创建新应用程序

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

<Frame caption="创建一个具有 Windows 平台的新 OneSignal 应用程序">
  <img src="https://mintcdn.com/onesignal/tNi1OgLc_p9hiq7_/images/docs/13e619dc5fd638b4d9adf5505ddd645de431dc963dbeeac923462060c030ce7c-Screenshot_2025-04-07_at_3.48.57_PM.png?fit=max&auto=format&n=tNi1OgLc_p9hiq7_&q=85&s=77c331bb0aea78c3f5d96ed065e14d1f" width="2344" height="1544" data-path="images/docs/13e619dc5fd638b4d9adf5505ddd645de431dc963dbeeac923462060c030ce7c-Screenshot_2025-04-07_at_3.48.57_PM.png" />
</Frame>

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

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

<Frame caption="设置您的 OneSignal 应用程序并选择 Windows 平台">
  <img src="https://mintcdn.com/onesignal/jFWn5xzleD8du3j6/images/docs/5cfafd284e02ae310a7e2a973d58d858e36d59bd54a7c58c3dc5da5ff5946721-Screenshot_2025-04-07_at_3.51.19_PM.png?fit=max&auto=format&n=jFWn5xzleD8du3j6&q=85&s=2059055133014853ce9d5a62fb7c9bbc" width="2428" height="1960" data-path="images/docs/5cfafd284e02ae310a7e2a973d58d858e36d59bd54a7c58c3dc5da5ff5946721-Screenshot_2025-04-07_at_3.51.19_PM.png" />
</Frame>

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

如果您正在构建跨平台应用程序，现在请配置附加平台：

* **Android**: [Set up Firebase Credentials](./android-firebase-credentials)
* **iOS**: [p8 Token (Recommended)](./ios-p8-token-based-connection-to-apns) or [p12 Certificate](./ios-p12-generate-certificates)
* **Amazon**: [Generate API Key](./generate-an-amazon-api-key)
* **Huawei**: [Authorize OneSignal](./authorize-onesignal-to-send-huawei-push)

在为每个平台输入凭据后点击 **Save & Continue**。

### 步骤 4：选择目标 SDK

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

<Frame caption="选择 Windows UWP SDK 以访问特定平台的文档">
  <img src="https://mintcdn.com/onesignal/tNi1OgLc_p9hiq7_/images/docs/13775481f708ed06086e4f6cfd4892a7e47970b669757212f62b2f508c0d1ab7-Screenshot_2025-04-07_at_3.57.27_PM.png?fit=max&auto=format&n=tNi1OgLc_p9hiq7_&q=85&s=2509168f647aef9dc29e59805d0cec21" width="3162" height="1886" data-path="images/docs/13775481f708ed06086e4f6cfd4892a7e47970b669757212f62b2f508c0d1ab7-Screenshot_2025-04-07_at_3.57.27_PM.png" />
</Frame>

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

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

<Frame caption="保存您的应用程序 ID 并邀请需要访问权限的团队成员">
  <img src="https://mintcdn.com/onesignal/YOTSrtBSoqdrJ37A/images/docs/45dc4f796e919a3da95ab0f3cba25be49091fe56c0a97b159dc12dd16702d734-Screenshot_2025-04-07_at_3.59.42_PM.png?fit=max&auto=format&n=YOTSrtBSoqdrJ37A&q=85&s=6c14c2a05be8a4474e22a52aaa7d76da" width="2710" height="1846" data-path="images/docs/45dc4f796e919a3da95ab0f3cba25be49091fe56c0a97b159dc12dd16702d734-Screenshot_2025-04-07_at_3.59.42_PM.png" />
</Frame>

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

## Windows 平台配置

### 获取 Microsoft Store 凭据

由于 OneSignal 使用 Windows 推送通知服务 (WNS)，您需要来自 Microsoft Store 的凭据：

1. **发布到 Microsoft Store** - 您的应用程序必须在 Microsoft Store 中注册（即使不公开可用）
2. **获取 Package SID 和密钥** - 按照 [Microsoft 的详细指南](https://learn.microsoft.com/en-us/azure/notification-hubs/notification-hubs-windows-store-dotnet-get-started-wns-push-notification#create-an-app-in-windows-store)检索这些凭据
3. **配置 OneSignal 平台**：
   * 在您的 OneSignal 仪表板中导航至 **Settings > Windows (UWP)**
   * 粘贴您的 Package SID 和密钥
   * 点击 **Save** 激活平台

<Frame caption="在 OneSignal 仪表板中配置 Windows 平台凭据">
  <img src="https://mintcdn.com/onesignal/56ctKxZSV4m5VEkn/images/docs/b83d13b-Screenshot_2023-03-21_at_12.02.58_PM.png?fit=max&auto=format&n=56ctKxZSV4m5VEkn&q=85&s=aac1ef94751db6f307284a86a455b6cf" width="1842" height="940" data-path="images/docs/b83d13b-Screenshot_2023-03-21_at_12.02.58_PM.png" />
</Frame>

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

## SDK 集成

### 理解架构

OneSignal 不提供专用的 UWP SDK。相反，您将使用以下方式进行集成：

1. **Windows 推送通知服务 (WNS)** - Microsoft 的原生推送服务
2. **OneSignal REST API** - 用于用户管理和消息发送
3. **通知通道 URI** - 作为推送通知的设备令牌

要全面了解 WNS，请查阅 [Microsoft 的 WNS 文档](https://docs.microsoft.com/en-us/windows/uwp/design/shell/tiles-and-notifications/windows-push-notification-services--wns--overview)。

### 为推送通知注册用户

#### 步骤 1：请求通知通道

按照 Microsoft 的指南[创建通知通道](https://learn.microsoft.com/en-us/windows/apps/design/shell/tiles-and-notifications/request-create-save-notification-channel)。WNS 返回的通道 URI 作为您的设备令牌。

```csharp theme={null}
// 示例：获取通知通道 URI
var channel = await PushNotificationChannelManager.CreatePushNotificationChannelForApplicationAsync();
string channelUri = channel.Uri; // 这是您的 OneSignal 令牌
```

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

调用 OneSignal 的[创建用户](/reference/create-user) API 来注册设备：

**必需参数：**

* `subscription.type`: `"WindowsPush"`
* `subscription.token`: 来自步骤 1 的通道 URI

**推荐参数：**

* `identity.external_id`: 用户的唯一标识符（例如，来自您系统的用户 ID）
* `properties`: 用于定向的任何自定义用户属性

```json theme={null}
{
  "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` 事件来检测何时需要刷新：

```csharp theme={null}
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

使用[创建通知](/reference/create-message) API 以编程方式发送通知：

```json theme={null}
{
  "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"
}
```

有关详细的消息选项和高级定向，请参阅[发送推送消息](./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 文档](/reference/rest-api-overview)。