Skip to main content

Notification APIs

Client Side Notifications​

Testing Instructions​

Please make sure to use the same browser and the same signed-in state for the entire process. This is required so that we send a notification only to the user who has subscribed to the notification.

Subscribing to notifications​

  1. Visit Games on Microsoft Start

  2. Click on a game

  3. Please install manually by clicking the download icon and then the Install button.

    Install PWA App

    Confirm installation of the PWA App

  4. Please select the appropriate permission for the app here.

    PWA App permissions

  5. Click on the Notifications blocked bell icon at the top. (This will only show up if you have not allowed notifications previously.)

    Notification blocked bell icon

  6. Click Allow for this site. (We understand these steps may seem overly complex. We are looking into how we can further optimize this user flow.)

    Allow notifications for the PWA App

Scheduling a notification​

Now that you have subscribed for the notifications, we can go ahead and schedule a new notification.

The updated API signature is as follows -

$msstart.scheduleNotificationAsync({
    title: string,
    description: string,
    type: number,
    imageData?: string,
    payload?: string,
    minDelayInSeconds?: number,
    callToAction?: string
}) : string

An API call will look like below.

$msstart.scheduleNotificationAsync({
    title: "Test Title",
    description: "Test Description",
    type: 0
});

Expected response and error objects when the promise resolves or rejects -

$msstart.scheduleNotificationAsync(...)
  .then(response: string) {
    // response === "Successfully queued the notification.">
    // This indicates that the notification has been queued successfully.
  }
  .catch(error: SdkError) {>
    // error.code === "INVALID_SCHEDULE_NOTIFICATION_PARAMETERS" &&
    // error.description === "Invalid parameters for SDK call to Schedule Notification."
    // This means that the Schedule Notification API was called with invalid parameter values.
    // Please read below for the parameter types and their acceptable values.

    // error.code === "NO_ACTIVE_GAME" &&
    // error.description === "Invalid SDK call to Schedule Notification. No active play items found."
    // This means that the API was called out of the context of a game.
    // Please ensure that the API is called from within the game.

    // error.code === "SCHEDULE_NOTIFICATION_REQUEST_FAILED" &&
    // error.description === "Failed to schedule notification."
    // This means that the service failed to schedule the notification
  }

The SDK Error object is defined as

 const errorObject: SdkError = {
   code: SdkErrorCode,
   description: string,
   extra?: any
 }
 const enum SdkErrorCode {
   // Error codes
 }

API Parameters​

Title: string​

  • Short title for the notification, which fits the notification window.
  • Maximum length - 60 characters
  • Recommended text - Name of the game or an event within the game. Ideally the title should be something that would be catchy to uniquely identify the game and captivate users to click on the notification.
  • Sample - Unlock the Fun: Dive into Microsoft's Playland Adventure!

Description: string​

  • Short description for the notification, which fits the notification window.
  • Maximum length - 200 characters
  • Recommended text - The description for a notification. This again, should be something appealing and make users click on the notification. (Added a longer sample description to suggest some ideas, but we enforce a limit of 200 characters.)
  • Sample - Embark on an exhilarating journey through the virtual world with Microsoft's Playland Adventure! Brace yourself for endless excitement as you immerse yourself in this casual gaming experience. From thrilling quests to mind-boggling puzzles, this captivating game will keep you hooked for hours. Gather your friends and unleash your gaming skills as you unlock new levels, collect rewards, and discover hidden treasures. Get ready to lose yourself in a world filled with laughter, adventure, and non-stop fun. Click and play the Playland Adventure today and let the gaming frenzy begin!

Type: number​

  • The type of notification. The type will be a number from 0-15, therefore there can be a maximum of 16 types of notifications. We would be using the Type field in addition to the GameId and the UserId to dedupe notifications. A second call to schedule a notification with the same type will overwrite the previous one. So at any given instant, there can only be one notification for a single type.
  • Acceptable values - 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15
  • Ensure you are passing an integer as a number and not a string. '1' and "1" are strings and will fail validation.

