Using URL parameters and markers in ArcGIS Experience Builder for ArcGIS Online and ArcGIS Enterprise

Summary

Using markers on a Map widget in an ArcGIS Experience Builder app can be a useful way to provide viewers with a clear point of reference. By highlighting a specific location when launching the experience, viewers can quickly orient themselves and focus on the area that is most relevant.

Within Experience Builder, this can be particularly useful when sharing an application centered on a specific area or point of interest, or guiding viewers directly to a feature without requiring them to manually search for it. 

URL Parameters provide a customizable way to achieve this functionality.

Cause

This workflow can be done in both ArcGIS Online and in ArcGIS Enterprise, although the URL formats for Experience Builder items look slightly different.

The ArcGIS Online URL format to point to the desired Experience item is as follows:

https://experience.arcgis.com/experience/<experienceItemID>

In ArcGIS Enterprise, the URL format for an Experience item will look like:

https://<portalMachineName>/portal/apps/experiencebuilder/experience/?id=<experienceItemID>

These URL formats are the starting point for creating URLs with parameters to add a Marker to a Map Widget.

Note: 
If you are using ArcGIS Experience Builder in ArcGIS Enterprise 11.5, this functionality may not work as expected. However, this behavior does not occur in ArcGIS Enterprise 12.1, and works as expected. 
See: BUG-000187160

Procedure

URL Parameter Formatting:

1. Required Parameters:
   Once you have the base URL to point to the Experience item, we can start appending our parameters to define our marker. Parameters that are crucial for the marker functionality are:

#<mapWidgetID>

followed by

=marker:<x>,<y>

• #<mapWidgetID> defines what widget ID corresponds to the Map widget in your Experience. If the Map widget is added as the first widget in the experience, the map widget ID will be 1. The parameter in the URL would, therefore, look like #widget_1.

Note:
If you are unsure of the widget ID for your map widget, you can use Developer Tools in a browser to find it.

1. With the published experience open, open Developer Tools.
2. In the top of Developer Tools, select the Elements tab. To search within the elements, you can use the keyboard shortcut Control + F. In the search bar, enter "widget_", and hover over the various results, until the Map widget in the Experience is highlighted. The corresponding element should also highlight in the list, to easily identify the widget ID.

• =marker:<x>,<y> is the other required parameter to place a marker, as it is necessary to define coordinates for a point where the marker is located. 
  • By default, the X and Y coordinates are in WGS 84, as that is the default projection for ArcGIS Map Viewer.

2. Optional Parameters:
   There are also many additional optional parameters that can be used to customize the marker's appearance in the Map widget. These parameters must be separated by a semicolon (;). The documentation states that these parameters must go in a specific order, and that order is as follows:
   1. <wkid>
      • If you are using a custom basemap in a specific projection, you can define a different coordinate system for the marker, using their respective codes.
      • For example, WGS 84's wkid code is 4326.
   2. <title> 
      
      • Use this parameter to specify a title that appears in the marker pop-up.
   3. <label>
      • Use this parameter to add a label to the marker's point.
   4. <symbol>
      • There are quite a few properties that make up the umbrella <symbol> parameter, as you can customize the color, style, size, outline, etc. of the marker point. 
      • You can use simple marker symbols (includes geometric symbology) and picture marker symbols (includes images as symbology). Simple Marker Symbol includes properties such as style, color, and outline, for symbology customization, and require specific formats for their URL parameters.
        • Style represents the shape of the marker. A few of the valid shapes include, circle, diamond, square, triangle, cross, etc. In a URL, these should be entered as "esriSMSCircle", "esriSMSSquare", "esriSMSTriangle", etc.
        • Color is represented in a 4 element array, including color values for red, green, blue and alpha, in that order. For example, the array code for red is [255,0,0,255].
        • Outline almost combines style and color, as you can define a color for the outline of the shape, and a style for the line itself. A few examples of these line styles include, "esriSLSDash", "esriSLSDot", "esriSLSLongDash", and more.
      • Documentation listed in the Related Links section goes more into depth about these symbol customization properties.

