GuideMark Documentation

Quick Start

Add GuideMark to your website in 30 seconds. Copy and paste this script tag into the <head> of every page where you want tours and checklists to appear.

html

<script
  src="https://naiuhnzdampxdewizhin.supabase.co/storage/v1/object/public/widgets/embed.js"
  data-project-id="YOUR_PROJECT_ID"
  async
></script>

Where do I find my Project ID? Go to your Dashboard → Settings → Project ID. It’s a UUID like a1b2c3d4-e5f6-...

Installation

Script Attributes

data-project-idstringRequiredYour project UUID from the dashboard.

data-auto-startbooleanAuto-trigger tours for matching pages. Defaults to true.

data-admin-panelbooleanShow the admin panel for recording/editing tours. Set to true only for admin users. Defaults to false.

Single Page Apps (React, Next.js, Vue)

GuideMark automatically detects SPA navigation (pushState, replaceState, popstate). No additional configuration needed. The widget re-evaluates tours and checklists on every route change.

Ready Check

The ProductTour global is available as soon as the embed script loads. If you need to wait for it:

javascript

// Wait for ProductTour to be available
function waitForProductTour(callback) {
  if (window.ProductTour) {
    callback(window.ProductTour);
  } else {
    const observer = new MutationObserver(() => {
      if (window.ProductTour) {
        observer.disconnect();
        callback(window.ProductTour);
      }
    });
    observer.observe(document, { childList: true, subtree: true });
  }
}

JavaScript API

The window.ProductTour object is your entry point for programmatic control.

ProductTour.complete(eventName)Custom Events

Marks a checklist item as complete when a custom event occurs in your app. The eventName must match the event name configured in the dashboard checklist item.

javascript

// User just uploaded their first file
ProductTour.complete('file_uploaded');

// User connected their payment method
ProductTour.complete('payment_connected');

// User invited a team member
ProductTour.complete('team_member_invited');

eventNamestringRequiredThe event identifier matching a checklist item's event name in the dashboard.

ProductTour.embedChecklist(selector, checklistId)Embedded

Renders a checklist directly inside a DOM element on your page, instead of the default floating FAB. Useful for embedding onboarding progress in a sidebar, settings page, or onboarding wizard.

javascript

// Embed in a sidebar panel
ProductTour.embedChecklist('#onboarding-sidebar', 'a1b2c3d4-...');

// Embed in a settings page container
ProductTour.embedChecklist('.settings-checklist', 'a1b2c3d4-...');

selectorstringRequiredCSS selector for the target container element.

checklistIdstringRequiredUUID of the checklist to render. Find it in Dashboard → Checklists.

ProductTour.projectIdRead-only

Returns the project ID the widget is configured for. Useful for debugging.

Checklists API

Completion Types

Each checklist item can be completed in different ways, configured in the dashboard:

Type	How it completes	Developer action
manual	User clicks the checkbox	None
tour	User completes a linked tour	None — select tour in dashboard
page_visit	User visits a specific URL	None — set URL in dashboard
custom_event	JS event fires	`ProductTour.complete('event_name')`
api	Server-side REST call	`POST /api/checklist/complete-item`

URL-Scoped Visibility

Set a URL Pattern on a checklist in the dashboard to restrict it to specific pages. Supports exact paths and * wildcards.

text

/settings          → Only shows on /settings
/onboarding/*      → Shows on /onboarding/step1, /onboarding/step2, etc.
(empty)            → Shows on all pages

REST API

Use the REST API to complete checklist items from your server. Useful for actions that happen server-side (account verification, payment processing, etc.)

Authentication

All API requests require a project API key passed in the Authorization header. Find your API key in Dashboard → Settings.

bash

Authorization: Bearer pt_a1b2c3d4e5f6...

POST/api/checklist/complete-item

Mark a checklist item as complete for a specific user.

Request Body

projectIdstringRequiredYour project UUID

checklistIdstringRequiredUUID of the checklist

itemIdstringRequiredUUID of the checklist item to complete

userIdstringRequiredYour user's unique identifier (e.g. database ID, email)

Example

bash

curl -X POST https://guidemark.co/api/checklist/complete-item \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "projectId": "a1b2c3d4-...",
    "checklistId": "e5f6a7b8-...",
    "itemId": "c9d0e1f2-...",
    "userId": "user-123"
  }'

Response

json

// Success (200)
{ "success": true }

// Error (400/401/403/500)
{ "error": "Missing required fields: projectId, checklistId, itemId, userId" }

Embedded Mode

Instead of the floating checklist button, render checklists directly inside your app's UI.

html

<!-- 1. Add a container where you want the checklist -->
<div id="onboarding-checklist"></div>

<!-- 2. Call embedChecklist after the embed script loads -->
<script>
  // Wait for the widget to load, then embed
  const checkObserver = setInterval(() => {
    if (window.ProductTour) {
      clearInterval(checkObserver);
      ProductTour.embedChecklist('#onboarding-checklist', 'YOUR_CHECKLIST_ID');
    }
  }, 100);
</script>

Note: The embedded checklist uses Shadow DOM for style isolation, so your app's CSS won't interfere with the checklist's appearance.

GuideMark — Developer Documentation

Questions? Reach us at support@guidemark.co