Administrator Help

Open topic with navigation

Viewer URLs

URLs (Uniform Resource Locators) are also known as web addresses. For example, http://www.esri.com/ is a URL. A viewer URL is a URL that launches a viewer. In order for a user to launch a viewer, the user must know the viewer's URL, or have access to a hyperlink or QR code that links to the URL.

Geocortex Essentials Manager provides viewer launch links in several places: in the Site List, on the Viewers page, and also on the Viewer Info page for a specific viewer. These links are useful while you are developing and testing a site.

For legibility, URLs and URL parameters are shown unencoded. You should always URL encode your URLs.

Form of a Viewer's URL

The general form of a viewer's URL is:

http://<server.domain.com>/<iis-virtual-directory>/<page>?<url-parameters>

where:

• <server.domain.com> specifies the server that the viewer template is deployed to.

• <iis-virtual-directory> is the virtual directory in IIS that the viewer template is deployed to.

• <page> is the name of the page to launch, for example, Index.html.

• <url-parameters> are the parameters that allow you to control how the viewer launches—the extent that is initially shown, the language that is used, and so on.

The simplest URL to launch an HTML5 viewer is:

http://<server.mydomain.com>/<iis-virtual-directory>

This launches the default page, Index.html, for an unsecured site. The default page detects the type of device and launches the appropriate interface: Desktop, Tablet or Handheld.

To explicitly launch the Tablet interface for medium-format, touch-screen devices like tablets, use Tablet.html as the <page>. To explicitly launch the Handheld interface for small-format, touch-screen devices like smartphones, use Handheld.html as the <page>.

Determine the Launch URL for a Particular Viewer

To find the URL for a particular viewer, launch the viewer and copy the URL from the browser's address bar. To launch the viewer, click the viewer's Launch URL link in Manager.

Launch URL for an HTML5 viewer, shown on Manager's Viewers page

Note that the viewer URLs that Manager displays are not the full URL—it is just the link text. For example, the full URL for the link shown above is actually:

http://MyServer.com/Html5Viewer/Index.html?configBase=http://MyServer.com/Geocortex/Essentials/REST/sites/LA_County/viewers/LA_County_HTML/virtualdirectory/Resources/Config/Default

URL Parameters

A URL parameter is a string attached to a URL that specifies initial values or actions. For example, you can use the extent URL parameter to make the map zoom to a particular extent when the viewer is launched. From the end user's point of view, the URL parameter's value is the default value. For example, to the end user, the extent at which the map loads is the default extent.

To specify a URL parameter, you add a question mark to the end of the URL, followed by parameter=value. The general form is:

http://server.domain.com/vwr/Index.html?parameter=value

A URL can have multiple parameters. Parameters are separated by the ampersand character (&). The general form is:

http://server.domain.com/vwr>/Index.html?parameter1=value1&parameter2=value2&...

URL Parameters to Load Configuration Files

For a viewer to launch, the viewer must load a configuration file. If you know what type of device the end user will be using, you can specify which configuration file to load. If the viewer will be launched on different types of devices, you can let the viewer detect the device type and load the appropriate configuration file.

The viewer launch URL has two parameters that you can use to tell the viewer how to locate the configuration file to load:

• configBase: Specify the folder that contains the three different configuration files, and let the viewer detect the type of device and load the appropriate configuration file. The launch links in Manager use the configBase parameter.

• viewerConfigUri: Specify which configuration file to load. This parameter overrides the configBase parameter.

Example

In this example, the Handheld interface of the LA_County site's LA_County_HTML viewer launches in Canadian French with debugging turned on. The site is not secured.

http://server.domain.com/vwr/Handheld.html?configBase=http://server.domain.com/Geocortex/Essentials/REST/sites/LA_County/viewers/LA_County_HTML/VirtualDirectory/Resources/Config/Default&locale=fr-CA&debug=true

URL Parameters Reference

For legibility, URLs and URL parameters are shown unencoded. You should always URL encode your URLs.

Short Viewer URLs

You can set up a short launch URL for a particular viewer that has the form:

http://MyServer.com/Html5Viewer/index.html?viewer=MyViewer

There are a few different ways to set up the value for the viewer parameter:

• Configure the Global Unique ID.

  We recommend this method because it is both the easiest and the most robust in terms of upgrading the viewer.

• Configure a short viewer URL in the ViewerSettings.json.js file.

  This method may slightly improve performance but requires manually editing a viewer configuration file. Any changes will also survive after upgrading the viewer. This method overrides the previous method.

• Configure a short viewer URL in the Index.html file.

  This method offers the greatest performance but is also the most fragile. Any changes must be reapplied after upgrading the viewer. We do not recommend using this method. This method overrides the previous methods.

