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
• Obtain Credentials to Use the Utility
• Use the Oculus Platform Tool for Unity or Unreal Engine
• Command Quick Reference
• Get Help with the Utility
• Upload a Rift Build
• Download a Rift Build
• Clone a Rift Build
• Add the Entitlement Check to an Executable
• Redistributable ID Reference
• Upload a Quest Build
• Download a Quest Build
• Upload a Go Build
• Download a Go Build
• Set Release Channel
• Manage Add-ons

Download and Install the Utility

1. Select the appropriate download for your system:

   • Windows 32-bit and 64-bit
   • Mac OS X
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:

  

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

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.

• For Unreal Engine, see Upload Apps to the Oculus Store with the Oculus Platform Tool.

• For Unity, in the Unity Editor, go to Oculus > Tools, and choose the Oculus Platform Tool. Fill out the required information and click the Upload button.

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

Manage Rift Builds

Manage Quest Builds

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

Manage Go Builds

The following commands help you manage Go apps.

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

Options

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

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

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

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.

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

Options

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

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

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

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

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

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