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

Call howdygo.control(demoId) to get a controller object for a specific demo.

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

If you only have one demo on the page, you can call control() without an ID and the SDK resolves it for you.

howdygo.control().next();

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);