Dynamically Load a Mobile-Optimized Version of your Story Map
Update: The June 2017 release of Cascade introduced a new feature, called alternate media, which brought many of the capabilities outlined in this blog post directly to the Cascade builder.
This feature allows authors to add alternate, mobile-friendly images to media sections in their Cascades; these images automatically appear on mobile devices, in lieu of complex or unsupported media, such as 3D webscenes, or webmaps containing lots of vector tile layers. The alternate media feature enables authors to quickly improve the appearance and performance of their Cascades on mobile devices, without requiring them to maintain two separate versions of their story maps, or to host the customized application files on their own servers.
You can learn more about the new alternate media feature in this blog post.
There are still some cases in which it may be preferable to use the manual method outlined in below — for instance, presenting an abridged version of your Cascade on mobile devices, or replacing a 3D webscene with a 2D map instead of a static image, or adding alternate media to a Story Map template other than Cascade. To see how that’s done, read on.
All of the Story Map apps are optimized for mobile devices and feature responsive layouts. Occasionally, however, you may wish to present a slightly different version of your story to readers using small devices. Perhaps the “main,” desktop-oriented version of your story uses 3D scenes, which aren’t supported by most tablets and smartphones; perhaps you’d like to use portrait-orientation images to maximize screen real estate; or perhaps you’d simply like to abridge your story to cater to on-the-go readers.
Fortunately, if you’re hosting story map(s) on your own servers, you can create two versions of your story — one optimized for desktop computers and one for mobile devices — and dynamically load the appropriate version depending on the detected device. This tutorial explains how to configure your self-hosted story maps to recognize the current browser and load the proper application.
Essentials for success
- A desktop-optimized story map, ready to publish
- A web server to host your finished story maps
- A basic understanding of JavaScript (or, at a minimum, the ability to copy and paste)
- A code editor installed (Sublime Text 3, Atom, Notepad++, etc)
Directions:
The first step, and the hardest one, is to create and finalize the full, desktop-optimized version of your story map. For this walkthrough, I am modifying Alexander von Humboldt’s Whole Earth Vision, a Cascade chronicling the life and travels of the famed German explorer. The desktop version of this story includes a 3D scene which, due to hardware limitations, is not visible on mobile devices. I’ve decided to replace the 3D scene with static aerial imagery in the mobile version of the story.
Once you’ve drafted your desktop-optimized story map, you’ll need to create a second version to show only on mobile devices. The best way to do this is to duplicate the original story, and then apply any necessary modifications to the new copy. To do this, navigate to AGO Assistant, a free and unsupported utility that provides a suite of tools for managing content in ArcGIS Online. Once you’ve signed into your AGO account, select “Copy Content” from the dropdown menu, and then select “My Account.”
In the lefthand panel, locate your story map, and then drag it onto the highlighted target in the righthand panel. Voila, you’ve just duplicated your story map! If you return to your ArcGIS Online account, you’ll now see both versions of your story, each with a unique app ID.
Bear in mind that this method does not duplicate any images uploaded to the original version of the app; the new version will continue to reference images attached to the desktop version. Because the images are not duplicated, you’ll need to make sure the original app is shared publicly (or that the photos are hosted elsewhere, such as on Flickr, Google Plus, or your web server). Likewise, this method does not duplicate webmaps, webscenes, or other multimedia content referenced in the application.
Note: the place-based Story Maps—specifically, Map Tour, Crowdsource, and Shortlist—store the content of the story map—images, text descriptions, and such—in the feature layer itself, not the application. So, if you’re using one of these apps, you’ll need to take a few more steps to ensure that your new, mobile-friendly version of the application is referencing a clean copy of the webmap and feature layer. In short, you’ll need to duplicate those items as well, and then update the JSON of the application to point to the proper item IDs. This blog post explains the process in great deal.
To avoid confusion and to ensure you’re always editing the proper version of your story, it’s a good idea to rename one of the application items. I’ve simply appended “Mobile” to my new copy. Renaming the item (in ArcGIS Online or in My Stories) will not change the title of the story, just the name of the item.
Open your mobile-friendly story map in the builder, and make your desired changes. (In this example, I’m simply replacing the 3D scene with static images — easy enough.) You can use your browser’s developer tools to simulate the story map’s appearance on mobile devices (and compare it to the desktop-friendly version). Once you’re satisfied with your changes, download the application source code from the corresponding app page on the Story Maps website (or, if you’re feeling adventurous, from the Github repository).
Unzip the directory and open index.html in your preferred code editor (I’m using Sublime Text 3). Scroll down to the application configuration script, which begins on or around line 41. On line 47, there’s a variable called “appid”. Typically, this is where you’d insert the alphanumeric application ID of your story map, which you can find in the story map’s original URL. But we have two application IDs — one for the desktop version of our story, and one for the mobile version — and so we want the appid variable to change dynamically, depending on the current device. So, instead of pasting in a single application ID, we’ll instead paste in a new variable called “appID” which we’ll create in the next step.
Next, we’ll write a brief script that runs as soon as the page loads, determines the current device, and uses this information to pass the appropriate application ID to the the “appID” variable you added in the previous step.
Copy the code snippet above, and paste it into index.html, right before the application configuration script (around line 40 in Cascade). Then, replace the placeholder text with the appropriate application IDs, where indicated (but leave the single quotation marks in place). This is what it looks like in my version:
That’s basically it. While you’re still editing index.html, don’t forget to add some descriptive metadata, so that your application is easy to find and looks great on social media.
Save index.html, and upload it (and all the other application files) to your web server. Test out the story on a computer and a mobile device. Now, when a reader loads your story, they’ll see the version optimized for their current device. That wasn’t so hard, was it?
