Geyed SDK

Framework-agnostic product tour runtime for rendering published tours from the Geyed backend.

Purpose

• Runtime viewer only: fetch and render tours inside a host web app.
• No authoring/editor logic in this package.
• Small public API: init, start, startTour, stop, destroy, on, off, registerTours.

Install

npm install @geyed/sdk

Or load via CDN (IIFE bundle exposes the global Geyed):

<script src="https://unpkg.com/@geyed/sdk/dist/index.iife.js"></script>

Build

npm install
npm run build

Build outputs (in dist/):

• index.cjs — CommonJS
• index.mjs — ESM
• index.iife.js — minified browser bundle, exposes window.Geyed
• index.d.ts — TypeScript declarations
• *.map — source maps for all formats

Usage

ESM

import { init, start, on } from "@geyed/sdk";

init({
  apiKey: "gyd_your_app_key",
  baseUrl: "https://api.geyed.com",
  debug: true,
});

on("tour_started", (e) => console.log("Tour started:", e.tourName));

await start();

IIFE / CDN

<script src="https://unpkg.com/@geyed/sdk/dist/index.iife.js"></script>
<script>
  Geyed.init({
    apiKey: "gyd_your_app_key",
    baseUrl: "https://api.geyed.com",
    debug: true,
  });

  Geyed.start();
</script>

API Reference

init(config: GeyedConfig): void

Sets SDK configuration. Must be called before start().

| Field | Type | Description | |---|---|---| | apiKey | string | Your Geyed app key (required for backend fetch). | | baseUrl | string | Base URL of the Geyed backend (e.g. https://api.geyed.com). | | environment | string? | Optional environment tag forwarded with fetch. | | userId | string? | Optional end-user identifier for analytics and targeting. | | debug | boolean? | Logs SDK activity to the console when true. | | tours | SdkTour[]? | Preload tours inline instead of fetching from the backend. | | onError | (err: GeyedErrorEvent) => void? | Callback for error events from API fetch or tour loading. |

start(): Promise<void>

Fetches published tours (or uses preloaded/registered tours) and starts the first tour whose urlPattern matches the current window.location.pathname.

startTour(tourId: number): Promise<void>

Starts a specific tour by ID, bypassing URL matching.

stop(): void

Stops the active tour and removes overlays and tooltips.

destroy(): void

Full cleanup: stops any active tour and removes injected styles.

registerTours(tours: SdkTour[]): void

Registers tours locally without a backend fetch. Useful for offline demos or self-hosted tour definitions.

on(event, callback) / off(event, callback)

Subscribe to lifecycle events.

| Event | Payload | |---|---| | tour_started | { tourId, tourName } | | tour_completed | { tourId, tourName } | | tour_dismissed | { tourId, tourName, stepIndex } | | step_viewed | { tourId, tourName, stepIndex, stepTitle } | | tour_error | { code, message, tourId? } | | tour_failed | { code, message, tourId? } |

Example:

import { on } from "@geyed/sdk";

on("step_viewed", ({ tourName, stepIndex, stepTitle }) => {
  myAnalytics.track("geyed_step_viewed", { tourName, stepIndex, stepTitle });
});

Runtime Behavior

• Fetches published tours from GET {baseUrl}/api/v1/sdk/tours.
• Uses current window.location.pathname for URL matching against each tour's urlPattern.
• Resolves selectors with retries before skipping a missing step.
• Renders overlay + tooltip with next, back, close controls.
• Emits analytics events through the event bus exposed via on/off.

Browser Support

| Browser | Minimum version | |---|---| | Chrome / Edge | 90 | | Firefox | 88 | | Safari | 15.4 |

Requires fetch, Promise, URLSearchParams, and modern DOM APIs. No IE support.

Troubleshooting

Uncaught ReferenceError: Geyed is not defined Make sure the IIFE bundle is loaded before your inline script, and that you are using the .iife.js file (not .mjs).

Tour never starts Enable debug: true in init() and check the console. Common causes: urlPattern does not match the current pathname, no published tour exists for your API key, or target selectors are not yet in the DOM when start() is called.

Target elements missing Tour steps skip when their targetSelector cannot be resolved after retries. Ensure the target is rendered before the step runs, or delay start() until your app has hydrated.

Current Limitations

• Runs the first matching tour only.
• URL matching supports wildcard patterns but is intentionally minimal.
• No built-in A/B testing or segmentation beyond userId passthrough.