Oculus Go Development

On 6/23/20 Oculus announced plans to sunset Oculus Go. Information about dates and alternatives can be found in the Oculus Go introduction.

Oculus Quest Development

All Oculus Quest developers MUST PASS the concept review prior to gaining publishing access to the Quest Store and additional resources. Submit a concept document for review as early in your Quest application development cycle as possible. For additional information and context, please see Submitting Your App to the Oculus Quest Store.

Oculus Platform Utility Reference

The Oculus Platform Utility is a command-line tool that enables you upload builds to your release channels much faster than using the Oculus dashboard web interface, and it enables larger upload packages. It also allows you to incorporate automated uploads into your existing build system.

The Oculus Platform Utility uploads builds faster because it analyzes your build and only uploads the parts that have changed since your last upload.

This topic contains the following sections:

Download and Install the Utility

  1. Select the appropriate download for your system:

  2. Copy the utility to the directory of your choice.
  3. For Mac, you will need to change the access permissions of the utility for it to execute:

    • Change directories (cd) to the location of the file
    • At the command prompt, type: chmod +x ./ovr-platform-util
    • Run the utility by typing ./ovr-platform-util and a command

Obtain Credentials to Use the Utility

You will need the App ID, App Secret or User Token, and Build ID to complete some of the commands. Note that:

  • Commands accept a App Secret or User Token to verify access to the app. You can access the App Secret or User Token on the developer portal or get the User Token with the get-access-token command.

Find the App ID, App Secret and/or User Token

  • Sign in to the Oculus developer portal with an admin account for your organization and navigate to https://dashboard.oculus.com.
  • Find the app in the list of apps for your organization
  • Navigate to the Getting Started API page to find the App ID and generate an App Secret and User Token. Note that you must use an admin account to view the app secret. Visit the Members page under Settings for your organization to verify the admin accounts. The following image shows an example of the API page:

    app get started API page

  • Alternatively, if you are not an administrator, you can retrieve a user token to use with additional commands with the Oculus Platform Utility. Use the get-access-token command and enter your credentials when prompted. A user token is returned.

Obtain Build ID

You will need a Build ID to download an existing build. You can find this in a couple of different ways:

  • Obtain the Build ID from the output when you successfully upload an app build with the utility.
  • View the build ID on the dashboard by viewing the build details for the upload channel. Do this by finding the app channel, and in the Action menu (ellipses), choose View Channel Builds. Then, on the Channel Builds page, under the Actions menu (ellipses), choose View Build Details. The build number will display like the following.

build details

Use the Oculus Platform Tool for Unity or Unreal Engine

Oculus offers a UI integration of the Oculus Platform Utility for Unreal Engine and Unity.

Command Quick Reference

The utility supports Rift, Quest and Go uploads and downloads. In addition, there are commands to manage the utility and get help.

Following is a list of commands for the utility:

Manage the Utility and Get User Tokens

TaskCommand
Get help with the utilityhelp
Get the version of the Oculus platform utilityversion
Update the Oculus platform utilityself-update
Get the app access tokenget-access-token

Manage Rift Builds

TaskCommand
Upload a Rift buildupload-rift-build
Download a Rift builddownload-rift-build
Clone an existing Rift buildclone-rift-build
Move build to a different release channelset-release-channel-build
Upload an add-on files such as DLC or IAPupload-add-on

Manage Quest Builds

The following commands help you manage apps that target Quest devices.

TaskCommand
Upload a Quest buildupload-quest-build
Download a Quest builddownload-quest-build
Move build to a different release channelset-release-channel-build
Upload an add-on files such as DLC or IAPupload-add-on

Manage Go Builds

The following commands help you manage Go apps.

TaskCommand
Upload a Go buildupload-mobile-build
Download a Go builddownload-mobile-build
Move build to a different release channelset-release-channel-build
Upload an add-on files such as a DLC or IAPupload-add-on

Get Help with the Utility

Use the following command to get a list of commands and other help for the utility.

$ ovr-platform-util.exe help

Check the Tool Version

You can check what version of the utility you have by using the version command

$ ovr-platform-util version

This will generate output like the following:

Oculus Platform Command Line Utility - 1.54.0.000001 (Built on Tue Jul 28 2020)

Configure the Tool to Self Update

You can configure the utility to self update using the self-update command.

