Prompting the DW Spectrum® Client to Launch Using a URL
-----------------------------------
Affected Roles: Administrator, Owner
Related Digital Watchdog VMS Apps: DW Spectrum® IPVMS
Complexity: High
Software Version: DW Spectrum® IPVMS v4.2 or higher, DW Spectrum® Mobile
Last Edit: November 16, 2021
-----------------------------------
Alternate Methods for Calling DW Spectrum to Display
Example scenario: The owner of a DW Spectrum system sends a web link to a user that they can be entered into a web browser on either a phone or a DW Spectrum Client machine (computer). By doing so, the URL would prompt the DW Spectrum Mobile application or the desktop client on the device being used, to launch and automatically display a specific camera’s archived video, at a specific point in the timeline. This could save the user the time from having to comb through the server’s archived footage to find that specific section of video.
This article will outline the format to create a URL address that can be used to launch the DW Spectrum Client desktop software or the DW Spectrum Mobile application, when used on a local device.
Using dw-vms Protocol Format
The general format this is used for calling the desktop or mobile client to display is:
{protocol}://{domain}/{client_command}/{system_id}/{system_action}?auth={access_key}&{action_parameters}
- {protocol} – use the protocol “dw-vms”; this represents the protocol that should be used depends on which DW Spectrum product is being used.
- {domain} – use “dwspectrum.digital-watchdog.com”; this represents the target domain of the URL, in this case it is the DW Spectrum Web Portal
- {client_command} – use the value “client” to connect to the system; this value represents the command to use the DW Spectrum Client
- {system_id} – use the Cloud System ID of the target DW Spectrum system. Alternatively, you may use the format of Server_IP:Port (ex. “192.168.1.100:7001”) instead of a Cloud System ID.
- {system_action} – [optional] use the value “view” to have the URL prompt and display the specified system and/or camera
- {access_key} – [optional] use the value “
?auth=
”, followed by a base64-encrypted access key to authenticate the URL and gain access to the DW Spectrum system without having to manually log in. This access key represents the login information of the user. If an access key is not included in the URL, the link will result in an “incorrect username/password” dialog box that will display in the DW Spectrum client. Use of a ‘permanent’ access key will not expire and will not change unless the details of the login information changes. Refer to the sections below for more information on how to create an access key. - {action_parameters}: [optional] – 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.
**NOTE: To find the Cloud System ID, you may refer to the article “Locating the DW Cloud System ID” for instructions.
**NOTE: If you are using the DW 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.
Creating a Permanent Access Key
To create encode a login into a permanent base64-encrypted key:
- Using a web browser, visit https://www.base64encode.org/ to use the base64 encoder tool.
- In the Encode to Base 64 format box, enter the User ID and Password of the user’s DW Spectrum login with the format of “User_ID:Password”.
For example, a User ID of “admin” (default) and Password of “admin12345” (default), would be “admin:admin12345”.
- Next, set the Destination character set to “UTF-8”.
Set the Destination newline separator to “CRLF (Windows)”.
Enable the “Perform URL-safe encoding (uses Base6URL format)” setting.
- When ready, click the “Encode” button. The resulting base64-encoded entry will then display the encoded access key.
Copy and paste the base64-encoded access key into the “{access_key}” portion of the URL.
Opening to a Specific Camera
The resource value “{action_parameters}”can be used to specify a 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:
dw-vms:// dwspectrum.digital-watchdog.com/client/d0b73d03-3e2e-405d-8226-019c83b13a08/view?auth=YWJyYTprYWRhYnJh&resources=ed93120e-0f50-3cdf-39c8-dd52a640688c:04762367-751f-2727-25ca-9ae0dc6727de
Opening a Video Archive to a Specific Timestamp
The timestamp value specifies the position for the cameras (in ms since epoch). To use this, it is required to use at least one value in the resources parameter. The Timestamp (also an action parameter) should be placed after resources as ×tamp=, 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:
dw-vms://dwspectrum.digital-watchdog.com/client/d0b73d03-3e2e-405d-8226-019c83b13a08/view?auth=YWJyYTprYWRhYnJh&resources=ed
Example dw-vms DW Spectrum Web Portal URLs
Below are example URLs created from the information above.
All links will start off from the basic URL, which will launch the client when the DW Spectrum Web Portal domain is used by itself.
dw-vms://dwspectrum.digital-watchdog.com/
Opening the client by using the Localhost as the address
dw-vms://dwspectrum.digital-watchdog.com/client/localhost:7001/view?auth=YWJyYTprYWRhYnJh
Using the serverip:port (ex. 192.168.1.100:7001) as the address
dw-vms://dwspectrum.digital-watchdog.com/client/192.168.1.100:7001/view?auth=YWJyYTprYWRhYnJh
Using a DDNS as the address
dw-vms://dwspectrum.digital-watchdog.com/client/dwexample.dwddns.com:7001/view?auth=YWJyYTprYWRhYnJh
Using the DW Cloud System ID to log in
dw-vms://dwspectrum.digital-watchdog.com/client/1750d3ef-f2c5-4cf1-acef-255dc3b2197d/view?auth=YWRtaW4vYWRtaW4xMjM0NQ
**NOTE: The DW Cloud System ID in the example above is partially redacted for security and privacy reasons.
Using HTTP Protocol Format to View Through a Web Browser
An easy option for viewing a local server’s archived or live video footage is to connect directly with the DW Spectrum System’s Web Client. This web viewer function can be utilized for viewing purposes as an alternative option to using the DW Spectrum desktop client.
To connect with a system’s web client, use the URL format of:
http://{serverip:port}/view?auth={access_key}
When the attribute “http” is used as the protocol instead of “dw-vms”, the value for “serverip:port” and can be used as the domain to directly access the web client locally. For this, you would need to have an authentication key (base64 format) that matches the server login information as opposed to using a DW Cloud login (if using the domain).
- http – use this protocol to communicate data through the local network or the Internet
- serverip – use the local IPv4 address or DDNS address of the DW Spectrum server; alternatively, if the local device that is being used is also hosting the server, then the local address of “localhost” or “127.0.0.1” may be utilized instead
- port – use the TCP/IP port of the DW Spectrum server program; default is Port 7001
It is optional to use the “view” and “auth=” portions of the URL, but you will be prompted to enter the server login information upon connecting if they are not implemented. However, including such information will instead allow automatic authorization by using encrypted access information.
- view – [optional] use this to immediately begin viewing after the DW Spectrum Client has connected with the system
- {access_key} – [optional] use this to automatically authenticate the connection to the DW Spectrum system by using a permanent access key; the access key must be in a base64-encoded format (see the Creating a Permanent Access Key section above for instructions)
Example HTTP DW Spectrum Web Portal URLs
The first example is that of a connection to the web portal of a DW Spectrum Server that is installed on the same local computer that is also being used for viewing. This will prompt a connection to the server’s web portal, but will require the user to enter their DW Spectrum login credentials.
http://localhost:7001/
The second example is of a connection to the web client of a specific DW Spectrum Server by using its local IPv4 address and TCP/IP port information. By including a base64-encrypted access key to view the local system, the web client will automatically log into the system.
http://192.168.1.160:7001/view?auth=anRlc3Q6QzNyYmVydXMhMTYyMjA
Using an Android Mobile Device
The use of the dw-vms URL format is supported by nearly all native DW Spectrum client operating systems (Windows, Linux, iOS, Android). However, calling the DW Spectrum Mobile application by using a web browser is currently supported on iOS devices only.
To use a URL to launch the DW Spectrum Mobile application in Android OS, it must be accessed through the form of a hyperlink.
To test this, create an HTML page with a hyperlink using the attribute <a href=URL>text</a> in the mobile device’s browser.
For example, an HTML hyperlink similar to below will result in clickable text that links to the specified address.
<a href=http://127.0.0.1:7001>Click Here</a>
Example HTML Result: Click Here