How to Call Client using URL?

This article explains how Nx URL scheme allows calling Nx Desktop or Nx Mobile applications via a link from the browser. For example, the link can open a specific camera to a specific timestamp in Nx Mobile. Our URL scheme is supported by all native client applications (Windows, Mac, Linux, iOS, Android).

Currently, calling the mobile application via browser address bar only works in iOS. To use the call client URL in Android OS, it must be in the form of a hyperlink. To test this, create an HTML page with a hyperlink <a href=URL>text</a>.

Note: You can also open Nx Desktop via the CLI by utilizing the URL format.

General URL Format

The general format is used for calling the desktop or mobile clients:

{protocol}://{domain}/{client_command}/{system_id}/{system_action}?auth={access_key}&{action_parameters}

{protocol}: Protocol depends on the specific Powered-by-Nx product. For calling Nx Witness or Nx Mobile, the protocol is nx-vms. 

{domain}: Typically, this is the cloud portal domain (e.g. nxvms.com). Alternatively, it can be substituted with serverip:port for accessing the web client locally. 

{client_command}: Use the value “client” to connect to the system.

{system_id}: This is a unique identifier for the System on Nx Cloud. To retrieve your System ID, refer to this article and follow the last section.

{system_action}: Use the value “view” to open the client or the web player.

{access_key}: An access key is used in the general format to authenticate the URL and gain access to the system without manually logging in. The access key is placed after "?auth="; without it, the link would just display the “incorrect username/password” error in the client. A permanent access key doesn't expire and doesn’t change unless the original login information changes. If you are using the cloud domain in the URL, you must create an access key based on your cloud login information, while if you are using serverip:port, then use the server login. 

To create a permanent access key:

1. Encode your login and password to base64 using the format “login:password”
2. Use the value it produces as your access key

{action_parameters}: For this parameter, you would input resources and timestamp if you wanted to pull up a specific camera and go to a timestamp in the camera’s archive with the call link. Refer to the sections below for more information on resources and timestamp.

What can you do with URLs?

All links will start off from your base URL, which by itself opens the client if installed:

nx-vms://nxvms.com/

To open the client and log into the cloud, use these two formats:

nx-vms://nxvms.com/client/d0b73d03-3e2e-405d-8226-019c83b13a08?auth=YWJyYTprYWRhYnJh

nx-vms://nxvms.com/client/d0b73d03-3e2e-405d-8226-019c83b13a08/view?auth=YWJyYTprYWRhYnJh

Note: You can also use the URL in a CLI command. 

How to open specific cameras?

The resource value contains the list of resource identifiers (ID) you want to open with the link. Multiple cameras should be split up using a colon and are placed after “resources=” as an action parameter. 

Following the example below, the link opens the client and connects to the server with the specified authenticator; if successful, it opens the resources dialog with the two cameras, specified each by their camera ID:

nx-vms://nxvms.com/client/systemid/view?auth=YWRtaW46cXdlYXNkMTIz&resources=ed93120e-0f50-3cdf-39c8-dd52a640688c:04762367-751f-2727-25ca-9ae0dc6727de

How to open the video archive?

The timestamp value specifies the position for the cameras (in ms since epoch). It requires at least one value in the resources parameter. The timestamp (also an action parameter) should be placed after resources as “&timestamp=”, in milliseconds. 

Following the example below, the link opens the client and connects to the server with the specific authenticator; if successful, it opens the camera (specifically the first resource ID in the URL) and sets it in an archive position specified by the timestamp parameter:

nx-vms://nxvms.com/client/systemid/view?auth=YWRtaW46cXdlYXNkMTIz&resources=ed93120e-0f50-3cdf-39c8-dd52a640688c&timestamp=1520110800000