ImageData (Optional): string​

  • Base 64 Encoded Image string or URL. We will determine on our end if it is a Base 64 image or an URL and then upload the image to our object store. This is the large image for the notification. The smaller image is the Game Thumbnail which we automatically determine from the game.
  • The image ideally should have a 2:1 aspect ratio and the resolution should be 364 x 180
  • Please find additional details for image dimensions here App notification content

Payload (Optional): string​

  • A schema-less string that can be used to pass additional data for the notification. This can be a string or a JSON object which can provide additional details in the target URL of the notification. This payload is present as a query parameter notificationPayload on the notification target URL. To keep the target URL safe, we encode the contents of the payload sent in the original schedule request. Therefore, you might have to decode the URI .

MinDelayInSeconds (Optional): number​

  • Delay in seconds for which the notification will be held on the backend before dispatching it to the end user. You can schedule a notification up to 7 days in advance. (<= 7 x 24 x 60 x 60 seconds.)
  • We have a inbuilt de-dupe logic that will only send one notification every 5 minutes for the same game, type and user.
  • Therefore, we have a minimum delay of 5 minutes for a notification. If there is another notification scheduled within those 5 mins, we will pick the updated content and deliver the notification after 5 minutes of when the original notification was scheduled.

CallToAction (Optional): string​

  • The text for the call to action button. The URL for the CTA will be the gameplay page URL or the URL to the PWA App.

Best Practices​

To enable notifications for PWA apps, here are some best practices reliably schedule and deliver notifications.

Don't 

  • Schedule too many notifications which might annoy the users.

Do 

  • Retain the same browser and the sign-in states when installing the PWA app and scheduling the notification

$msstart.scheduleNotificationAsync​

When this API is called from a Game, a notification can be scheduled for that game. This is the very first version where we are supporting only one delivery channel through PWA so that we can unblock integration. We are still building more impactful delivery channels.

Please follow the testing instructions below closely to test your integrations

Server-Side Notifications​

Prequisite: Please ensure you have onboarded to the User Identity APIs. We use player data from these APIs to uniquely identify a player for scheduling server-side notifications.

When a game is running, the SDK has context and its APIs can only be used within this context. This means the client-side notification SDK API (scheduleNotificationAsync()) can only schedule a notification while the user is actively playing a game (delivery can still happen when they are not). To schedule a notification while the user is offline, you should use the server-side notification API.

Because server-side notifications work differently from SDK APIs, we need extra details for server-side notifications compared to the client-side SDK API.

The SDK has access to Player Information and Game Information, making these properties automatically available for client-side notification calls. However, for server-side notifications, you need to provide the player information and game information as parameters to uniquely identify the player and the game.

Sample API call

API URL

POST https://msstart-games.azure-api.net/notification/schedule

Headers

Content-Type: application/json

Post Request Body

{
  "playerId": "082d9af-e8f1-49b9-9e60-da7c0711ba50",
  "gameId": "9xxxxxxxxxxx",
  "type": 0,
  "title": "Server Side Notification Title",
  "description": "Server Side Notification Description"
}

Request Body Parameters​

Player Information​

Player information is retrieved from the User Identity SDK APIs ($msstart.getSignedInUserAsync() and/or $msstart.signInAsync()) and includes two parameters: PlayerId and PublisherPlayerId

To uniquely identify the player, provide either PlayerId or PublisherPlayerId. If neither or both are provided, or if the user is not found, a HTTP 400 Bad Request validation failure occurs.

PlayerId: GUID​

  • The Player Id of the user
  • Sample - 0982d9af-e8f1-49b9-9e60-da7c0711ba50

PublisherPlayerId: GUID​

  • The Publisher Player Id of the user
  • Sample - 04a6f571-0032-42aa-b3e0-b6413f79305d

Game Information​

Game information requires one parameter: GameId.

To uniquely identify the game, provide the GameId. A HTTP 400 Bad Request validation failure occurs if GameId is not provided or is invalid.

GameId: string​

  • The Game Id
  • Length - 12 characters
  • Sample - 9xxxxxxxxxxx

Notification parameters​