Configure the Global Unique ID

To configure the Global Unique ID by editing the viewer:

1. In Geocortex Essentials Manager, edit the viewer that you want to configure—edit the site that the viewer belongs to, click Viewers in the side panel, and then click the Edit icon beside the viewer.

2. On the Viewer Info page, type any value without special characters for Global Unique ID. For example, MyViewer.

   As the name suggests, the Global Unique ID must be unique for each viewer across all sites and instances of Essentials.

   The Global Unique ID must not contain special characters such as <, >, %, &, :, *, \, / and ?.

3. Click Apply Changes.

4. Click Save Site.

   The Launch in Browser link now contains the short launch URL in the form of:

   http://MyServer.com/Html5Viewer/index.html?viewer=MyViewer

   where the viewer parameter is the same value as the Global Unique ID of the viewer.

   If you do not set the Global Unique ID, all viewers use the default Global Unique ID, which consists of the Site ID and the Viewer ID separated by a period character. For example, http://MyServer.com/Html5Viewer/index.html?viewer=MySiteID.MyViewerID.

Configure a Short Viewer URL in the ViewerSettings.json.js File

To configure a short viewer URL in the ViewerSettings.json.js file:

1. In the root folder where the HTML5 Viewer is installed, open the ViewerSettings.json.js file in a text editor. The default location is:

   C:\inetpub\wwwroot\Html5Viewer\ViewerSettings.json.js

   You may need to run your text editor as an Administrator to modify this file.

2. For each viewer, do one of the following:

   • To configure a short launch link for any interface, in the viewerSettings array, add a new object with the following properties.

     The viewerConfigUri property has been deprecated.

     {
         "viewerSettings": [
             {
                 "id": "MyViewer",
                 "url": "http://MyServer.com/Geocortex/Essentials/REST/sites/LA_County/Viewers/LA_County_HTML/VirtualDirectory/Resources/Config/Default/",
                 "securityUrl": ""
             }
         ],
         ...
     }
     

     Set id to any value without special characters you want to use for the viewer parameter.

     Set url to the folder containing the viewer configuration files.

     If the site is secured, set the optional securityUrl property to the Essentials sign-in URL. For example:

     http://MyServer.com/Geocortex/Essentials/REST/security/signin?token_type=fragment&app=

   • To configure a short launch link for a specific interface such as the Handheld interface, in the viewerSettings array, add a new object with the following properties:

     {
         "viewerSettings": [
             {
                 "id": "MyViewer",
                 "viewerConfigUri": "http://MyServer.com/Geocortex/Essentials/REST/sites/LA_County/viewers/LA_County_HTML/VirtualDirectory/Resources/Config/Default/Handheld.json.js",
                 "securityUrl": ""
             }
         ],
         ...
     }
     

     Set id to any value without special characters you want to use for the viewer parameter.

     Set viewerConfigUri to the location of a specific viewer configuration file.

     If the site is secured, set the optional securityUrl property to the Essentials sign-in URL. For example:

     http://MyServer.com/Geocortex/Essentials/REST/security/signin?token_type=fragment&app=

3. If you want the viewer to use a custom splash screen image, add the splashScreenUrl property to the viewerSettings object. Set splashScreenUrl to the image's fully qualified URL.

   When you configure the short URL in the ViewerSettings.json.js file, you must configure the custom splash screen image in the ViewerSettings.json.js file instead of in Manager.

   {
       "viewerSettings": [
           {
               "id": "MyViewer",
               "url": "http://MyServer.com/Geocortex/Essentials/REST/sites/LA_County/Viewers/LA_County_HTML/VirtualDirectory/Resources/Config/Default/",
               "splashScreenUrl": "http://host.domain.com/resources/images/splash-image.png"
               "securityUrl": ""
           }
       ],
       ...
   }
   

4. Save the file.

   You can use the following URL to launch the viewer: 

   http://MyServer.com/Html5Viewer/index.html?viewer=MyViewer

Configure a Short Viewer URL in the Index.html File

To configure a short viewer URL in the Index.html file:

1. In the root folder where the HTML5 Viewer is installed, open the Index.html file in a text editor. The default location is:

   C:\inetpub\wwwroot\Html5Viewer\Index.html

   You may need to run your text editor as an Administrator to modify this file.

