Windows app setup

Complete guide for integrating OneSignal push notifications into your Universal Windows Platform (UWP) app using Windows Push Notification Service (WNS) and OneSignal’s REST API

Windows App Setup

Requirements

Before setting up OneSignal for your Windows app, ensure you have:

• Universal Windows Platform (UWP) App - OneSignal currently supports UWP apps only
• Microsoft Store App Registration - Required for obtaining Package SID and Secret Key
• OneSignal Account - Free account with configured app and platform settings

OneSignal does not currently support Windows App SDK (WinUI 3). If your app uses Windows App SDK instead of UWP, please contact [e-mail] for guidance on migration options.

Configure Your OneSignal App and Platform

Step 1: Set Up Your OneSignal Account

If your team already has a OneSignal account, request admin access to configure platform settings. Otherwise, create a free account to get started.

Step 2: Create or Configure Your OneSignal App

OneSignal allows you to configure multiple platforms (iOS, Android, Huawei, Amazon, Windows) within a single app for cross-platform messaging.

Create New App

1. Click New App/Website from your dashboard
2. Choose a recognizable app name and organization name
3. Select Windows (UWP) as your platform
4. Click Next: Configure Your Platform

Creating a new OneSignal app with Windows platform

Add Platform to Existing App

1. Select your existing app
2. Navigate to Settings > Push & In-App
3. Click Add Platform and select Windows (UWP)

Setting up your OneSignal app and selecting Windows platform

Step 3: Configure Additional Platforms (Optional)

If you’re building a cross-platform app, configure additional platforms now:

• Android: Set up Firebase Credentials
• iOS: p8 Token (Recommended) or p12 Certificate
• Amazon: Generate API Key
• Huawei: Authorize OneSignal

Click Save & Continue after entering credentials for each platform.

Step 4: Select Target SDK

Choose Windows UWP as your target SDK and click Save & Continue.

Select Windows UWP SDK to access platform-specific documentation

Step 5: Save Your App ID

Critical: Copy and securely store your OneSignal App ID - you’ll need this for API calls and user registration.

Save your App ID and invite team members who need access

Optionally, invite team members by clicking Invite, then click Done to continue.

Windows Platform Configuration

Get Microsoft Store Credentials

Since OneSignal uses Windows Push Notification Service (WNS), you’ll need credentials from the Microsoft Store:

1. Publish to Microsoft Store - Your app must be registered in the Microsoft Store (even if not publicly available)
2. Obtain Package SID and Secret Key - Follow Microsoft’s detailed guide to retrieve these credentials
3. Configure OneSignal Platform:
   • Navigate to Settings > Windows (UWP) in your OneSignal dashboard
   • Paste your Package SID and Secret Key
   • Click Save to activate the platform

Configure Windows platform credentials in OneSignal dashboard

Gotcha: Package SID and Secret Key are only available after your app is registered with the Microsoft Store. You cannot test push notifications locally without these credentials.

SDK Integration

Understanding the Architecture

OneSignal doesn’t provide a dedicated UWP SDK. Instead, you’ll integrate using:

1. Windows Push Notification Service (WNS) - Microsoft’s native push service
2. OneSignal REST API - For user management and message sending
3. Notification Channel URI - Acts as the device token for push notifications

For comprehensive understanding of WNS, review Microsoft’s WNS documentation.

Register Users for Push Notifications

Step 1: Request Notification Channel

Follow Microsoft’s guide to create a notification channel. The channel URI returned by WNS serves as your device token.

// Example: Getting notification channel URI
var channel = await PushNotificationChannelManager.CreatePushNotificationChannelForApplicationAsync();
string channelUri = channel.Uri; // This is your token for OneSignal

Step 2: Create OneSignal User Record

Call OneSignal’s Create user API to register the device:

Required Parameters:

• subscription.type: "WindowsPush"
• subscription.token: The channel URI from Step 1

Recommended Parameters:

• identity.external_id: Unique identifier for the user (e.g., user ID from your system)
• properties: Any custom user properties for targeting

{
  "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"
    }
  }
}

Gotcha: Channel URIs can expire and change. Implement logic to refresh the channel URI periodically and update the OneSignal user record when it changes.

Handle Channel URI Changes

WNS channel URIs can expire. Implement the PushNotificationReceived event to detect when you need to refresh:

channel.PushNotificationReceived += OnPushNotificationReceived;

// Check if channel URI has changed
if (channel.Uri != storedChannelUri) {
    // Update OneSignal user record with new URI
    await UpdateOneSignalUser(channel.Uri);
}

Sending Push Notifications

Using OneSignal Dashboard

1. Navigate to Messages > Push in your OneSignal dashboard
2. Create a new push notification
3. Select your Windows platform
4. Configure your message content and targeting
5. Send immediately or schedule for later

Using OneSignal API

Send notifications programmatically using the Create notification 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"
}

For detailed messaging options and advanced targeting, see Sending Push Messages.

Next Steps and Best Practices

Testing Your Integration

1. Test Notification Channel Creation - Ensure your app successfully creates and maintains a WNS channel
2. Verify User Registration - Confirm users are properly registered in your OneSignal dashboard
3. Send Test Notifications - Use the OneSignal dashboard to send test messages
4. Handle Notification Events - Implement proper handling for notification received, opened, and dismissed events

Common Issues and Solutions

Channel URI Not Working

• Verify your Package SID and Secret Key are correctly configured
• Ensure your app is properly registered with the Microsoft Store
• Check that the channel URI hasn’t expired

Users Not Receiving Notifications

• Confirm the OneSignal user record was created successfully
• Verify the Windows platform is properly configured in OneSignal
• Check that notifications aren’t being blocked by Windows notification settings

API Integration Issues

• Validate your OneSignal App ID is correct
• Ensure you’re using the correct API endpoints and authentication
• Review API response codes and error messages for troubleshooting

Production Considerations

• Implement proper error handling for all OneSignal API calls
• Set up monitoring for channel URI refresh failures
• Consider implementing offline queueing for API calls during network issues
• Plan for scaling user registration during peak app usage periods

For additional support and advanced implementation guidance, contact OneSignal support or explore our comprehensive API documentation.