Advice and answers from the Roadmap Team

How to Embed a Public Roadmap to your Website or App

Embedding a public roadmap makes your roadmap more accessible, branded, and engaging. There are two ways to embed a public roadmap:

  1. On a marketing site such as WordPress and/or
  2. Directly to an app (recommended)

A public roadmap can be embedded in multiple locations, though we recommend at least embedding it in your web app. When a roadmap is embedded in your app, it’s easier for users and customers to engage with what you’re working on. You can also see interesting data from your app such as the monthly recurring revenue (MRR) associated with users following stories or submitting feedback.

If you don’t share a public roadmap with customers, some users have embedded their roadmaps to internal applications to make them more accessible to colleagues throughout the organization.

How to Embed a Public Roadmap

Just like the feedback widget, you are using our CDN (content delivery network) ensuring your users load the content from the nearest Amazon data center possible. This makes the latency minimal and creates the best experience for your users.

Make sure you embed the code before the </body> tag.

For non-single page app page:

<script type="text/javascript"
  src="https://cdn.roadmap.space/widget/roadmap.js?v=1.1"
  id="public-roadmap"
  data-id="rdmp-id-here"
  data-story="optional-display-story"
  data-embedded="true"
  data-container="div-container-here"
  data-email="user email"
  data-first="user first name"
  data-last="user last name"
  data-company="user company"
  data-revenue="user revenue"
>
</script>

For a single page app:

var b = document.body;
var s = document.createElement("script");
s.id = "public-roadmap";
s.src = "https://cdn.roadmap.space/widget/roadmap.js?v=1.1";
s.type = "text/javascript";
s.dataset["id"] = "rdmp-id-here";
s.dataset["embedded"] = "true";
s.dataset["container"] = "div-container-here";
s.dataset["email"] = “user email”;
s.dataset["first"] =”user first name”;
s.dataset["last"] = “user last name”;

b.appendChild(s);

For single page and non-single page applications, you must first prepare an HTML div container to host the public roadmap:

<div id=”div-container-here”></div>

You can name this however you want, it just needs to match with the embedded “container” parameter. The public roadmap will be injected in this container, so make sure the width and height are reasonable for your public roadmap.

Required parameters for the public roadmap:

Find your roadmap id in the Widget settings tab here: https://app.roadmap.space/#/roadmap/widget and replace “rdmp-id-here” with your roadmap id.

Optional parameters:

User parameters are optional. If you supply them your users will be able to follow stories without entering their contact information. If you are using the embedded roadmap in an app where users are signed in, we recommend adding these parameters. If you are using Roadmap on your website, be sure to remove these parameters.

The “story” parameter lets you load your public roadmap directly to this story. The value for this story can be found on our URL when you click on a story from your internal story. The URL looks like this: #/story/edit/p-id|token.

Take the id from the id|token portion of the URL and this is what you would send to load that story. Your users will still be able to go back to the normal public roadmap from there.

User Parameters

Passing User Data:

Fill in the entire parameters for the best experience when users engage with your public roadmap. If you’re using a server-side programming language to render your pages like Go, Python, Ruby, JavaScript (Node), PHP, C# / VB.NET, etc you could use your own view engine and inject those values when rendering the pages.

<script type="text/javascript"
 src="https://cdn.roadmap.space/widget/roadmap.js?v=1.1"
 id="public-roadmap"
 data-id="rdmp-id-here"
 data-embedded="true"
 data-container="div-container-here"
 data-email="{{ currentUser.email }}"
 data-first="{{ currentUser.first }}"
 data-last="{{ currentUser.last }}"
 data-company="{{ currentUser.company }}"
 data-revenue="{{ currentUser.subscription.amount }}"
>
</script>

Below are the user parameters and their definitions

data-id: Required, this is the id of your roadmap. If you manage multiple product and roadmaps you are able to share each of them separately. It is up to you to decide which pages of your app load your roadmap.

data-email: Optional this is the email of your user. You’ll know who is clapping and when a user follows a story they become a subscriber.

data-first and data-last: : Optional, these are the first and names of your users. We recommend including these attributes so that you can personalize your updates to subscribers using our merge tokens.

data-company: Optional, this is the company name or account name your users is associated with. If you’re a b2b product, we reccomend adding this parameter to see feedback across accounts.

data-revenue: Optional, this is the monthly recurring revenue for each user. This is useful if you want to see the total MRR for all your ideas and the Roadmap items so that you can prioritize product roadmap decisions based on your business objectives.

Feedback

We’re thinking of adding more flexibility to this small API, such as the ability to manually load the roadmap at a moment you choose. Events you could register and perform actions with such as “onClap”, “onFollow” and “onStoryClicked” could be tracked in an analytics framework such as Segment.

If these ideas sound interesting or you have some thoughts on how to make embedded roadmaps better, we’d love to hear from you!

Check out our API to learn about more ways to customize your public roadmaps.