How to Call Client Using URL?

This article explains how the Nx Witness URL format allows you to call Nx Witness Desktop or Nx Witness Mobile through a link from the browser, or other applications.

For example, the link can open a specific camera to a specific timestamp in Nx Witness Mobile. The URL format is supported by all native client applications (Windows, Mac, Linux, iOS, Android).

You can also open Nx Witness via CLI by utilizing the URL format.

Note: Currently, calling the Nx Witness Mobile client 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>.

General URL Format

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

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

{protocol}: The protocol depends on the VMS. For calling Nx Witness or Nx Witness Mobile, the protocol is nx-vms. 

{domain}: This is the cloud portal domain (e.g. https://nxvms.com). 

Only when using http as the protocol instead of nx-vms, you may use your serverip:port as the domain to directly access the Web Admin locally. For this, you would need to have the auth key (base64 format) matching your server login information as opposed to your cloud login (if using domain). 

An example of this is the following URL (alternatively, you may leave out the view and auth portion, but you will be prompted for the server login information):

http://localhost:7001/view?auth=YWJyYTprYWRhYnJh

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

{system_id}: This is a unique identifier for the Nx Witness System. To retrieve your Cloud System ID, open your server in Nx Cloud. The string that appears after "https://nxvms.com" is your Cloud System ID.  Alternatively, you may use serverip:port.

A few examples of serverip:port being implemented are the following URLs:

nx-vms://nxvms.com/client/localhost:7001/view?auth=YWJyYTprYWRhYnJh

nx-vms://nxvms.com/client/nxee.fairddns.com:7001/view?auth=YWJyYTprYWRhYnJh

{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 open an “incorrect username/password” dialog box in the client. A ‘permanent' access key doesn't expire and doesn’t change unless the original login information changes. However, if you are using the cloud domain in the URL, you must create an access key based on your cloud login information. If 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

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/d0b73d03-3e2e-405d-8226-019c83b13a08/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). Requires at least one value in resources parameter. 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 timestamp parameter:

nx-vms://nxvms.com/client/d0b73d03-3e2e-405d-8226-019c83b13a08/view?auth=YWRtaW46cXdlYXNkMTIz&resources=ed93120e-0f50-3cdf-39c8-dd52a640688c&timestamp=1520110800000