Playing Back Walkthroughs with the Bookmarklet

The playback bookmarklet replays a recorded walkthrough as an overlay on the current page. It works on any browser with a bookmarks bar.

FoxChat has two ways to play a walkthrough. The first is the embedded player at app.getfoxchat.com/embed/<walkthrough_id> — that's the full-fidelity player with background music, lead-modal end screen, and the FoxChat-controlled chrome. The second is the playback bookmarklet, which loads playback.js into the page you're already viewing and renders the same step overlays in a Shadow DOM root. This guide is about the bookmarklet path.

When to use the playback bookmarklet

The bookmarklet is the right tool when:

• You want to preview your own walkthrough on the live site exactly as a visitor would see it, without going through the embed player chrome.
• You want to hand-test selector resilience after the host site changed — click the bookmarklet, watch the runtime fall through the seven-identifier hierarchy, see what still matches.
• You want to show a walkthrough to a colleague on a page they're already looking at, without making them navigate to the embed URL.

For visitor-facing playback — the URL you share publicly — use the embed player. The bookmarklet is an internal/preview tool.

Step 1: Get the walkthrough ID

Every walkthrough has a UUID. You can find yours in two places:

• The walkthroughs dashboard at /walkthroughs — each row has a copy-id button.
• The share URL itself — app.getfoxchat.com/embed/<walkthrough_id> — the part after /embed/ is the ID.

The dashboard also offers a one-click "copy personalized playback bookmarklet" button. That bookmarklet has the ID pre-filled. Drag it to your bookmarks bar, click it on any page, and that specific walkthrough plays.

Step 2: Click the bookmarklet on the target page

Navigate to the page where you want the walkthrough to play (typically the page where it was originally recorded). Click the playback bookmarklet on your bookmarks bar. The runtime fetches the walkthrough definition from the FoxChat API, builds a Shadow DOM root, and starts at step 1.

Step 3: Use the playback controls

You will see a small controls bar at the bottom of the page with these buttons (every one has a tooltip):

• Prev — back one step.
• Next — forward one step.
• Replay — re-trigger the current step's highlight animation. Useful if you missed a transition.
• Restart — jump back to step 1.
• Close (Esc) — dismiss the playback overlay. Pressing Esc on your keyboard does the same thing.

For each step, the runtime locates the captured element using its seven-identifier fallback chain, draws the cyan numbered badge, draws the connector line, displays the description text, and pulses the highlight ring. If a step's element cannot be found at all (the host site removed or restructured it), the runtime shows a small "step element not found" toast and offers to skip to the next step.

What the bookmarklet does NOT include

Compared to the embedded player at app.getfoxchat.com/embed/<id>, the bookmarklet player is intentionally lean. It does not include:

• Background music — the embed player can pipe a music track. The bookmarklet plays narration audio (if recorded) but no music bed.
• Lead-modal end screen — the embed player can show a lead-capture form on the final step. The bookmarklet just closes when you reach the end.
• Branded chrome — the embed player has the FoxChat-controlled wrapper. The bookmarklet renders only the overlay on top of whatever you're already looking at.

If you need any of those, share the embed URL instead.

How playback resilience works under the hood

The runtime tries each of the seven captured identifiers in priority order until one matches an element on the current page. The order is:

1. data attribute — if your team uses data-testid or data-cy, those are usually the most stable selectors and the runtime tries them first.
2. ARIA label + role — combinations like button with aria-label "Submit order" rarely change even when class names do.
3. CSS selector — the recorder captures the most specific stable selector at recording time. Often this still works, but it's fragile to class-name renames.
4. Text content — matching by visible text inside the element is resilient when the visible copy stays stable across redesigns.
5. XPath — the full DOM path. Brittle but useful when nothing else matched.
6. Surrounding text — the runtime can locate elements relative to nearby text anchors ("the button just below the heading 'Account'").
7. Position hint — last resort: nth-child within a known container.

This fallback is what makes walkthroughs replay correctly across redesigns. If the runtime cannot find the element with any of the seven, it shows the "step element not found" toast and offers to skip.

Browser support

Same support matrix as the recorder bookmarklet: Chrome, Edge, Brave, Firefox, Safari, Vivaldi, Opera. Same caveats apply: the bookmarklet's loaded playback.js can be blocked by host-site Content-Security-Policy that disallows third-party script tags. When that happens you see a red toast in the corner and the runtime aborts. See troubleshooting for workarounds.