$ ovr-platform-util self-update

This will result in output like the following:

Checking for the latest version
Already running the latest version 1.54.0.000001

Get the App Access Token

Use the following command to get a user access token for the app. You can use this token in place of the app secret for many commands.

$ ovr-platform-util.exe get-access-token

You will be prompted for the account access credentials and when successfully entered, returns the token for use with commands that require an access token.

Upload a Rift Build

Following is the syntax and parameters for uploading a Rift app to the Oculus store.

Syntax

$ ovr-platform-util upload-rift-build -a <AppID>  --app_secret <App-Secret> --token <User-Token> -d <BuildPath> -l <LaunchFile>
-c <ReleaseChannel> -v <Number> -n <Text> --assets-dir <assset-dir> --asset-files-config <config.json>  --language-packs-dir [-p <Arguments>] [-L <2DLaunchFile>] [-P <2DArguments>]
[-r <RedistID>[,]...] [-f {true|false}] [--help  {true|false}] [--clean  {true|false}]  [--add-entitlement-check  {true|false}] [--help  {true|false}] [--inherit-assets  {true|false}]

Parameters

SyntaxDescription
-d <buildPath>
--build_dir <buildPath>
Required. Specifies the full path to the directory containing your build files.
-a <ID>
-app_id <ID>
Required. Specifies the ID of your app. Obtained from the API tab of your app in the Oculus Dashboard.
-s <app-secret>
--app_secret <app-secret>
Required. Specifies the app secret. Obtained from the API tab of your app in the Oculus developer dashboard.
-t <token>
--token <token>
Either app secret or user token required. A user token obtained by the get-access-token command or from the API tab of your app in the Oculus developer dashboard.
-c <releaseChannel>
--channel <ReleaseChannel>
Required. Specifies the release channel for uploading the build. Release channel names are not case-sensitive.
-v <version-number>
--version <version-number>
Required. Specifies the version number shown to users.
-l <launchFile>
--launch_file <launchFile>
Required. Specifies the relative path from the the build directory to the executable that launches your app.
-n <text>
--notes <text>
Optional. Specifies the release note text shown to users. Enclose the text in quotation marks. Encode double quotes as ". Encode newlines as \n.
-p <arguments>
--launch_params <arguments>
Optional. Specifies any arguments passed to the launcher.

--assets-dir <dirPath>
Optional Specifies the path to the directory with DLCs for this build.

--asset-files-config <filePath>
Optional. Specifies the path to the file that configures required assets or associates DLC assets with in-app purchases

--language-packs-dir <file-path>
Optional. The path to the directory that contains language packs.
-L <2DLaunchFile>
--launch_file_2d <2DLaunchFile>
Optional. Specifies the relative path from the build directory to the executable that launches your app in 2D mode.
-P <2DArguments>
--launch_params_2d <2DArguments>
Optional. Specifies any arguments passed to the launcher in 2D mode.
-r <redistID>,<redistID2>...
--redistributables <redistID>,<redistID2>....
Optional. Specifies one or more redistributable IDs. Enclose the IDs with quotation marks. Separate multiple redistributable IDs with commas. Example - “RedistID1,RedistID2”.
See the Redistributable section for a complete list of redistributables and their IDs
-f {true/false}
--firewall_exceptions {true/false}
Optional. Specifies if a Windows Firewall exception is required. True or False. Default is false.

Options

SyntaxDescription

--help
Optional. Show help for the command

--clean
Optional. Skips the caching layer and performs a fresh upload. Use this if you want to force the tool to start over and recompute the checksums of an interrupted upload session instead of continuing where it left off.

--add-entitlement-check
Optional. Adds entitlement check code to the executable. Use this if you want to automate the entitlement check process in your application.

--inherit-asset-files
Optional. A boolean that indicates whether to inherit asset files from the previous build. The default is false.

--exclude-addons
Optional. A boolean that indicates whether to exclude the add-ons associated with this app. The default is false.

Examples

This upload example uses the fictitious app “Rabbit Hole” and assumes the following sample parameters. Note that the example shows Windows file syntax.

  • App ID: 10001234
  • Token: 1234abcd
  • Build Directory: C:\Rabbit Hole
  • Launch File: C:\Rabbit Hole\bin\badrabbits.exe
  • New version: 1.1
  • Release Note: Fixes the rabbit spawn bug.

