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 Command Line Utility Reference

The Oculus Platform Command Line Utility lets 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 CLI 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 command line utility to the directory of your choice.
  3. For Mac, you will need to change to access permissions of the tool 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 tool by typing ./ovr-platform-util and a command.

Obtain Credentials to Use the Utility

You may need the App ID, App Secret or Build ID to complete some of the commands.

Find the App ID and App 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 App Secret. The following image shows an example:

Use the app secret wherever you are prompted for the access token. You can also obtain a user token that can be used with some commands with the get-access-token command)

Note: 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.

Obtain Build ID

You will need a Build ID to download an existing build. You can obtain the build ID two different ways:

  • Obtain the Build ID from the output when you successfully upload an app build with the command-line tool.

OR

  • Obtain the Build ID on the developer dashboard by navigating to Manage Build page.
  • Click the ellipses for a channel, and View Channel Builds
  • The URL of this page displays the App ID and the Build ID. The following image shows an example:

Command Quick Reference

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

Following is a list of commands for the tool:

Manage the Utility

TaskCommand
Get help with the utilityhelp
Get the version of the Oculus platform utilityversion
Update the Oculus platform utilityself-update
Get the app access tokenaccess-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 fileupload-add-on

Manage Quest Builds

TaskCommand
Upload a Quest buildupload-quest-build
Download a Quest builddownload-quest-build
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 fileupload-add-on

Manage Go Builds

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 fileupload-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

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

Check the Tool Version

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

$ ovr-platform-util version

This will generate ouput 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 tool 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.

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

You will be promped for the account access credentials and when successfully entered, returns the token for use with commands that accept a user token.

Upload a Rift Build

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

Syntax

$ ovr-platform-util upload-rift-build -a <AppID> -s <Token> -d <BuildPath> -l <LaunchFile>
-c <ReleaseChannel> -v <Number> -n <Text> [-p <Arguments>] [-L <2DLaunchFile>] [-P <2DArguments>]
[-r <RedistID>[,]...] [-f {true|false}] [-w {7SP1|8.1|10}] [--add-entitlement-check]

Options

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-token>
--app_secret <app-token>
Required. Required. Specifies the app secret token. Obtained 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 lLaunchFile>
--launch_file <launchFile>
Required. Specifies the relative path from
-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
-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

--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.
-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”.

This upload example uses the fictitious app “Rabbit Hole” and assumes the following sample parameters:

  • App ID: 10001234
  • App Secret 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 --app-secret 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 --app-secret 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 --app-secret 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 options for downloading a Rift app to the Oculus store.

Syntax

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

Options

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.

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>

Options

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 <Secret> --source_channel <Channel> --destination_channel <Channel> [OPTIONS]

Options

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-token>
--app_secret <app-token>
Required. Required. Specifies the app secret token. Obtained from the API tab of your app in the Oculus developer dashboard.

--destination_channel <channel>
Required. 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. Obtained from the console output message after successfully uploading an app build with the command line tool. Cannot currently be obtained from the Oculus Dashboard.
-v <version-number>
--version <version-number>
Required. Specifies the version number shown to users.
-l lLaunchFile>
--launch_file <launchFile>
Required. Specifies the relative path from
-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
-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 options for uploading a Quest app to the Oculus store.

Syntax

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

Options

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-token>
--app_secret <app-token>
Required. Required. Specifies the app secret token. Obtained 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>
Required. Specifies the path to the directory with DLCs for this build.

--asset-file-iap-configs-file <filePath>
Required. Specifies the path to the file with IAP configs for paid DLCs.

--obb <filePath>
Required. 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.

Examples

This upload example uses the fictitious app “Rabbit Hole”.

  • App ID: 10001234
  • App Secret Token: 1234abcd
  • APK Path: C:\Rabbithole.apk
  • APK Package name: com.oculus.rabbits

For Quest enter:

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

Download Quest Build

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

Syntax

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

Options

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.

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 options for uploading a Go app to the Oculus store.

Syntax

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

Options

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-token>
--app_secret <app-token>
Required. Required. Specifies the app secret token. Obtained 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>
Required. Specifies the path to the directory with DLCs for this build.

--asset-file-iap-configs-file <filePath>
Required. Specifies the path to the file with IAP configs for paid DLCs.

--obb <filePath>
Required. 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
  • APK Package name: com.oculus.rabbits

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>

Options

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.

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 <Secret> --source_channel <Channel> --destination_channel <Channel>

Options

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.

--destination_channel <channel>
Required. Required. Specifies the release channel to be updated.
-b <buildID>
--build_id <buildID>
Optional. Specifies the build ID you want to download. Obtained from the console output message after successfully uploading an app build with the command line tool. Cannot currently be obtained from the Oculus Dashboard.

--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

You can manage add-ons with the utility and upload-add-on command. For more information, see Add-ons.

Syntax

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

Options

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-token>
--app_secret <app-token>
Either app secret or user token required. Required. Specifies the app secret token. 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 access token obtained by the get-access-token command.
-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.