Embed a tour

Put a tour on your own pages inline or behind a button, wire it to your own buttons, and listen to its events in your analytics.

The pages your buyers already visit are the best place for a tour: a product page, a pricing page, a help article. Embedding puts the tour right there, so a visitor can try the product without leaving your site, and every play still counts in ShowPilot's tour insights. Embeds always serve the published version, so you can keep editing without breaking the page.

You're in the right place when you want a tour on a web page you control, or when a developer needs the embed options, the player events or the control API.

What do you need before you embed?

A published tour. Until it's published, the share window is dimmed. See Publish and revisions.
Access to the page's HTML. You paste a short snippet where the tour should appear. Most site builders have an HTML or embed block for this.

Where do you get the embed code?

Select Share on the tour's card on the Tours tab and open the Embed tab. Choose Inline or Launch button, then select Copy code.

The builder has the same code: open the tour, select Settings, and copy the snippet from the Embed card. Before the tour is published, that snippet points at your private preview, so wait until you've published before you paste it anywhere public.

A hub can be embedded too. Select Share in the hub's header; the Embed tab offers the inline code only.

Which embed should you use?

Inline plays the tour right on the page, in a frame that fills the width of wherever you paste it, at a 16:9 shape. Viewers can go fullscreen from the bar that appears when they hover the tour.

For a self-guided tour, the code is a frame of the tour link with ?embed=1 on the end, which drops the page around the tour:

<iframe
  src="https://share.showpilot.com/t/YOUR-TOUR-ID?embed=1"
  style="width:100%;aspect-ratio:16/9;border:0;border-radius:12px"
  allow="autoplay; clipboard-write; fullscreen"
  allowfullscreen
  loading="lazy"
  title="Your tour name"
></iframe>

For an agent-led tour, the code frames the plain tour link instead, so your agent and the tour run together inside the frame. It adds microphone permission, which lets a viewer who selects Join the tour start a live call from inside your page:

<iframe
  src="https://share.showpilot.com/t/YOUR-TOUR-ID"
  style="width:100%;aspect-ratio:16/9;border:0;border-radius:12px"
  allow="microphone; autoplay; clipboard-write; fullscreen"
  allowfullscreen
  loading="lazy"
  title="Your tour name"
></iframe>

The share window picks the right version from the tour's Delivery setting. If you change the tour between self-guided and agent-led, copy the code again. See Agent-led tours.

How do you embed a tour on your page?

Publish the tour

In the builder, select Publish, or Update if it's already live.

Copy the code

Select Share on the tour's card, open Embed, choose Inline or Launch button, and select Copy code.

Paste it into your page

Paste the code into your page's HTML where the tour or button should appear, then publish your page.

Check it plays

Open your page in a private browser window and play the tour.

What embed options can you set?

The launch button snippet is one of several ways to use the ShowPilot script. Your developer can set these attributes on the element that holds the tour:

Attribute	What it does
`data-showpilot-tour`	Required. The tour's ID, the last part of its share link.
`data-showpilot-tour-mode`	`launcher` makes the element a button that opens the tour in a lightbox. `embed` plays the tour inside the element. Leave it out for `embed`.
`data-showpilot-tour-label`	The button text in `launcher` mode, used when the element has no text of its own.
`data-showpilot-tour-trigger`	A CSS selector, such as `.take-tour`. In `launcher` mode, every matching element on the page opens the tour, and the element with the attributes stays invisible. Use it to open the tour from your own buttons.
`data-showpilot-tour-autoplay`	Set to `true` to load the tour into an `embed` element as soon as the page loads. Without it, an `embed` element waits until your code opens it.
`data-showpilot-tour-source`	Which place the plays are credited to in tour insights: `embed`, `lightbox`, `share`, `chat` or `preview`. Leave it out and ShowPilot picks from the mode.
`data-showpilot-api`	The ShowPilot address the tour loads from. Leave it out; the script already knows it.

For example, to open a tour from two buttons you already have:

<script src="https://cdn.showpilot.com/widget/v1/app.js" async></script>
<div
  data-showpilot-tour="YOUR-TOUR-ID"
  data-showpilot-tour-mode="launcher"
  data-showpilot-tour-trigger=".take-tour"
></div>

<button class="take-tour">See it in action</button>
<a class="take-tour" href="#">Try the product</a>

Or to play a tour inside your page as soon as it loads:

<script src="https://cdn.showpilot.com/widget/v1/app.js" async></script>
<div
  data-showpilot-tour="YOUR-TOUR-ID"
  data-showpilot-tour-mode="embed"
  data-showpilot-tour-autoplay="true"
  style="width:100%;max-width:960px"
></div>

An embed element with no height of its own takes the tour's shape automatically.

How do you open an embedded tour from your own code?

On a page with an embed element, the script adds a small JavaScript API:

// Load the tour into its embed element
window.__showpilotTour.open('YOUR-TOUR-ID');

// Clear it again
window.__showpilotTour.close();

open only works for the tour ID on that element. With several embed elements on one page, the API belongs to the first one.

