An introduction to hosting your own classic Esri Story Map

This article covers a topic related to the classic Esri Story Maps templates. Story authors are encouraged to use the current-generation ArcGIS StoryMaps to create stories. However, Esri will continue to maintain the classic templates for your use. For more information, see the product road map.

Classic Esri Story Maps are open source. This means you can download the code for any Story Map template from GitHub, host it on your own server, and even customize it.

While the needs of most story map authors will be served using the versions of these apps that are hosted on ArcGIS Online (or an ArcGIS Enterprise portal), there are a few reasons to consider hosting your own.

This article covers why you might host a Story Map app, how an app works when it runs on your server, and step-by-step instructions for hosting your first app.

Why host an app?

There are several benefits to hosting a Story Map app on your own server, the most obvious is you can give your story a custom URL on your organization’s domain. So, instead of the standard arcgis.com URL:

https://www.arcgis.com/apps/Cascade/index.html?appid=abcdef123456…

your story can have a URL like this:

https://www.our-agency.gov/stories/our-latest-story/

Note the example URL above begins with https. It is highly recommended that your story map hosting environment support secure web standards. If your self-hosted story doesn’t support being accessed over https, be sure to talk to your web administrator.

You can also set up web analytics to capture statistics about who’s reading your story and enhance how your story looks when it’s shared on social networking sites like Facebook and Twitter. There’s more information about how to add these improvements later in this article.

If you are a designer who knows HTML and CSS, you can style a Story Map app to change its appearance beyond what is possible in the builder. A popular style change is to add a banner image to a Map Tour, like in the “Kentucky’s Frontier Trails” story from the University of Kentucky and the Commonwealth Office of Technology, Division of Geographic Information (DGI).

Kentucky’s Frontier Trails is a styled Story Map Tour.

Finally, developers can customize an app to add new features. Examples of customizations are adding background audio or a cover page to your story. There are many styled and customized story maps in our gallery that you can review for ideas, and our developer blog has lots of articles about how to make specific customizations.

You’re now familiar with reasons to host a Story Map app. Next, you’ll learn the basics of how it works.

How do self-hosted apps work?

When you host a story map on your own server you only host the app code; your story content is still hosted in ArcGIS Online (or an ArcGIS Enterprise portal). The content includes your story’s text, images, maps, scenes, as well as the story’s configuration settings (does your Map Journal use a side panel or floating panel layout? is a legend visible for the map in section 2? etc).

Your story content is saved in ArcGIS as a web mapping application item that has a unique ID. The ID is the number that can be seen in the URL when you are viewing the story’s item page or the story itself. For example:

https://arcgis.com/home/item.html?id=a22c0c5113e64dd7b9fb6248e4b96c3

https://arcgis.com/apps/Cascade/index.html?appid=a22c0c5113e64dd7b9fb6248e4b96c3

The Story Map app requires a parameter called the appid. By specifying an appid in your hosted app you’re letting it know what story you want it to load. When readers open a link to your story, the app code is loaded into their browser from your server, then the appid you’ve specified in the code is used to find and load the story content from ArcGIS.

How a self-hosted Story Map works.

Images you’ve uploaded in builder while creating your story are stored with your story in ArcGIS, but if you added content from elsewhere on the web — for example, an image from Flickr, a video from YouTube, or a custom chart hosted on your website — the links to those items are stored in the story configuration in ArcGIS, but the content itself is retrieved from its original location.

Source Code and Compiled Code

It’s important to know there are two versions of code available to download for each app:

• The source code is the code Esri’s developers wrote to create the app; it’s what a developer needs to customize an app. The best way to get the source code is to clone or fork it from GitHub. By doing this, you’ll be notified of updates made by the Story Maps Team and can easily incorporate them into your customized app using git’s merge feature. You can find links to all the Story Map app code repositories hosted on GitHub here.
• The compiled code — or minified code — is an optimized version of the source code; it’s what should be used to deploy the app to your web server. If you plan to only make style changes (or no changes at all), you should download the compiled code. Go to the Apps page on the Story Maps website, click Overview next to the app you need, and find the Host it yourself! section at the bottom of the page and then click Download the ready-to-deploy app.

You’ll find links to download the compiled code and source code on each app’s page on the Story Maps website.

The source code comes with documentation on how to build a compiled version of the code, and developers must do this to build a deployable version of their customized app. However, for someone who is not a developer, the process can be a bit difficult to execute. For that reason, we provide a pre-compiled version of the standard app to make it easier for people who are not developers.

You can run an app on your local machine from the source code while developing your customizations, but you should never deploy the source code to a production web server for the following reasons:

• Your story map will take longer to load and run slower since the code isn’t minified or optimized
• Readers may see an Edit button when viewing your story that would let them open it in builder (don’t worry, they won’t be able to save changes)
• Your custom code will be exposed since the JavaScript isn’t obfuscated

Now you know how a self-hosted story map works, that there are two versions of the code, and how to know which one to use.

