Group Launch

Note: You are viewing the Unity version of this topic. To view this topic for native development, see Group Launch (Native). To view this topic for Unreal development, see Group Launch (Unreal).

Group Launch allows developers to create deeplink urls for users to coordinate travel into your application together. For more information on deeplink handling, see the Oculus Destinations and Rich Presence docs.

There are two types of Group Launches: private and public.

  • Private - These deep launches have exclusive user list that control the visibility and are passed to the deep link.
  • Public - These deep launches have no user list and can be used by anyone. These are the links that can be posted to social media.

These links have a configurable time to live (TTL) with a 7 day default. The associated room can be configured. Deletion is possible, but updating is not. Simply create a new deeplink. The content shown on the Oculus website are the image and description from the destination the deeplink is configured to.

S2S REST Requests

Our S2S REST APIs are available as a secure channel to interact with the Oculus Platform. For example, you may wish to track and consume coins purchased through in-app purchases on your trusted server. This prevents any client-side tampering to grant unpurchased gems. Using the S2S APIs are not required, but may be used if you wish.

See the Server-to-Server API Basics page for information about interacting with our APIs.

Use this method to create a deeplink that any user can join.

URL: https://graph.oculus.com/{app-id}/app_deeplink_public

METHOD: POST

Creating a new public link:

curl -X POST "https://graph.oculus.com/<app-id>/app_deeplink_public?access_token=<app-secret-token>&destination_api_name=super_cool_level&deeplink_message_override=custom_payload&valid_for=1"

Parameter Descriptions

ParameterParam TypeDescriptionType
destination_api_nameQueryThe name of the destination the deeplink routes to.string
deeplink_message_overrideQueryOptional. An optional field to add additional information to the launch.string
valid_forQueryThe hours until the link expires. 0 means the link never expires.integer

Return Parameter Descriptions

ParameterDescriptionType
idThe id of the group launch deeplink.integer

Example return:{"id":"012345678911"}


Use this method to create a deeplink with a specified leadder and a list of users that is not available to the public.

URL: https://developer.oculus.com/{app-id}/app_deeplink_private

POST: /{app-id}/app_deeplink_private

Creating a new private link for a group of users:

curl -X POST "https://graph.oculus.com/<app-id>/app_deeplink_private?access_token=<app-secret-token>&destination_api_name=super_cool_level&deeplink_message_override=custom_payload&valid_for=1&leader=<user-id>&users[]=<user-id2>&users[]=<user-id3>&fields=url"

Creating a new private link for one person without a room:

curl -X POST "https://graph.oculus.com/<app-id>/app_deeplink_private?access_token=<app-secret-token>&destination_api_name=super_cool_level&valid_for=1&leader=<user-id>&create_room=false&fields=url"

Parameter Descriptions

ParameterParam TypeDescriptionType
destination_api_nameQueryThe name of the destination the deeplink routes to.string
deeplink_message_overrideQueryOptional. An optional field to add additional information to the launch.string
valid_forQueryThe hours until the link expires. 0 means the link never expires.integer
leaderQueryOptional. The id of the user who created the private deeplink.integer
usersQueryOptional. The list of users using the private deeplink.A comma-separated list of strings

Return Parameter Descriptions

ParameterDescriptionType
idThe id of the group launch deeplink.integer

Example return:{"id":"012345678910"}


Use this method to get information about an existing group launch deeplink.

URL: https://graph.oculus.com/{link_id}

METHOD: GET

Example Request (server authoritative):

GET /{link-id}/?fields=url,expiration_time,users\{alias\}
HTTP/1.1
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5

Example cURL Request:

curl "https://graph.oculus.com/<link-id>?access_token=<app-secret-token>&fields=url,expiration_time,users\{alias\}"

Parameters

ParameterParam TypeDescriptionType
idPathThe id of the group launch deeplink.integer
urlQueryThe url of the deeplink.string
destinationQueryThe id of the destination the deeplink routes to.integer
roomQueryOptional. The id of the room the destination routes to.integer
leaderQueryOptional. The id of the user who created the private deeplink.integer
usersQueryOptional. The list of users using the private deeplink.A comma-separated list of strings
deeplink_message_overrideQueryOptional. An optional field to add additional information to the launch.string
valid_forQueryThe hours until the link expires. 0 means the link never expires.integer

Example return:{"id":"012345678912", "url":"https:\/\/www.oculus.com\/vr\/01234578999\/"}


Delete a Group Launch

Use this method to delete a group launch deeplink.

URL: https://graph.oculus.com/{link_id}

METHOD:DELETE

Example Request (server authoritative):

GET /{link-id}/?fields=url,expiration_time,users\{alias\}
HTTP/1.1
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5

Example cURL Request:

curl -X DELETE "https://graph.oculus.com/<link-id>?access_token=<app-secret-token>"
ParameterDescriptionType
successA boolean that defines whether or not the request was successful.boolean

Example return:{"success":true}


Example Scenarios

Two Person Tournament from Website

Two players have signed up on your tournament website to play against each other. You can generate a group launch link for them to launch the app directly into the match, from your website with a request to the following endpoint with parameters like these.

Endpoint: app_deeplink_private

ParameterExample value
destination_api_namemuliplayer_arcade_1v1
deeplink_message_overridetournament_match=1234
leader5678910
users%5B"11121314"%5D
valid_for720

Example curl request:

curl -X POST "https://graph.oculus.com/<app-id>/app_deeplink_private?access_token=<app-secret-token>&destination_api_name=muliplayer_arcade_1v1&deeplink_message_override=tournament_match=1234&leader=5678910&users=%5B\"2815643748564206\"%5D&valid_for=0"

New skin in your game on Social Media

You released a new skin in your game and want users to check it out. You can generate a deeplink and post it to your Twitter with the following endpoint and parameters like these.

Endpoint: app_deeplink_public

ParameterExample value
destination_api_namecharacter_editor
deeplink_message_overrideitem=bunny_ears_5
valid_for0

Example curl request:

curl -X POST "https://graph.oculus.com/<app-id>/app_deeplink_public?access_token=<app-secret-token>&destination_api_name=character_editor&deeplink_message_override=item=_bunny_ears_5&valid_for=0"

Your app provides a standalone account registration system. Users that have already signed up on your website don’t want to enter their complicated password in VR. You can generate an account linking deeplink on-demand, and show it on your website with the following endpoint and parameters like these.

Endpoint:app_deeplink_private

ParameterExample value
destination_api_namemenu
deeplink_message_overrideaccount_nonce=1234abcd56ef
valid_for1

Example curl request:

curl -X POST "https://graph.oculus.com/<app-id>/app_deeplink_private?access_token=<app-secret-token>&destination_api_name=menu&deeplink_message_override=account_nonce=1234abcd56ef&leader=5678910&valid_for=1"