Simple Rift Upload Example

To upload version 1.1 of Rabbit Hole to the RC release channel, enter:

$ ovr-platform-util upload-rift-build --app-id 10001234 --token 1234abcd
-d "C:\Rabbit Hole" -l "bin\badrabbits.exe"
-n "Fixes the rabbit spawn bug." -v 1.1 -c rc

Upload with Redistributables Example

If the app requires .NET Framework 3.5 and Visual C++ 2013 x86 redistributable files, enter:

$ ovr-platform-util upload-rift-build --app-id 10001234 --app-secret 1234abcd -d "C:\Rabbit Hole" -l "bin\badrabbits.exe" -n "Fixes the rabbit spawn bug."
-v 1.1 -c rc -r "606493776156948, 910524935693407"

2D Mode with Firewall Exception Example

If the app requires a Windows Firewall exception, Windows 10 as a minimum version, and has a 2D mode executable file and argument string of badrabbits2d.exe -force2dfix, enter:

$ ovr-platform-util upload-rift-build --app-id 10001234 --token 1234abcd
-d "C:\Rabbit Hole" -l "bin\badrabbits.exe"
-n "Fixes the rabbit spawn bug." -v 1.1  -c rc -L badrabbits2d.exe
-P "-force2dfix" -f -w "10"

Multi-line Release Note Example

If you have a multi-line release note, enter:

$ ovr-platform-util upload-rift-build --app-id 10001234 --token 1234abcd -d "C:\Rabbit Hole" -l "bin\badrabbits.exe"
-n  "Carrots now available as in-app purchases.\nBlue rabbits no longer \"glitch\" and get stuck in terrain.\nSpawn sound spatialization adjusted for realism."
-v 1.1 -c rc

Download a Rift Build

Following is the syntax and parameters for downloading a Rift app to the Oculus store.

Syntax

$ ovr-platform-util download-rift-build -b <BuildID> -d <Directory>

Parameters

SyntaxDescription
-b <buildID>
--build_id <buildID>
Required. Specifies the build ID you want to download. You can obtain this from the CLI output after successfully uploading an app build with the command line tool.
-d <directory>
--output_dir <directory>
Required. Specifies the directory you want to download the build to.

Rift Download Example

To download the app build with build ID 3141592653589793 to “C:\Pie Thrower”:

  1. Enter:
    $ ovr-platform-util download-rift-build -b 3141592653589793 -d "C:\Pie Thrower"
    
  2. Provide the email address and password of an Oculus user authorized to download the app.
  3. The build should download to the specified directory.

Add the Entitlement Check to an Executable

Add Oculus Platform Entitlement Check to specified executables.

Syntax

$ ovr-platform-util add-entitlement-check -b <BuildID> -d <Directory>

Parameters

SyntaxDescription
-d <buildPath>
--build_dir <buildPath>
Required. Specifies the full path to the directory containing your build files.
-d <directory>
--output_dir <directory>
Required. Specifies the directory you want to download the build to.

Clone a Rift Build

This command will clone an existing Rift build to create a new build. You can optionally modify any of the metadata for the build. The new build will be placed in the release channel specified by the destination_channel parameter. The build to be cloned can either be picked from another channel by using the source_channel or specified explicitly by using the build_id parameter.

Syntax

ovr-platform-util clone-rift-build --app_id <AppID>  --app_secret <App-Secret> --token <User-Token> --source_channel <Channel> --destination_channel <Channel> [OPTIONS]

Parameters

SyntaxDescription
-a <ID>
-app_id <ID>
Required. Specifies the ID of your app. Obtained from the API tab of your app in the Oculus Dashboard.
-s <app-secret>
--app_secret <app-secret>
Either app secret or user token required. Specifies the app secret. Obtained from the API tab of your app in the Oculus developer dashboard.
-t <token>
--token <token>
Either app secret or user token required. A user token obtained by the get-access-token command or from the API tab of your app in the Oculus developer dashboard.

--destination_channel <channel>
Required. Specifies the release channel to be updated.