URL Assembly:

Here is a template of the parameters to append to a URL for an Experience:

#<mapWidgetID>=marker:<x>,<y>;<wkid>;<label>;<symbol>

1. Start with a base URL.
   The example URL below defines the widget ID, and the x & y coordinates for the point. This URL places a point marker on the city of Seattle, using the default appearance.

https://experience.arcgis.com/experience/123456789101112131415abcd#widget_1=marker:
-122.33%2C47.61

Note:
You may notice that instead of a comma (,) separating the x and y coordinates, "%2C" takes its place. When formatting your URL, it is important to note that some characters are considered preserved URL delimiters. 
To ensure that the URL and the characters you enter are interpreted correctly, you will need to encode characters by replacing them with the UTF-8 hexadecimal equivalent. See the table below.

This table is a list of a few common characters that may be necessary to encode to include them in URL parameters:

2. Add Optional Parameters.
   The documentation describes that you must use empty values if you want to include some parameters, and not others. For example if you only want to specify the symbol of the marker and nothing else, you'll need to add semicolons to account for the missing parameters (Example: <x>,<y>;;;;<symbol>).
   
   For our example, we only want to add a label to our marker, to easily identify what location our marker is pointing out. We can add semicolons in place of other parameters we want to skip. The URL to add our "Seattle" label will look like this:

https://experience.arcgis.com/experience/123456789101112131415abcd#widget_1=marker:
-122.33%2C47.61;;;Seattle

Encoded, it will look like this:

https://experience.arcgis.com/experience/123456789101112131415abcd#widget_1=marker:
-122.33%2C47.61%3B%3B%3BSeattle

3. Customize Marker Appearance:
   For example, we want to make our marker symbol a red triangle with a blue outline. So now we need to add the parameters for style, color, and outline, to format our symbol.
   • To ensure our symbol properties are grouped together properly, we will need to use brackets ( { } ) to enclose the style parameters.
   • In our first set of brackets, to define the style of our marker, we need to specify our symbol type, style, color, and size: "type":"esriSMS","style":"esriSMSTriangle","color":[255,0,0,255],"size":12
   • Note our color format, using the four-value RGBA code. The above code is the RGBA code for red.
   • Our second set of brackets will be enclosed within our first set of brackets, to define the same properties, but this time about our outline of our marker: "type":"esriSLS","color":[0,0,255,255],"width":1
   • The above type "esriSLS" represents a solid line, and the RGBA code corresponds to blue.
4. Putting It All Together:
   The resulting URL combining this customization will look like this:

https://experience.arcgis.com/experience/123456789101112131415abcd#widget_1=marker:
-122.33,47.61;;;Seattle;{"type":"esriSMS","style":"esriSMSTriangle","color":
[255,0,0,255],"size":12,"outline":{"type":"esriSLS","color":[0,0,255,255],"width":1}}

Encoded, it will look like this:

https://experience.arcgis.com/experience/123456789101112131415abcd#widget_1=marker:
-122.33%2C47.61%3B%3B%3BSeattle%3B%7B%22type%22%3A%22esriSMS%22%2C%22style%22%3A%22
esriSMSTriangle%22%2C%22color%22%3A%5B255%2C0%2C0%2C255%5D%2C%22size%22%3A12%2C%22
outline%22%3A%7B%22type%22%3A%22esriSLS%22%2C%22color%22%3A%5B0%2C0%2C255%2C255%5D
%2C%22width%22%3A1%7D%7D

These are just a few examples and possibilities of how to use URL parameters to add a marker to your map in ArcGIS Experience Builder! Additional customization options can be found in the documentation. Get creative!

Note: 
Some URL Parameters also have configurable options that are available through the Experience Builder web application. Authors can use the built-in configuration tools to add a marker to a map widget. This is a great option because setup is simplified, making it is easier to implement common URL parameter functionality without needing to edit the URL syntax directly.