2. For each viewer, do one of the following:

   • Within the ViewerInitializationOptions object passed into the ViewerLoader's loadAndInitialize() method, add a new property to the aliases property:

     new geocortex.essentialsHtmlViewer.ViewerLoader().loadAndInitialize({
         aliases: {
             default: "Resources/Config/Default/" + shellName + ".json.js",
             MyViewer: "http://MyServer.com/Geocortex/Essentials/REST/sites/LA_County/viewers/LA_County_HTML/virtualdirectory/Resources/Config/Default/" + shellName + ".json.js"
         }
     });
     

     Set the name of the new property to the ID you want to use for the viewer parameter.

     Set the value of the new property to the location of the viewer configuration file. The shellName variable allows the viewer to load different configuration files for each type of interface: Desktop, Tablet or Handheld.

     Viewers defined using this method override viewers defined using the following alternative method.

   • Within the viewerConfig variable, add a new property to the configurations property:

     var viewerConfig = {
         "configurations": {
             "default": "Resources/Config/Default/" + shellName + ".json.js",
             "MyViewer": "http://MyServer.com/Geocortex/Essentials/REST/sites/LA_County/viewers/LA_County_HTML/virtualdirectory/Resources/Config/Default/" + shellName + ".json.js"
         },
         "viewerConfigUri": null
     };
     

     Set the name of the new property to the ID you want to use for the viewer parameter.

     Set the value of the new property to the location of the viewer configuration file. The shellName variable allows the viewer to load different configuration files for each type of interface: Desktop, Tablet or Handheld.

   The configuration files must be on the same domain as the viewer.

3. Save the file.

   You can use the following URL to launch the viewer: 

   http://MyServer.com/Html5Viewer/index.html?viewer=MyViewer

URLs for Secured Sites

You do not need a different URL to access a secured site—you can use a regular viewer URL, as described above in Form of a Viewer's URL. However, you can improve a viewer's launch performance by using a URL that links directly to the sign-in page. A direct link skips the steps required for the viewer to determine whether the site is secured.

When you link directly to the sign-in page, you pass the viewer's URL as a parameter. This ensures that the user's browser can be correctly directed to the viewer after the user has authenticated.

The general form for a URL that links directly to the sign-in page is:

http://server.domain.com/Geocortex/Essentials/REST/security/signIn?[url-parameters]

For legibility, URLs and URL parameters are shown unencoded. You should always URL encode your URLs.

URL Parameters for Sign-in Page URLs

The table below lists the parameters that you can use in sign-in page URLs.

Find the Value for the idp URL Parameter

The idp URL parameter identifies the security provider to use for authentication. The table below lists the values for different security providers. For Geocortex Identity Server and ArcGIS Online security providers, you need the security provider's issuer seed. Instructions for getting the issuer seed are given below the table.

Values to Use for the idp URL Parameter

Determine a Security Provider's Issuer Seed

To get the issuer seed for a security provider:

1. In Geocortex Essentials Manager, click the Security & Data tab, expand the Security area in the side panel, and then click Providers.

2. Click the Edit icon  beside the security provider whose issuer seed you want to get.

3. In the Advanced area, select the issuer seed and copy it.

4. Click OK to close the dialog box.

5. Paste the issuer seed in the URL's idp parameter.

Example 1 - URL for an HTML5 Viewer and Windows-Secured Site

Suppose you have a site that is secured using the Windows Integrated security provider. The URL below performs the authentication using Windows Authentication, and then launches the HTML5 viewer called MyViewer.

http://server.domain.com/Geocortex/Essentials/REST/security/signIn?token_type=fragment&idp=AD+AUTHORITY&app=http://server.domain.com/viewers/Index.html?Viewer=MyViewer

Example 2 - URL for an HTML5 Viewer and Site that is Secured Using ArcGIS Online

Suppose you have a site that is secured using ArcGIS Online. The URL below performs the authentication using ArcGIS Online, and then launches the HTML5 viewer called mobile in the Handheld interface.

http://server.domain.com/Geocortex/Essentials/REST/security/signIn?token_type=fragment&idp=urn:gcx:ags:9b567ddc-27ab-4321-b968-570df7b53bfe&app=http://server.domain.com/gvh/Handheld.html?Viewer=mobile

Publish Viewer URLs

As the application administrator, you must provide users with a way to launch the viewer. There are different ways to do this:

• URL: Give the viewer's URL to users, so they can type the URL into their browser's address bar.

• Hyperlink: Put a hyperlink representing the viewer's URL on a website or other web-connected resource. Users click the hyperlink to launch the viewer.

  URL-encode your URLs.

• QR Code: Provide a QR (Quick Response) code  in a web or print resource. To launch the viewer, users scan the QR code using a mobile device, such as a smartphone or tablet.

  To display a QR code for a launch link in Manager, hover the mouse pointer over the QR code icon  beside the launch link—the icon will expand into a scannable QR code.