JavaScript API reference

Once the StepsKit script has loaded, it exposes a global window.stepskit object. All methods are safe to call after the script tag fires its load event, and the global is undefined before that — use optional chaining (window.stepskit?.method(...)) to be safe.

User attributes

setUserAttributes

setUserAttributes(
  attrs: Record<string, string | number | boolean>,
  options?: { autoRefresh?: boolean },
): Promise<void>

Merges attrs into the visitor's known attributes. Passing autoRefresh: true re-fetches tours and re-evaluates visibility against the new attributes — call this after login or any change that affects targeting.

await window.stepskit?.setUserAttributes(
  { id: "user_123", plan: "enterprise" },
  { autoRefresh: true },
);

getUserAttributes

getUserAttributes(): Record<string, string | number | boolean> | undefined

Returns the current attributes, or undefined if none have been set.

Tour control

playTour

playTour(tourId: string): Promise<void>

Starts the named tour immediately, regardless of targeting rules. Useful for "Take a tour" buttons.

stopTour

stopTour(): void

Stops the currently playing tour. Counts as a dismissal for frequency capping.

isPlaying

isPlaying(): boolean

Returns true if a tour is currently on screen.

getTours

getTours(): Array<{ id: string; name: string }>

Returns the list of tours currently loaded for this visitor (i.e., the tours that passed targeting and frequency rules at the last fetch).

Re-evaluation

refresh

refresh(): Promise<void>

Re-fetches tours from the StepsKit API with the current user attributes and re-evaluates which one (if any) should play now. Call this after client-side route changes if your app navigates without full page reloads and you want tours to react to the new page.

setUserAttributes(..., { autoRefresh: true }) calls refresh for you; you only need refresh() directly when attributes haven't changed but context has.

Events

on / off

on(event: string, handler: (...args: unknown[]) => void): void
off(event: string, handler: (...args: unknown[]) => void): void

Subscribe and unsubscribe to embed events. Available events include:

• announcement_clicked — fired when a banner CTA is clicked.

window.stepskit?.on("announcement_clicked", (payload) => {
  console.log("announcement clicked", payload);
});

Announcements

dismissAnnouncement

dismissAnnouncement(announcementId: string): void

Programmatically dismiss a banner — equivalent to the user clicking the close button.

Teardown

destroy

destroy(): void

Tears down all StepsKit UI (active tours and announcements) and detaches listeners. Useful in single-page apps when the user signs out and you want to fully reset the embed.

TypeScript

The @stepskit/embed package ships types at dist/types/index.d.ts. For most projects you'll only need an ambient declaration for the global:

type StepsKitAttributes = Record<string, string | number | boolean>;

interface Window {
  stepskit?: {
    setUserAttributes(
      attrs: StepsKitAttributes,
      options?: { autoRefresh?: boolean },
    ): Promise<void>;
    getUserAttributes(): StepsKitAttributes | undefined;
    playTour(tourId: string): Promise<void>;
    stopTour(): void;
    isPlaying(): boolean;
    getTours(): Array<{ id: string; name: string }>;
    refresh(): Promise<void>;
    on(event: string, handler: (...args: unknown[]) => void): void;
    off(event: string, handler: (...args: unknown[]) => void): void;
    dismissAnnouncement(id: string): void;
    destroy(): void;
  };
}