What controls do viewers get?

Control	What it does
Screen pill	Shows the screen number, such as 3/8, with previous and next arrows. On video screens it adds play and pause.
Arrow keys	Left and right move between screens. In an inline embed they work while the pointer or focus is on the tour, so your page keeps its own keys.
Narration button	Plays or pauses the voiceover on steps that have one, with a ring showing progress. See Step settings.
Play tour	Appears once, over the first frame, when a tour that advances on its own has narration and the browser will not start sound without a click. One click starts the tour with sound. Tours the viewer steps through by hand, and silent tours, never show it.
Fullscreen	In inline embeds, a button in the bar that appears on hover.
Close	In the lightbox only. Esc does the same.

How do you track tour events in your analytics?

The player reports what viewers do, so your own analytics can count plays, completions and clicks.

Event	When it fires	Details it carries
`played`	The tour starts.	`stepCount`
`step`	The viewer reaches a step.	`stepIndex`, `screen`, `totalScreens`, `screenId`
`completed`	The viewer reaches the end, or a step marked Completion step.	None
`cta`	The viewer selects a button or link that opens a web page.	`url`
`closed`	The player is closed through the control API.	None

Every event also carries publicId (the tour's ID) and viewSessionId (one viewing).

From an inline embed

The frame sends each event to your page as a message. Listen for it like this:

window.addEventListener('message', (e) => {
  const m = e.data;
  if (!m || m.source !== 'showpilot' || m.type !== 'sp:tour:event') return;
  // m.event is 'played', 'step', 'completed', 'cta' or 'closed'
  console.log(m.event, m.publicId, m);
});

From a launch button or an embed element on your page

The player runs in your page, so each event is pushed to your page's dataLayer as showpilot_tour_played, showpilot_tour_step, showpilot_tour_completed, showpilot_tour_cta and showpilot_tour_closed, with the details under showpilot. In Google Tag Manager, add a Custom Event trigger for the event name you want. See Track ShowPilot conversions in Google Tag Manager.

On ShowPilot's hosted tour page, the same events go to your container if you've turned on Tag Manager for hosted pages. See Run Tag Manager on hosted pages.

Can your page drive the tour?

Yes. Your page can move the tour, for example from your own next and back buttons.

Inline embeds take commands as messages to the frame:

const frame = document.querySelector('iframe[src*="/t/"]');
frame.contentWindow.postMessage(
  { source: 'showpilot', type: 'sp:tour:command', command: 'next' },
  '*',
);

Launch buttons and embed elements on your page expose the same commands on window.__spTourControl while a tour is open, for example window.__spTourControl.next().

Command	What it does
`next` / `back`	Moves one step forward or back.
`nextScreen` / `backScreen`	Moves to the first step of the next or previous screen.
`goTo`	Jumps to a step. Pass the step number, counting from 0, as `arg`.
`seekTo`	On a video screen, jumps to the step that covers a moment. Pass the seconds as `arg`.
`playPause`	At a step, moves on. On a video screen, plays or pauses the video.
`close`	Closes the lightbox and sends a `closed` event. It does nothing to an inline tour.
`getState`	On `window.__spTourControl` only. Returns the tour's ID, the current step, the step count, and whether it's waiting at a step.

A hub embed also accepts checklist:open and checklist:close as commands, to open or close its checklist panel. See Checklists.

Test it

Your embed is working when:

You open your page in a private browser window and the tour plays, or the button opens it in a lightbox.
The arrow keys move the tour while your pointer is over it.
A test play appears in Tours → Insights under the embedded or lightbox source.
If you listen for events, your console or Tag Manager preview shows played when the tour starts.

Troubleshooting

Issue	What to check
The frame shows a not-found page	The tour isn't published, or its Serving is off.
The tour loads for you but not for visitors	You copied the builder's snippet before publishing, and it points at your private preview. Copy it again after publishing.
The button doesn't appear	Check the script line is on the page, and your site doesn't block scripts from other domains.
An `embed` element stays empty	Add `data-showpilot-tour-autoplay="true"`, or call `window.__showpilotTour.open` with the tour's ID.
The frame is tiny or cut off	The frame fills the width of its container. Give the container a width, and don't set a fixed height on the frame.
Viewers can't talk to the agent in an agent-led embed	Check the frame's `allow` list still includes `microphone`. Some site builders strip it.
The embed plays self-guided although the tour is agent-led	You copied the code before changing Delivery, or you used Launch button. Copy the Inline code again.
No events reach my page	Frames send messages, not `dataLayer` pushes. Listen with `message` as shown above.

FAQ

Do I need to update the embed when I edit the tour?

No. Embeds serve the published version. Publish your edits with Update and the embed shows them within a minute.

Can I embed a hub?

Yes. Select Share in the hub's header and copy the code from Embed. Hubs embed inline, with their checklist and tour chooser inside the frame. A hub link with ?embed=1 on the end always plays self-guided, the same as a tour link; the agent-led embed is the bare hub link.