--source_channel <channel>
Optional. If specified, the build from this channel will be copied to the destination channel.
-b <buildID>
--build_id <buildID>
Optional. Specifies the build ID you want to download. You can obtain this from the CLI output after successfully uploading an app build with the command line tool.
-v <version-number>
--version <version-number>
Required. Specifies the version number shown to users.
-l <launchFile>
--launch_file <launchFile>
Required. Specifies the relative path from the the build directory to the executable that launches your app.
-n <text>
--notes <text>
Optional. Specifies the release note text shown to users. Enclose the text in quotation marks. Encode double quotes as ". Encode newlines as \n.
-p <arguments>
--launch_params <arguments>
Optional. Specifies any arguments passed to the launcher.
-L <2DLaunchFile>
--launch_file_2d <2DLaunchFile>
Optional. Specifies the relative path from the build directory to the executable that launches your app in 2D mode.
-P <2DArguments>
--launch_params_2d <2DArguments>
Optional. Specifies any arguments passed to the launcher in 2D mode.
-r <redistID>,<redistID2>...
--redistributables <redistID>,<redistID2>....
Optional. Specifies one or more redistributable IDs. Enclose the IDs with quotation marks. Separate multiple redistributable IDs with commas. Example - “RedistID1,RedistID2”.
See the Redistributable section for a complete list of redistributables and their IDs
-f {true/false}
--firewall_exceptions {true/false}
Optional. Specifies if a Windows Firewall exception is required. True or False. Default is false.
-w {"7SP1"/8.1/10}
--windows_min_version {"7SP1"/8.1/10}
Optional. Specifies the minimum required Windows version. The versions that can be specified are “7SP1”, 8.1, 10. The default is “7SP1”.

Clone Rift Build Example

ovr-platform-util clone-rift-build --app_id 10001234 --app_secret 1234abdc --source_channel alpha --destination_channel beta --launch_params "server=beta"

Redistributable ID Reference

Following is a list of redistributable packages and their associated IDs.

NameRedistributable ID
.NET Framework 3.5606493776156948
.NET Framework 4.0133610290311340
.NET Framework 4.5.11617306711884127
.NET Framework 4.7.11667821599930345
DirectX (June 2010)822786567843179
OpenAL 1.11147517301974655
Visual C++20051604897159783747
Visual C++2008118440348500045
Visual C++2010532320330249657
Visual C++2010 x861008652072555515
Visual C++20121683508698536289
Visual C++2012 x861002692246447245
Visual C++20131675031999409058
Visual C++2013 x86910524935693407
Visual C++2015 Update 31183534128364060
Visual C++2015 x86 Update 31113033105419344
Visual C++20171315322525257173
Visual C++2017 x861064693870299984
Visual C++20192657209094360789
Visual C++2019 x862556834837738356
Vulkan Runtime1.0.65.11824471960899274
Vulkan Runtime1.1.73.01941020095932382

Upload Quest Build

Following is the syntax and parameters for uploading a Quest app to the Oculus store.

Syntax

ovr-platform-util upload-quest-build --app_id <ID>  --app_secret <App-Secret> --token <User-Token> --apk <path/to/Your.apk> --obb <path/to/Your.obb> --assets-dir <path/to/DLCs/dir> --channel <ReleaseChannel> --notes <ReleaseNotes>  --asset-files-config <config.json>  --language-packs-dir <path>  [--help  {true|false}]  [--inherit-assets  {true|false}]
 [--exclude-addons  {true|false}]

Parameters

SyntaxDescription
-a <ID>
-app_id <ID>
Required. Specifies the ID of your app. Obtained from the API tab of your app in the Oculus Dashboard.
-s <app-secret>
--app_secret <app-secret>
Either app secret or user token required. Specifies the app secret. Obtained from the API tab of your app in the Oculus developer dashboard.
-t <token>
--token <token>
Either app secret or user token required. A user token obtained by the get-access-token command or from the API tab of your app in the Oculus developer dashboard.

--apk <filePath>
Required. Specifies the path to the APK file to upload.

--assets-dir <dirPath>
Optional Specifies the path to the directory with DLCs for this build.

--asset-files-config <filePath>
Optional. Specifies the path to the file that configures required assets or associates DLC assets with in-app purchases

--obb <filePath>
Optional. Specifies the path to the Expansion file (OBB) to upload.
-c <releaseChannel>
--channel <ReleaseChannel>
Required. Specifies the release channel for uploading the build. Release channel names are not case-sensitive.
-n <text>
--notes <text>
Optional. Specifies the release note text shown to users. Enclose the text in quotation marks. Encode double quotes as ". Encode newlines as \n.

