==============================
Custom Protocol Commands
==============================

Launcher supports deep linking which allows using custom URLs to point to specific Launcher screens or 
run various Launcher commands. Deep linking is built on top of custom protocol URLs that start with ``omniverse-launcher://``.
Such links can be used by emails, websites or messages to redirect users back to Launcher, 
or can be used by system administrators to manage installed apps.

This document describes the list of all available custom protocol commands for Launcher.

Showing a Launcher Screen
-------------------------------

Launcher supports ``omniverse-launcher://navigate`` command to bring up the main window and 
open a specific screen there. The screen is specified with the ``path`` query parameter, for example:

`omniverse-launcher://navigate?path=/news <omniverse-launcher://navigate?path=/news>`__

The list below defines all available screens supported by this command:

- News: `omniverse-launcher://navigate?path=/news <omniverse-launcher://navigate?path=/news>`__
- Library: `omniverse-launcher://navigate?path=/library <omniverse-launcher://navigate?path=/library>`__
  
  - Installed app in the library: `omniverse-launcher://navigate?path=/library/:slug <omniverse-launcher://navigate?path=/news>`__ where ``:slug`` should be replaced with a unique application name.
  - Installed connectors: `omniverse-launcher://navigate?path=/library/connectors/ <omniverse-launcher://navigate?path=/library/connectors>`__

- Exchange: `omniverse-launcher://navigate?path=/exchange <omniverse-launcher://navigate?path=/exchange>`__
  
  - Detailed app info: `omniverse-launcher://navigate?path=/exchange/app/:slug <omniverse-launcher://navigate?path=/exchange/app/:slug>`__ where ``:slug`` should be replaced with a unique application name.
  - Detailed connector info: `omniverse-launcher://navigate?path=/exchange/connector/:slug <omniverse-launcher://navigate?path=/exchange/app/:slug>`__ where ``:slug`` should be replaced with a unique connector name.

- Nucleus: `omniverse-launcher://navigate?path=/collaboration <omniverse-launcher://navigate?path=/collaboration>`__

Installing Apps
-----------------------

``omniverse-launcher://install`` command can be used to start installing an application. This command requires 
two query arguments:

Query Arguments
###################

- ``slug`` - the unique name of the installed app or connector.
- ``version`` - the version that needs to be installed.

Example
#################

`omniverse-launcher://install?slug=create&version=2020.3.0-rc.14 <omniverse-launcher://install?slug=create&version=2020.3.0-rc.14>`__

The IT Managed Launcher supports only the ``path`` argument that must point to a zip archive downloaded from the 
enterprise portal.

Example
#################

`omniverse-launcher://install?path=C:\Downloads\create.zip <omniverse-launcher://install?path=C:\Downloads\create.zip>`__

Uninstalling apps
-----------------------------

``omniverse-launcher://uninstall`` command can be used to removed installed apps or connectors. This command requires two query
arguments:

- ``slug`` - the unique name of the installed app or connector.
- ``version`` - the version that needs to be uninstalled.

Example
#############

`omniverse-launcher://uninstall?slug=create&version=2020.3.0-rc.14 <omniverse-launcher://uninstall?slug=create&version=2020.3.0-rc.14>`__

Launching apps
------------------

``omniverse-launcher://launch`` command allows users to start the specified application. The launch command will start the app with the specified `slug` and will use the version that is currently selected by user. 

This command requires one query argument:

- ``slug`` - the unique name of the installed app that must be launched.

Example
##########
Starts the current version of Create.    

`omniverse-launcher://launch?slug=create <omniverse-launcher://launch?slug=create>`__ 

.. note:: Users can change their current app versions in the library settings.

Close the Launcher
------------------------

``omniverse-launcher://exit`` command can be used to close Launcher. This command requires no query arguments.

Example
###########

`omniverse-launcher://exit <omniverse-launcher://exit>`__

Open omniverse:// links
-----------------------------

Launcher is also registered as the default handler for ``omniverse://`` links. 
The first time when such link is opened by user, Launcher brings up the dialog to select an Omniverse application
that should be used to open ``omniverse://`` links by default:

.. image:: /content/images/launcher_omniverse-default-app-dialog.png

Example
################

`omniverse://rc.ov.nvidia.com/NVIDIA/Samples/Astronaut/Astronaut.usd <omniverse://rc.ov.nvidia.com/NVIDIA/Samples/Astronaut/Astronaut.usd>`__