Create targeted messages that Oculus will deliver to your users’ Notification Feed. Notifications allow you to interact with your users outside of your app.
Congratulate them for unlocking a rare achievement with an XP boost, notify them of an upcoming in-game event, or remind them that they have unused gems. The message you send is up to you.
Notifications that you generate are displayed in the Notification Feed with the other Oculus notifications. Users are made aware of the notification by badging both on and in the Gear VR Oculus app. Then when the user interacts with your notification, your app will be launched for a deeper experience.
(Badging on the Oculus app)
(Badging in the Oculus app)
When creating your content, we recommend that each notification has a personalized element and a clear call to action. Concise, actionable notifications are most effective, especially those that are a result of some in-app action.
Notification titles of up to 30 characters fit on one line and notification messages of up to 70 characters fit on two lines. The following image shows an example of two-line notifications.
Users have the ability to unsubscribe from notifications, so it is your responsibility to create high-quality and interesting notifications at a reasonable cadence. Notifications that users find spammy or uninteresting may result in them unsubscribing from your app’s notifications.
All notifications must conform to the Oculus Content and Design Guidelines. Apps that violate these guidelines or otherwise create a poor user experience (for example, by sending an excessive volume of notifications) may be blocked from sending notifications.
When creating your notification you’ll have the option of sending the notification to a list of users you define, or to a targeted audience of your users.
Please note that this is not the user’s Org Scoped ID. Users will have different IDs for each app.
You can also target users by sending notifications to predefined audience. To send to a predefined audience, send
“LAST_30_DAY_ACTIVE” as the
target_audience. When using
recipient_ids parameter should be omitted from your API call.
"ALL" will send the notification to every user entitled to your app. In other words, every user who has ever installed your app through the Oculus Store.
"LAST_30_DAY_ACTIVE" will send the notification to all users who are entitled to your app and have used their VR device in the last 30 days. This targeting will include users who have been active in any VR app, not just your app, in the last 30 days.
target_audience, users’ time zones will be taken into account so notifications will send at the same local time for each user. In the 24 hours following
send_time (or, if omitted, the Unix timestamp at time of send), users will receive the notification at a consistent time in their respective time zones. This enables you to maximize the impact of notifications by choosing the most relevant local time for them to be received.
For example, if
send_time is 1527883200 (8:00pm UTC, June 1, 2018), each user will receive the notification at 8:00pm in their respective time zone. If
send_time is omitted, notifications are sent to users in the UTC time zone immediately, and users in other time zones will receive it at the same respective local time over the next 24 hours.
A small percentage of any notifications sent to a target audience will be held out as a control.
Once you’ve written your notification message and determined who will receive the notification, you can create and schedule the message to be sent.
Notification are created by REST API call. Please review the information on the Server-to-Server API Basics page for information about interacting with the Oculus S2S APIs.
The format of the POST is:
curl https://graph.oculus.com/notification_request -d access_token='OC\|APP_ID\|APP_SECRET' -d app_id=APP_ID -d title='Title' -d message='Message' -d uri='url' -d recipient_ids=["USER_ID2","USER_ID3","USER_ID3"]
Following are the parameter descriptions:
|Y||Auth token Server-to-Server API Basics||string||“OC|APP_ID|APP_SECRET”|
|Y||Notification message.||string||“You’ve won a brand new car!”|
|Y, unless targeting an audience with target_audience||Array of targeted Oculus IDs.||array of strings||[“123”,”456”,”789”]|
|Y||Notification title.||string||“Tell them what theyve won.”|
|Y||Deeplink URI. More information below.||string||See below.|
|N||Unix timestamp of the date and time to send the notification. If omitted, notifications will begin to send immediately.||string||“1529598630”|
|N||Defines the audience grouping to receive the message.||enum - “ALL”, LAST_30_DAY_ACTIVE||“ALL”|
Using the URI Parameter
The URI parameter allows you to deeplink into your app. When a user clicks on the notification, your app will be launched and the URI defined in your notification will be passed in the launch intent.
In your app, you’ll need to be able to handle the deeplink message you’ve defined. Native apps will receive a notification of type
ovrMessage_Notification_ApplicationLifecycle_LaunchIntentChanged on the message queue when the app is launched from a notification.
On startup, check for this notification and call
Platform.ApplicationLifecycle.GetLaunchDetails() in Unity) to retrieve information about how the app was launched. All app launches by this API will have a launch type of
DEEPLINK. This information allows you to direct the user to the proper app experience.
If the user does not currently have the app installed, they will be directed to the product information page in the Gear VR Oculus app where they can download the app.
Before you send your notification broadly to an audience using the
target_audience option, you may wish to test your notification and URI integration by sending to yourself or your team using
recipient_ids. Once you’re happy with the notification message and deeplink, you may change the targeting to a more broad audience.
Track the lifetime performance of the notifications you send. To access the Notification analytics, navigate to the Analytics page for your app, and select the Notifications tab.