The last section will get a little more technical and look at three specific hosting scenarios.

What do you need to do?

We’ve observed three common situations in which people look to self-host a Story Map app:

1. Web administrators want to host an app on their own infrastructure to give a story a custom URL, control how the story looks when shared on social networking sites, and/or collect web analytics.
2. Designers want to style an app to make changes to its appearance beyond what is possible in the builder.
3. Developers want to customize an app to add a new feature or change something about the user experience.

Let’s take a look at each scenario and what steps are needed to get the app up and running in each case. See the end of the article for instructions on how to get the correct version of each code for each scenario.

Scenario 1 — Hosting an un-customized app

In this case you’re a web administrator who wants to take advantage of the benefits of hosting the app on your own server like a custom URL and the ability to collect usage statistics. You will not need to alter the app code beyond some minor edits to the index.html file.

Here are the steps to follow to host an app in this scenario:

1. Build your story on ArcGIS Online
2. Download the compiled code for the app you used to build the story
3. Add the appid of the story you built in step 1 to the application configuration section of the index.html file (see code snippet below)
4. Deploy the app to a web server

Below is a portion of a typical index.html file showing where the appid should be added. The line numbers below do not correspond to the line numbers in an actual index.html.

Parameters such as the appid are specified in the Application Configuration section of a Story Map app’s index.html file.

In step 2, you can optionally edit index.html to make these other configuration changes:

• Add an oAuthAppId to let readers login using their ArcGIS account if your story is only shared with your organization. This will also let others use your hosted version of the app to create stories using the builder. To get an oAuthAppId you’ll need to register your self-hosted story map on ArcGIS Online.
• The authorizedOwners parameter controls which ArcGIS members’ stories can be viewed using your custom app using the appid URL parameter. Comments in the index.html file tell you how to use this.
• Add your web analytics code snippet and key to collect usage stats about your story.
• Add info to the <meta> tags to control how your story looks when it’s shared on social networking sites.

These articles have more information about the configuration options described in the last two bullets, above:

Adding Google Analytics to your Story Maps

Improving how your self-hosted Story Map looks on social media

Scenario 2 — Make style changes to the app

To make style changes that alter the colors, layout, or appearance of the app you’ll only need to modify the app’s CSS and you can do this by using <style> tags in index.html.

Here are the steps you need to follow to perform style changes to a story:

1. Build your story on ArcGIS Online
2. Download the compiled code for the app you used to build the story
3. Make changes to the app’s appearance by adding <style> tags to index.html
4. Add the appid of the story you built in step 1 to the application configuration section of the index.html file (you can also make any of the optional changes described in scenario #1)
5. Deploy the app to your web server

Note: Map Journal has an HTML editor that you can use to make style changes even when using the hosted version of the app. See this article for more information.

Create Buttons for Story Actions in Map Journal

Scenario 3 — Adding new features

Customization is the most extensive type of modification you can do to an app, and you’ll need to be a JavaScript developer to do this. For example, you may want to add data-driven text or audio to your story or maybe you want to add an index map to your Map Journal.

Whatever alterations you are making, the basic steps you’ll follow when customizing an app are:

1. Build your story on ArcGIS Online
2. Clone the source code for the app you used to build the story from GitHub
3. Add the appid of the story you built in step 1 to the application configuration section of the index.html file (you can also make any of the optional changes described in scenario #1)
4. Make customizations to the app
5. Build a compiled version of the app (as described in the app’s readme)
6. Deploy the compiled version of the app to your web server

If you’ve never worked with Story Map code before, this article about getting your development environment up and running will be helpful:

Set up your Story Maps development environment

Other Considerations

Should I update my app after each new release?

Esri releases updates to ArcGIS Online several times a year, but you don’t have to update your app if your story is working as expected. However, you can update it if there are enhancements or fixes that will improve your story.

If you’ve made customizations, you’ll need to merge the updates into your version of the source code then build a compiled version to deploy on your server. If you’ve made no changes or only style changes you can just download the latest compiled version.

The process is simple: just keep your index.html (remember, that has your appid and other configuration changes) and replace the rest of the app on the web server with the updated version. Make sure to test your story with the updated app locally before deploying it to your production server.

What if I’m using Enterprise?

If you are using an ArcGIS Enterprise portal, you’ll build your story on your portal and add its appid to the index.html file in the same way described above, but you’ll also need to add the sharingurl parameter in the configurationOptions section of your index.html. For example:

sharingurl = "//my.portal.gov/sharing/rest/content/items"

More Information

If you plan to try your hand at hosting one of Esri’s Story Map apps, be sure to check out these other articles for more tips and tricks about this process:

Getting the most out of your customized storytelling app — part 1

Getting the most out of your customized storytelling app — part 2

Host Your Story Maps for Free with Surge

Tech Session from the 2017 Esri Developer Summit on customizing Story Maps.

This article was originally published in Mar 2017 and was updated in Sep 2017.