--language-packs-dir <file-path>
Optional. The path to the directory that contains language packs.

Options

SyntaxDescription

--help
Optional. Show help for the command
``
--inherit-asset-files
Optional. A boolean that indicates whether to inherit asset files from the previous build. The default is false.
``
--exclude-addons
Optional. A boolean that indicates whether to exclude the add-ons associated with this app. The default is false.

Examples

This upload example uses the fictitious app “Rabbit Hole”. Note that these examples show syntax used on Windows.

  • App ID: 10001234
  • App User Token: 1234abcd
  • APK Path: C:\Rabbithole.apk

For Quest enter:

$ ovr-platform-util upload-quest-build --app-id 10001234 --token 1234abcd --apk C:\RabbitHole.apk --channel alpha --notes "Fixes the rabbit spawn bug."

Download Quest Build

Following is the syntax and parameters for downloading a Quest app from the Oculus store.

Syntax

ovr-platform-util download-quest-build -b <BuildID> -d <Directory>

Parameters

SyntaxDescription
-b <buildID>
--build_id <buildID>
Required. Specifies the build ID you want to download. You can obtain this from the CLI output after successfully uploading an app build with the command line tool.
-d <directory>
--output_dir <directory>
Required. Specifies the directory you want to download the build to.

Download Example

The following example shows how to download the app build with build ID 3141592653589793 to “C:\Pie Thrower”.

For Quest enter:

$ ovr-platform-util download-quest-build -b 3141592653589793 -d "C:\Pie Thrower"

Upload Go Build

Following is the syntax and parameters for uploading a Go app to the Oculus store.

Syntax

ovr-platform-util upload-mobile-build --app_id <ID>  --app_secret <App-Secret> --token <User-Token> --apk <path/to/Your.apk> --obb <path/to/Your.obb> --assets-dir <path/to/DLCs/dir> --channel <ReleaseChannel> --notes <ReleaseNotes>

Parameters

SyntaxDescription
-a <ID>
-app_id <ID>
Required. Specifies the ID of your app. Obtained from the API tab of your app in the Oculus Dashboard.
-s <app-secret>
--app_secret <app-secret>
Either app secret or user token required. Specifies the app secret. Obtained from the API tab of your app in the Oculus developer dashboard.
-t <token>
--token <token>
Either app secret or user token required. A user token obtained by the get-access-token command or from the API tab of your app in the Oculus developer dashboard.

--apk <filePath>
Required. Specifies the path to the APK file to upload.

--assets-dir <dirPath>
Optional. Specifies the path to the directory with DLCs for this build.

--asset-files-config <filePath>
Optional. Specifies the path to the file that configures required assets or associates DLC assets with in-app purchases

--obb <filePath>
Optional. Specifies the path to the Expansion file (OBB) to upload.
-c <releaseChannel>
--channel <ReleaseChannel>
Required. Specifies the release channel for uploading the build. Release channel names are not case-sensitive.
-n <text>
--notes <text>
Optional. Specifies the release note text shown to users. Enclose the text in quotation marks. Encode double quotes as ". Encode newlines as \n.

Simple Upload Example

The following examples show how to upload Rabbit Hole to the Alpha release channel. This upload example uses the fictitious app “Rabbit Hole”.

  • App ID: 10001234
  • App Secret Token: 1234abcd
  • APK Path: C:\Rabbithole.apk

For Go enter:

$ ovr-platform-util upload-mobile-build --app-id 10001234 --app_secret 1234abcd --apk C:\RabbitHole.apk --channel alpha --notes "Fixes the rabbit spawn bug."

Multi-line Release Note Example (Go)

For Go, if you have a multi-line release note, enter:

$ ovr-platform-util upload-mobile-build --app-id 10001234 --app-secret 1234abcd
--apk C:\RabbitHole.apk --channel alpha
--notes "Carrots now available as in-app purchases.\nBlue rabbits no longer \"glitch\" and get stuck in terrain.\nSpawn sound spatialization adjusted for realism."

Expansion File Example (Go)

If you split version 2 of Rabbit Hole into separate APK and APK expansion files (see APK Expansion File Requirements) you specify the full path to the expansion file with --obb. Enter:

