Embedding

Overview

Running Reality provides a wide range of options to share historical maps with your visitors and audience. The simplest approach is to share a map URL, but you can also configure how that URL will make the map look to tailor it to the specific needs you have. Deeper embedding options are also possible if your platform makes it possible. Using story map-style Running Reality projects can provide more structured narrative and in-map options like custom layers. Finally, if you use the app you can export standalone products like highly tailored HTML, images, or movies.

As always, when using the work of others, we ask that embedded content be provided with proper citation back to Running Reality so that Running Reality can provide the citation details for the data that went into the historical map you are using. See our data use policy for more details.

Integrations

Running Reality has tested integrations with common platforms to smooth the process for you. These are the primary tested platforms:

Platform	Method	Instructions
Esri StoryMap	Embed any map URL as a StoryMap "embed" block.	Instructions
Wordpress	Embed any map URL in a "link" block.	Instructions
Jupyter	Add a historical map to a Jupyter Notebook as a static map or connected to notebook variables as an interactive map.	Instructions
Blackboard	Add the student-access URL (which includes an access key if sharing a Lesson Plan) to your Blackboard class resources page.	Instructions
Google Classroom	Add the student-access URL (which includes an access key if sharing a Lesson Plan)to the class materials using "Classwork" tab -> "Create" button -> "Material" menu item.	Instructions
Schoology	Add the student-access URL (which includes an access key if sharing a Lesson Plan) as a Schoology "link", by copy-pasting any Running Reality URL or iFrame.	Instructions

Running Reality also provides the metadata needed by social media platforms to enable map sharing:

Platform	Method
Facebook	Share from the social media links or copy-paste any Running Reality URL.
Threads	Share from the social media links or copy-paste any Running Reality URL.
Instagram	Share a map image from the social media links or copy-paste any Running Reality URL.
YouTube	Share from the social media links or copy-paste any Running Reality URL.
Twitter	Share from the social media links or copy-paste any Running Reality URL.
Pinterest	Share from a copy-paste of any Running Reality URL.

Parameters

If you want to hide certain parts of the interface, you can add parameters to the Running Reality URL. These can be helpful to remove distractions when creating a map specific for your embedding needs and audience.

This is an example of how to use these parameters to construct your own specific URL:

• https://www.runningreality.org/?student&notimeline&nobox&nolabels#07/08/1585&36.30364,-78.47428&zoom=7

And this is an example for embedding in an HTML iFrame:

• <iframe src="https://www.runningreality.org/?lesson=1&key=FREEACCESS" width="100%" height="300" referrerpolicy="origin" style="border:none;">Running Reality</iframe>

The full set of parameters are:

Note that parameters that are part of the URL query string (starting with a ? and separated by & characters) affect the user interface where parameters that are part of the URL hash (starting with a # and separated by commas) affect the display position in space and time. Sometime social media or sharing platforms could ignore or truncate the hash values.

OEmbed

Many websites, blogging platforms, social media, and "story map" sites where you may be creating content use the Open Embedding (OEmbed) standard to determine how best to show an embedded version of a linked website like Running Reality. Running Reality includes OEmbed metadata in all map pages so that you can simply paste any Running Realty map URL into the platform and it will handle the embedding details for you. Sites that use OEmbed include Esri StoryMaps and Wordpress blogs.

The technical details are that Running Reality maintains an OEmbed "endpoint" at https://www.runningreality.org/data/oembed that will provide embedding details in the JSON format. The details will include an HTML snippet that proposes using an iFrame tag wrapping the Running Reality URL. The URL will honor all configuration parameters listed above so that you can embed a map with no sidebar or timeline if you like.

Standalone HTML

From the world menu of the app version of Running Reality, there is an option to export a world to a standalone HTML page. There are many configuration options to include your raw layer data within that HTML page, including any GeoJSON layers or CSV, XLS, or SQL tabular data. This produces an HTML page that you can then host from your own web server, such as a university server. The HTML includes documentation on how you can directly modify the HTML to add or remove layers or change styles. The HTML gives you direct Javascript access to the instance of OpenLayers that Running Reality uses for rendering so that you can directly control OpenLayers with your own custom Javascript. This gives you maximum flexibility to host a map of your own.

Standalone Images and Movies

From the share menu of the app version of Running Reality, you can embed an image or movie into your own work. You can copy-paste an image of the map directly to your computer's clipboard. You can create a JPEG image of a point in time or create an MP4 movie or GIF animation of a span of time.

Note that the web map uses a Mercator projection but the app uses an equi-rectangular projection. In most cases, you might not notice a difference, but at street level, Mercator keeps right angles looking correct and equi-rectangular can show some distortion. Eventually, we will migrate the app to Mercator.

Sharing Highlights, Lessons, and Research

Running Reality has special projects that add onto the regular historical map and these also have additional sharing and embedding capabilities. These special projects -- highlights, lesson plans, and research projects -- can include extra features for the sidebar or in-map layers and markers. Highlights are platform-wide areas where Running Reality has particularly detailed historical data to highlight for visitors. Lesson Plans are a premium feature to allow teachers to step classroom students through a guided history lesson. Research Projects are a premium feature for research professionals to share data products including in-map layers.

When sharing or embedding one of these projects, including the URL parameter will enable those special features. Extra metadata is provided within the page HTML header to the embedding website such as the project title, author, text description, and thumbnail image. Social media sites and OEmbed sites pick up this data to produce their sharing "cards," previews, or thumbnails.

From the projects page you can access a range of sharing and embedding links if you have either read-only or edit access to the project. These sharing links simplify the process of sharing. You can also generate QR Codes for the project from here. However, you can also share the main URL for a project just by viewing the project, such as this highlight https://www.runningreality.org/?highlight=34