June 2020 update: In our latest release of ArcGIS StoryMaps we’ve added additional functionality to the embed block. You can now get a better preview of what your embed will look like for readers on smaller screens within Embed properties. Another handy new option is the ability to see and copy the link or code for an embed if you need to re-use or adjust it.
In my last post, I talked a bit about immersive blocks in ArcGIS StoryMaps, and how they’re powerful tools for getting readers engrossed in the story you’re telling. Well there’s another tool in your toolkit—or, more accurately, block on the block palette—that can help you create the kind of delightful and informative experiences your audience craves.
I’m talking about the embed block. With it, you can add all kinds of things to story maps: Tweets, SoundCloud tracks, Spotify playlists, interactive charts, ArcGIS apps… the list goes on and on. Embedding web content is a great way to add important context, crowdsourcing elements, or just an element of fun to your story, all of which help leave a lasting impression on anyone who comes across it.
The key to success with external web content, though, is creating a seamless, positive experience for your readers. That’s not always an easy task. Luckily, the StoryMaps builder does a lot of work behind the scenes to get the technical details right so you can focus on your narrative instead.
To help you become an embed master, let’s spend a little time going over all the nitty-gritty details. Those details include:
- How to add embedded content
- The different types of embeds
- How embeds can appear
- Where you can add embeds (and why that matters)
- Considerations for mobile readers
- Some practical tips
That might seem like a lot to cover, but I promise to keep it as brief as possible. I’ve also included a downloadable cheat sheet to help keep all this info fresh in your mind.
Ready? Let’s dig in.
Adding content with the embed block
Once you’re signed in to your account, have opened StoryMaps (at storymaps.arcgis.com), and are in the builder, adding an embed is pretty easy. Simply open up the block palette with the green (+) and click Embed. Up pops a field where you add in your content by pasting in either a link or iframe code. Each way of adding content has its own perks, but I’ll get to those details in a bit. Either way, once you’ve pasted in the reference to your content, click Save and you’re off to the races.
Right away, the builder starts doing some behind-the-scenes decision-making to ensure that what you’re adding is delivered to your readers in the best way possible. This process takes into account a few different things, like the type of content being embedded, its appearance options, where in the story its being added, and how it will look on different screen sizes.
The choices available to you as an author will vary depending on the combination of these variables, so let’s unpack each one a bit and then see how they all work together.
The four types of embedded web content
First things first, let’s look at the kinds of content you can embed in your story map. While potential web sources are many, their content can all be categorized into four core types of embeds:
These are images that are already hosted online, perhaps on Flickr or your own private server, and are added to your story via a link instead of being uploaded directly from your machine.
You know, like the ones available on YouTube, Vimeo, or Dailymotion. The story builder supports dozens of different video providers; add content from them to your story with a link or iframe code.
Some trusted embed sources provide special information about their content, which the StoryMaps builder uses to optimize the display and reading experience for that embed. Twitter and SoundCloud are two examples, but there are loads more.
For the builder to gather that extra info, however, you’ll need to add this content with a link. (If the term OEmbed API means anything to you, that’s the kind of thing that’s at play here. If you read that and your response was “huh?” don’t worry, you can get by just fine without knowing what that means.)
This category consists of content like ArcGIS apps, websites, and other full-page content that provides the basic embed info when referenced with a link. Non-video content you’ve added via iframe also falls into this bucket. If you’re embedding an ArcGIS app, be sure to share it publicly first.
Ok, that’s pretty much it for embed types. Moving on…
The three different ways embedded content can be displayed
To help create a seamless reading experience, the story builder has three different ways it can display embedded content. Before we look at where these different views come into play, let’s first get an understanding of what each one is, and why it’s useful.
Cards appear as handy little link previews, pulling a title, description, and thumbnail from the embedded content. These cards are also themed, so they match the look and feel of your story.
Cards are nice way to include related resources in your story for the extra-curious individual without taking too much attention away from your main story. They’re also great for creating a list of recommending reading at the end of your story. Once clicked, the card simply opens that content in a new browser tab.
Any type of embed can be displayed as a card if you so choose—use the toolbar that appears above an embed to move between the card and live view. For some content a card may be the only available option, either for security reasons or because the content source prevents live embedding.
You can customize the appearance of a card through the embed properties panel (click the gear icon to open this up). There you can adjust the title and description for the card, upload a custom thumbnail, or reset all the information to what was originally supplied from the content’s source.
While cards simply provide a summary of the content they reference, live embeds integrate it right into your story. Readers can view the linked material alongside your text and other media, and can even interact with it all in the same space.
If the external web content you’re adding is pretty critical to your story—maybe it provides more nuance to your discussion or gives your readers a chance to explore some data you’re presenting—a live embed is likely your preferred choice.
Photo and video embeds will appear as live content automatically (though of course there’s no interactivity with a photo). Because of the behind-the-scenes optimization, rich embeds will also be added as live content.
Simple embeds will usually be added as a card at first, but will give you the option to switch to live content (minus the two exceptions noted above). When these embeds become live, you’ll notice that they require an initial click to enable interaction. That’s because the story builder doesn’t have enough information to ensure readers won’t get caught in any sticky situations—like stuck in a scroll within a scroll—if interaction is automatically enabled.
While live content can be great, it doesn’t always provide the best experience on small screens and mobile devices. In these instances, the gist of an embed is conveyed through an image that you upload as alternative media. When you upload an alternative image, you also have the option to make it clickable, so that readers can tap on it to open that content in a new tab.
If you forget to upload an alternative image, the builder will provide a generic placeholder to alert your reader that there’s more to the story. This placeholder also includes a link to open the embedded content in a new tab.
The three places you can add embeds (and why that matters)
Ok, time for a quick recap. So far we’ve established that you can add external web content to your story via a link or iframe code. This embedded content can fall into one of four categories (photo, video, rich, or simple), and there are three possible ways it might be displayed (card, live, or alternative media). Now let’s bring it all together by looking at where in your story maps you can add different types of embedded content, and how that placement will influence the way it appears.
Add embeds right into the body of your story, between paragraphs or other media, directly from the block palette. Photos, videos, rich embeds, and simple embeds can all be added here, and each one has the ability to be displayed as a card or live content.
Live embeds will also typically have the option to be displayed at small, medium, or large widths. The only exceptions to this are rich embeds like Tweets, where the builder has already determined the most ideal size based on the content being embedded.
In a sidecar’s narrative panel
One of the immersive blocks in ArcGIS StoryMaps, sidecar has a long scrolling narrative panel that can include a variety of content. Open up the block palette and, sure enough, the embed block is right there waiting for you.
In the narrative panel, photos, videos, and rich embeds will appear as live content for desktop viewers (though you can change it to a card if you wish). Given the space constraints and limited information, simple embeds will always display as cards to ensure a smooth reading experience.
In a sidecar’s media panel
As part of the October 2019 release, sidecar’s media panel was enhanced to also include embedded content capabilities. Photo, video, and simple embeds are right at home here. Rich embeds are too, with a few exceptions. Tweets, for example, are a no-go for sidecar’s media panel (but they look great in the narrative panel).
How embedded content appears for mobile readers
While the scenarios above describe the embed appearance rules for desktop readers, things change a little on small screens. When it comes down to it, there’s just not enough space to elegantly present complicated interactives, so StoryMaps gives you some options, and makes some decisions behind the scenes, to optimize your audience’s experience. Here’s a little table to break down how each type of embed appears in each context on a mobile device:
For rich or simple content that you’ve added to inline in your story, you can choose whether you’d like it to display as a card or an alternative image on small screens. To configure these settings, open up the properties panel for your embed, and adjust the card details as needed or upload an image. You can see how this will look for mobile readers by using the tablet and phone views in the story preview (access this in the story header).
A few tips to keep in mind
Now that you’ve got a sense of the fundamental workings of embedded content in story maps, let me leave you with some practical suggestions and insider tricks.
Link vs. iframe code
As I mentioned a while back, each way of adding embedded content comes with its own perks. The advantages of links are, of course, their ease of use, but also that they give the story builder the chance to detect those special optimization details that set rich embeds apart from simple embeds.
Iframes, meanwhile, give you a bit more flexibility in terms of display details. With iframes, you can add in URL parameters to adjust the look of your live content. A good example of this is using parameters to set a video to autoplay or loop.
You can also use iframe code to specify the width, height, or aspect ratio of your live content. If, for example, you’re embedding a survey into your story and want all fields visible at once, you could set the width to be 100 percent of the iframe container, and then set the height in pixels to ensure the whole form appears inline in your story.
Use caution with embedded photos
You certainly have the option of linking to photos already hosted online, and sometimes that’s the only choice available. But ask anyone on the StoryMaps team, and we’ll tell you that, given the option, uploading your photos directly to your story is the recommended approach. The story builder has a few tricks up its digital sleeve to ensure that uploaded images are optimized for the size at which they appear in your story, but it can’t do this for linked images. That can mean longer load times for readers on mobile devices or slow internet connections.
Another risk, depending on your photo source, is the chance of a server crash or some other technical difficulty that renders your linked photos inaccessible. While popular third-party vendors like Flickr are generally reliable, that might not be the case for a small server with just a few images on it.
Don’t forget alternative text
When embedding content, be sure to open up the properties panel and add in a nice description in the alternative text field. This text is used by screen readers to help those with visual disabilities enjoy the full experience your content has to offer, making it an essential step in creating inclusive content. (Embed cards don’t require alternative text, since they already have a title and description attached to them.)
Put the reader first
Finally, and most importantly, stay focused on your target audience. If you’re not sure about where to put an embed, or which appearance option is most appropriate, start by asking yourself “how essential is this for my reader, and what’s the most ideal way for them to engage with this content?” The answer to those questions will help you chart a clear path forward.
As promised, here’s a helpful cheat sheet should you need a quick reference or a refresher on everything we covered here. And if you have any reactions or ideas on how to take the embed experience even further, be sure to share them with us through our product feedback form. Now, go ahead and start putting all this new knowledge to use—happy embedding!
Note: The embed block is only available to those with subscription accounts for ArcGIS. If you don’t have a subscription account, but would like to give embeds a try, you can always sign up for a free 21-day trial of ArcGIS.