Similar to client-side notifications, you need to include Title, Description, and Type parameters, which are mandatory. Additionally, you can optionally include ImageData, Payload, MinDelayInSeconds, and CallToAction. These mandatory and optional parameters have the same validation requirements as those for client-side notifications.

Title: string​

  • Short title for the notification, which fits the notification window.
  • Maximum length - 60 characters
  • Recommended text - Name of the game or an event within the game. Ideally the title should be something that would be catchy to uniquely identify the game and captivate users to click on the notification.
  • Sample - Unlock the Fun: Dive into Microsoft's Playland Adventure!

Description: string​

  • Short description for the notification, which fits the notification window.
  • Maximum length - 200 characters
  • Recommended text - The description for a notification. This again, should be something appealing and make users click on the notification. (Added a longer sample description to suggest some ideas, but we enforce a limit of 200 characters.)
  • Sample - Embark on an exhilarating journey through the virtual world with Microsoft's Playland Adventure! Brace yourself for endless excitement as you immerse yourself in this casual gaming experience. From thrilling quests to mind-boggling puzzles, this captivating game will keep you hooked for hours. Gather your friends and unleash your gaming skills as you unlock new levels, collect rewards, and discover hidden treasures. Get ready to lose yourself in a world filled with laughter, adventure, and non-stop fun. Click and play the Playland Adventure today and let the gaming frenzy begin!

Type: number​

  • The type of notification. The type will be a number from 0-15, therefore there can be a maximum of 16 types of notifications. We would be using the Type field in addition to the GameId and the UserId to dedupe notifications. A second call to schedule a notification with the same type will overwrite the previous one. So at any given instant, there can only be one notification for a single type.
  • Acceptable values - 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15

ImageData (Optional): string​

  • Base 64 Encoded Image string or URL. We will determine on our end if it is a Base 64 image or an URL and then upload the image to our object store. This is the large image for the notification. The smaller image is the Game Thumbnail which we automatically determine from the game.
  • The image ideally should have a 2:1 aspect ratio and the resolution should be 364 x 180
  • Please find additional details for image dimensions here App notification content

Payload (Optional): string​

  • A schema-less string that can be used to pass additional data for the notification. This can be a string or a JSON object which can provide additional details in the target URL of the notification. This payload is present as a query parameter notificationPayload on the notification target URL. To keep the target URL safe, we encode the contents of the payload sent in the original schedule request. Therefore, you might have to decode the URI .

MinDelayInSeconds (Optional): number​

  • Delay in seconds for which the notification will be held on the backend before dispatching it to the end user. You can schedule a notification up to 7 days in advance. (<= 7 x 24 x 60 x 60 seconds.)
  • We have a inbuilt de-dupe logic that will only send one notification every 5 minutes for the same game, type and user.
  • Therefore, we have a minimum delay of 5 minutes for a notification. If there is another notification scheduled within those 5 mins, we will pick the updated content and deliver the notification after 5 minutes of when the original notification was scheduled.

CallToAction (Optional): string​

  • The text for the call to action button. The URL for the CTA will be the gameplay page URL or the URL to the PWA App.

Overwriting an existing notification​

When a notification is scheduled with a delay specified by MinDelayInSeconds, we schedule the notification to be delivered after "MinDelayInSeconds" seconds have elapsed. An existing notification that has been scheduled (but not delivered yet) can be overwritten by calling scheduleNotificationAsync() again with the desired modifications in the data and keeping the same type. We will update all the fields with the new data except the minDelayInSeconds and deliver the updated notification after the original delay has elapsed.

If multiple notifications need to be scheduled, please consider using a different type.

Ex. Consider a notification has been scheduled like below

Title: Let's race!
Description: Winner gets a trophy!
Type: 0
MinDelayInSeconds: 3600

this notification can then be updated with new data

Title: Finish first and win a car!
Description: Winner gets an upgraded car!
Type: 0

This updated notification will be delivered after the delay in the original notification. (3600 seconds). If MinDelayInSeconds is provided on the second (or subsequent request), this delay will be ignored and the notification will be delivered honoring the delay from the schedule time of the first request.