Cloud

Experience Notifications

Experience Notifications are a way for 13+ users to keep up with their favorite experiences through timely, personalized notifications. As the developer, you can determine what kinds of in‑experience activities are most important to notify your users about, as well as define the notification content. This article contains best practices, examples, instructions for implementation and analytics, details on the delivery system, and an overview of guidelines.

Example notification
Example notification

The Experience Notification system features the following:

  • Customizable Notifications with Parameters — Full flexibility to customize the notification message with parameters, for example "Your gold goose egg has hatched!" or "You're 2 quests away from reaching Level 6!"
  • Launch Data — Include optional launch data that can be read through Player:GetJoinData() when the notification recipient joins. This could involve routing a user to a coordinate location or personalizing their joining experience.
  • Analytics Support — Track your reachable audience and the performance of your notifications in the Creator Dashboard. Available in March 2024.

Experience Eligibility Requirements

In order to use the APIs to send notifications, the experience must meet the following base criteria:

  • Minimum 100 visits since launch.
  • The experience must not be under moderation.
  • You as the developer must have permission to manage the experience.

User Experience

Enabling Notifications

Users of age 13+ are eligible to receive Experience Notifications and can enable them by clicking the Notify button on your experience's details page. Users can also view and manage all the experiences they receive notifications from in the Notifications settings for their Roblox account.

Enable notifications button on an experience's details page (mobile)
Enable notifications button on an experience's details page (web)

13+ users who already follow your experience will be retained and these users will be automatically eligible to receive Experience Notifications in addition to existing update notifications.

Receiving Notifications

Experience Notifications will be delivered to the Roblox notification stream. Users can join your experience directly via the Join button on the notification and spawn according to your launch data.

Notifications stream on the Roblox app

Example Notifications

You may use Experience Notifications to notify users of moments and activity that occur in-experience and are highly relevant to them. Here are two categories for inspiration:

Example notification
Example notification

Best Practices

Notifications should be personalized to the receiver and should be based on in‑experience activity that's specifically relevant to the user. Inversely, notifications should not be of a generic, advertising nature.

Ideally, notifications should also alert users of something they can take immediate action on. Avoid purely informational notifications that do not prompt a direct response or action.

Please also ensure that you are following the guidelines before using Experience Notifications.

Implementation

Implementing Experience Notifications begins with creating a notification string. Once a notification string is set up, you can send notifications with optional custom parameters.

Alternatively, you can use the Engine API to trigger notifications through server-side scripts.

Creating a Notification String

Sending an Experience Notification

The UserNotification API lets you send Experience Notifications to users. Before using it, you must generate an API key or configure OAuth 2.0 for your app. The examples on this page use API keys.

To send an Experience Notification to a user:

  1. Copy the API key to the x-api-key request header of the Create User Notification call.

  2. In your request:

    1. Copy the notification string asset ID as the value of the payload.message_id property.
    2. Set payload.type to "MOMENT".
    3. Set source.universe to be the universe resource URL "universes/${UniverseID}".
Send an Experience Notification

curl --location 'https://apis.roblox.com/cloud/v2/users/${UserId}/notifications' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
"source": {
"universe": "universes/${UniverseID}"
},
"payload": {
"message_id": "${AssetID}",
"type": "MOMENT"
}
}'

Example response which returns the notification ID in the id field:


{
"path": "users/505306092/notifications/6ca4d981-36fa-4255-82a1-14d95c116889",
"id": "6ca4d981-36fa-4255-82a1-14d95c116889"
}

Customizing Notifications Using Parameters

To customize the notification for each recipient, you can include parameters in the notification string, then customize the parameters when calling the API. For example, you can define the notification string as "You won {numRaces} races this week and unlocked the {racetrackName} track!", then set the numRaces and racetrackName parameters.

Customize Notification Using Parameters

curl --location 'https://apis.roblox.com/cloud/v2/users/${UserId}/notifications' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
"source": {
"universe": "universes/${UniverseID}"
},
"payload": {
"message_id": "${AssetID}",
"type": "MOMENT",
"parameters": {
"numRaces": {"int64_value": 5},
"racetrackName": {"string_value": "Galaxy Road"}
}
}
}'

Including Launch and Analytics Data

To further improve user experience, you can include launch data in the notification, useful for scenarios such as routing users to a coordinate location or personalizing the joining experience. Additionally, you can include analytics data to segment the performance of different categories of notifications.

Include Launch Data and Analytics Data