$ ovr-platform-util upload-mobile-build --app-id 10001234 --app-secret 1234abcd
--apk C:\RabbitHole.apk --obb C:\main.2.com.oculus.rabbits.obb
--channel alpha --notes "Split data and code to provide smaller and faster patch updates."

Required Assets Example (Go)

If you have a build with required assets, include a path to the assets and a config file that designates them as required or as IAP. Following is an example for Go:

$ ovr-platform-util upload-mobile-build --app-id 10001234 --app-secret 1234abcd
--apk C:\RabbitHole.apk --assets_dir ~\path\to\assets\ --asset_files_config '{"Asset1.obb": {"required": true}, "Asset2.obb": {"sku": "IAP_SKU"}}'
--channel alpha

Download Go Build

Syntax

ovr-platform-util download-mobile-build -b <BuildID> -d <Directory>

Parameters

SyntaxDescription
-b <buildID>
--build_id <buildID>
Required. Specifies the build ID you want to download. You can obtain this from the CLI output after successfully uploading an app build with the command line tool.
-d <directory>
--output_dir <directory>
Required. Specifies the directory you want to download the build to.

Download Example

The following examples show how to download the app build with build ID 3141592653589793 to “C:\Pie Thrower”.

For Go, enter:

$ ovr-platform-util download-mobile-build -b 3141592653589793 -d "C:\Pie Thrower"
  1. Provide the email address and password of an Oculus user authorized to download the app.
  2. The build should download to the specified directory.

Set a Release Channel

Syntax

ovr-platform-util set-release-channel-build --app_id <AppID>  --app_secret <App-Secret> --token <User-Token> --source_channel <Channel> --destination_channel <Channel>

Parameters

SyntaxDescription
-d <buildPath>
--build_dir <buildPath>
Required. Specifies the full path to the directory containing your build files.
-s <app-secret>
--app_secret <app-secret>
Either app secret or user token required. Specifies the app secret. Obtained from the API tab of your app in the Oculus developer dashboard.
-t <token>
--token <token>
Either app secret or user token required. A user token obtained by the get-access-token command or from the API tab of your app in the Oculus developer dashboard.
-d <directory>
--output_dir <directory>
Required. Specifies the directory you want to download the build to.

--destination_channel <channel>
Required. Specifies the release channel to be updated.
-b <buildID>
--build_id <buildID>
Optional. Specifies the build ID you want to download. You can obtain this from the CLI output after successfully uploading an app build with the command line tool.

--source_channel <channel>
Optional. If specified, the build from this channel will be copied to the destination channel.

Release Channel Example The following example shows how to set the release channel for a build from Beta to RC

$ ovr-platform-util set-release-channel-build --app-id 10001234 --app-secret 1234abcd  --source-channel beta --destination-channel rc

Manage Add-ons

The utility enables you to manage add-ons such as downloadable content (DLC) and in-app purchases (IAP) with the upload-add-on command. For more information, see Add-ons.

Syntax

$ ovr-platform-util.exe upload-add-on --app_id <AppID> --app_secret <App-Secret> --token <User-Token> --file <file> --sku <sku> --min-version-code <min-version>

Parameters

SyntaxDescription
-a <ID>
-app_id <ID>
Required. Specifies the ID of your app. Obtained from the API tab of your app in the Oculus Dashboard.
-s <app-secret>
--app_secret <app-secret>
Either app secret or user token required. Specifies the app secret. Obtained from the API tab of your app in the Oculus developer dashboard.
-t <token>
--token <token>
Either app secret or user token required. A user token obtained by the get-access-token command or from the API tab of your app in the Oculus developer dashboard.
-f <file-path>
--file <file-path>
Required. The path to the asset file to upload.
-p <SKU>
--sku <SKU>
Required. The SKU associated with the add-on item.
-v <version-code>
--min-version-code <version-code>
Required. The minimum build number of the app to associate this add-on item with.

Add-on Example

The following examples show how to upload the add-on “carrot”.

  • App ID: 10001234
  • App Secret: 1234abcd
  • File: C:\rabbit-hole-d
  • Sku: carrot
$ ovr-platform-util upload-add-on   --app-id 10001234  --app-secret 1234abcd  --file C:\rabbit-hole\dlc\  --sku carrot