Player Control

The Player Control API lets you drive an embedded HowdyGo demo from your own page. Build custom Next and Previous buttons in your own UI, jump to a specific step or chapter, resume or pause auto-progress, and read the current player state.

Use it when you want playback to react to something on your page, like a scroll position or a tab change, instead of relying on the player’s built-in controls.

Getting a controller

Install the SDK, then call howdygo.control(demoId) after the SDK has initialized to get a controller for a specific demo. The initial loading snippet queues calls but cannot return a controller.

const demo = howdygo.control("your-demo-id");
demo.next();
demo.pauseAutoProgress();

An explicit demo ID lets the controller queue commands while that demo’s iframe is still loading. If exactly one demo has already registered, you can call control() without an ID and the SDK resolves it for you.

howdygo.control().next();

With no registered demo, or more than one, control() without an ID cannot choose a target. Pass the demo ID when your page has several demos or when registering one later.

Navigation

Move through steps and chapters.

const demo = howdygo.control("your-demo-id");
 
demo.next();
demo.goToStep(3); // 3rd step
demo.goToStep("step_abc123"); // by ID
demo.goToChapter(2); // 2nd chapter

Auto-progress

Toggle the auto-progress timer that advances the demo automatically. See Auto-Progress & Looping for the editor settings that control this.

demo.pauseAutoProgress(); // pause auto-progress on the current step
demo.resumeAutoProgress(); // resume auto-progress

Both methods only act on demos where the publisher has enabled auto-progress in the editor. To check before calling, read autoProgress from getState().

Reading state

Call getState() to read the player’s current state. It returns a Promise.

const state = await howdygo.control("your-demo-id").getState();
 
console.log(state.currentStepIndex); // e.g. 3
console.log(state.autoProgress); // 'disabled' | 'playing' | 'paused'
console.log(state.steps); // [{ id, index, title }, ...]

The resolved value:

{
  currentStepIndex: number; // 1-based
  steps: Array<{
    id: string;
    index: number; // 1-based
    title: string | null;
  }>;
  chapters: Array<{
    id: string;
    title: string;
    index: number; // 1-based
    stepIndex: number; // 1-based step where the chapter starts
  }>;
  autoProgress: "disabled" | "playing" | "paused";
}

autoProgress tells you whether the demo’s auto-progress timer is 'playing', 'paused' by the viewer or by your own pauseAutoProgress() call, or 'disabled' because the publisher hasn’t enabled auto-progress for the demo.

If the iframe has not registered yet, getState() waits for registration before sending the request. The default timeout is 5 seconds, after which the Promise rejects.

Examples

Custom next and previous buttons

<button id="prev">Previous</button>
<button id="next">Next</button>
 
<script>
  const demo = howdygo.control("your-demo-id");
  document.getElementById("prev").onclick = () => demo.previous();
  document.getElementById("next").onclick = () => demo.next();
</script>

Pause auto-progress when the demo scrolls out of view

This only does something when auto-progress is enabled on the demo. If it’s not, both calls are silent no-ops.

const demo = howdygo.control("your-demo-id");
const iframe = document.querySelector("iframe");
 
const observer = new IntersectionObserver(([entry]) => {
  if (entry.isIntersecting) {
    demo.resumeAutoProgress();
  } else {
    demo.pauseAutoProgress();
  }
});
 
observer.observe(iframe);