curl --location 'https://apis.roblox.com/cloud/v2/users/${UserId}/notifications' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
"source": {
"universe": "universes/${UniverseID}"
},
"payload": {
"message_id": "${AssetID}",
"type": "MOMENT"
},
"join_experience": {
"launch_data": "Test_Launch_Data"
},
"analytics_data": {
"category": "Test_Analytics_Category"
}
}'

Delivery System

A spam prevention system exists to ensure the quality of notifications for users and protect the shared notification channel for all developers. Because of this, delivery of notifications is not guaranteed. This spam prevention system is directly informed by user engagement: the more users engage with your notifications, the more reach they'll receive. You can transparently track engagement metrics in the analytics dashboard, as explained below.

To start, Experience Notifications are subject to the same static throttle limit of experience update notifications. Each user can receive one notification every three days from a given experience and you'll receive transparent feedback when a user's throttle limit is reached. The limit will be relaxed over time.

Additionally, the following list outlines some of the special cases which may result in non‑delivery of a notification:

  • Experience eligibility requirements are not met.
  • Recipient is not opted in to notifications from your experience.
  • Recipient's throttle limit for your experience has been reached.
  • Recipient's aggregate daily throttle limit has been reached.
  • Missing or invalid request parameters.
  • Notification string was moderated.

Analytics

Starting in March, performance of your notifications and notifiable audience are displayed in the Analytics tab of the Notifications page where you configure notification strings (simply tab from Creations to Analytics).

  1. Navigate to the Creator Dashboard.

  2. Similar to badges, notification strings are tied to a specific experience. Locate that experience's thumbnail and click on it.

  3. In the left column, under Engagement, click Notifications.

  4. On the target page, click the Analytics tab to switch to the analytics dashboard.

Notifications Summary

The summary section serves as a snapshot of the aggregate performance of your notifications.

StatisticDescription
Opted-in UsersThe total number of users that have turned on notifications for your experience. Please note that this does include users under the age of 13 who are only able to receive notification of experience updates, not personalized Experience Notifications.
ImpressionsThe total number of user impressions all of your notifications have received in aggregate.
ClicksThe total number of clicks all of your notifications have received in aggregate.
CTRThe rate at which users are clicking on your notifications, calculated as the ratio of clicks to impressions.
Turn OffThe rate at which users are turning off notifications for your experience directly from your notifications, calculated as the ratio of turn off actions to impressions.
DismissThe rate at which users are dismissing your notifications, calculated as the ratio of dismiss actions to impressions.

Itemized Stats

The Experience Notifications table displays detailed performance statistics for each notification with at least 100 impressions, ordered by the date of first impression for that notification.

The Name column is the key identifier for the notification. By default, the name matches the identifier name you specified when creating the notification string, but you can override it through the category field in your API calls, in which case category overrides the name. Changing the string name in the Creator Dashboard or changing the string your message ID references in the API call will generate a new row in the table.

If you'd like to A/B test the performance of different strings, it's recommended that you create an entirely new notification string with a similar name, for example:

  • EggHatchA — "Your gold egg has hatched! Come meet your new pet."
  • EggHatchB — "It's hatching time! Come meet your new pet."

Guidelines

All notification content and behaviors are subject to Roblox's Community Standards and platform‑wide text filtering, regardless of your experience's age guidelines. This means that if your experience is a 17+ experience, your notifications are still subject to the platform‑wide standards, not the 17+ Policy Standards.

Do not mention specific users in your notifications by user name, Player.DisplayName, or otherwise. Notifications should be relevant to the receiver without the mention of a specific user.

Notification content is not permitted to incorporate dark patterns or other tactics that manipulate or deceive users into making choices they don't intend, or which may be counter to their best interests. This could include the following:

  • Disguised Ads — Notifications that are intentionally disguised as organic content, but are actually advertising.

    Clicking notification leads to Petz World but no "important information" is displayed
  • Time Pressured Actions — Notifications that pressure users into clicking, subscribing, consenting, or purchasing through applying false time pressure.

    The information provided about the purchase reward is false/inaccurate
  • Bait-and-Switch with Free Items or Other Rewards — Notifications that falsely tell users that they'll receive something for free when it's not.

    Upon clicking the notification, it becomes clear that something further is required to get the gift
  • Tricking Users Into Purchasing — Notifications that trick users into making unintended purchases.

    When clicked, the user is brought directly to a purchase system pre‑loaded with items that the user didn't choose to buy

Experiences should not require users to turn on notifications in order to participate or advance in gameplay.