Documentation

GuideAI SDK Installation & Usage

Install the browser SDK (guideai.js), configure it with data-*attributes, and learn what's sent automatically vs. what you should send manually.

1) Install the SDK on your website

Add this to your HTML (usually near the end of <body>):

html

<script
  src="https://cdn.3guideai.com/sdk/guideai.js"
  data-site-id="YOUR_SITE_ID"
  data-token="YOUR_PUBLIC_TOKEN"
  data-api-url="https://api.3guideai.com"
  data-cdn-url="https://cdn.3guideai.com"
></script>

Notes

data-site-id and data-token are required. If either is missing, the SDK will not initialize.
data-api-url is strongly recommended. The SDK has a default, but you should set it explicitly.
data-cdn-url is the CDN base URL.

2) Public API (what you can call)

The SDK exposes a global window.guideai object (and a legacy alias window.__guideai) once loaded.

3) What the SDK sends automatically

When not in extensionMode, the SDK automatically emits:

Session + page basics

session_start (includes metadata like entry URL, referrer, device info, viewport, session number, etc.)
Initial page_view (with metadata.entry_page: true)
page_view on SPA navigations
page_exit with engagement + scroll metadata (time_on_page_ms, active_time_ms, idle_time_ms, max_scroll_depth_pct)

Interaction + friction

click, double_click, right_click
rage_click, dead_click
scroll
form_start, form_submit, form_abandon, form_error
js_error, network_error, ui_error

UTM + referrer capture

On the first load, if UTMs or referrer are present, the SDK emits an identify event with metadata.utm_* and metadata.referrer.

The SDK does not currently send a dedicated referrer_host; derive it from referrer server-side.
The SDK does notautomatically label clicks as “CTA clicks” unless your dashboard logic / click classifier marks them.

4) Configuration reference (script tag `data-*`)

Configuration is read from the <script> tag.

Required

Attribute	Type	Meaning
`data-site-id`	string	Your site/workspace ID
`data-token`	string	Public token (pk_live_...) used by the browser SDK

Endpoints

Attribute	Default	Notes
`data-api-url`	`https://api.3guideai.com`	Recommended: set to https://api.3guideai.com
`data-cdn-url`	`https://cdn.3guideai.com`	Base URL used for KB/assets (not /sdk/guideai.js)

Sessions + batching

Attribute	Default	Meaning
`data-idle-timeout`	`20000`	Idle threshold for engagement calculations (ms)
`data-session-timeout-ms`	`1800000`	Rotate session after inactivity (ms)
`data-batch-size`	`50`	Max events per batch
`data-batch-interval-ms`	`30000`	Flush interval (ms)

Privacy / enrichment

Attribute	Values	Default	Meaning
`data-geolocation`	`off \| granted-only \| prompt`	`off`	Optional browser geo enrichment

Guides + bubble

Attribute	Default	Meaning
`data-guides-enabled`	`true`	When false, guide playback is disabled
`data-auto-advance-on-target-click`	`true`	Auto-advance guides on target click (when applicable)
`data-bubble-enabled`	`true`	Show the bubble entry point
`data-bubble-position`	`bottom-right`	Bubble placement
`data-bubble-label`	`Help`	Bubble label
`data-bubble-icon`	`robot`	Mascot id (or use data-bubble-image)
`data-bubble-image`	empty	Custom image URL that overrides icon
`data-bubble-mode`	`drift`	Bubble motion mode
`data-widget-mode`	`guide`	How bubble behaves when support is enabled

Recording + feedback

Attribute	Default	Meaning
`data-recording`	`false`	Enables session recording
`data-feedback-auto-prompt`	`true`	Auto-prompt feedback
`data-feedback-prompt-delay-ms`	`30000`	Delay before prompting (ms)
`data-feedback-prompt-min-pageviews`	`2`	Minimum page views before prompting

Extension mode

Attribute	Default	Meaning
`data-extension-mode`	`false`	When true, disables analytics/tracking/support because the “visitor” is an extension user

Announcements

Attribute	Default	Meaning
`data-announcement-surface`	`modal`	Default surface when opening from beacon
`data-announcement-close-on-backdrop`	`true`	Close announcement when clicking backdrop

Attributes that are currently ignored

These script attributes are currently not read by parseConfig():

data-track-all
data-behavioral-triggers

5) How to update configuration

Update via dashboard (recommended)

Some settings are applied from the backend knowledge base load. Update settings in the dashboard, then reload the page (or re-initialize the SDK) to apply changes.

Update via script tag

Change <script data-*> attributes and redeploy your site. These are read during initialization.

Runtime updates

updateOptions() is for visitor/account identity metadata, not for changing widget configuration at runtime. To hot swap config:

call guideai.destroy()
remove the script tag (optional)
re-insert the script tag with updated data-*

6) Knowledge Base & Scanner (how GuideAI understands your UI)

GuideAI's knowledge base (KB) describes your app routes, interactive elements, and a hierarchical UI map used by AI for more accurate guidance.

Ways to get a KB into GuideAI

Run the scanner (recommended for most teams)
Upload a KB JSON directly from the dashboard Knowledge Base page

Privacy note: the scanner is designed to extract structure needed for guidance (routes/elements/UI map). It is not intended to collect secrets.

Scanner source (public): github.com/3gensolution/guideai-scanner

7) GuideAI Scanner — Installation & Usage Guide

GuideAI Scanner scans your web app, detects your framework, extracts routes and interactive elements, and builds a knowledge base for AI-powered guidance.

Installation

bash

npm i @guideai/scanner

Or globally:

bash

npm i -g @guideai/scanner

Quick Start

Command-Line Options

Option	Description	Default	Required
--dry-run	Output JSON without uploading	false	No
--dir	Project root directory	cwd	No
--output	Save scan result to JSON file	—	No
--api-url	GuideAI API endpoint	https://cdn.3guideai.com	No
--key	Site API key for uploads	—	Yes (unless --dry-run)

Common Usage Patterns

bash

# Preview scan:
npx guideai-scan --dry-run

# Save results to a file:
npx guideai-scan --dry-run --output scan-results.json

# Upload:
npx guideai-scan --key sk_live_your_api_key

# Scan a specific directory:
npx guideai-scan --dir /path/to/project --dry-run

# Scan, save, and upload:
npx guideai-scan --key sk_live_your_api_key --output scan-results.json

Knowledge Base Output Structure

json

{
  "framework": "nextjs-app-router",
  "routes": [],
  "elements": [],
  "ui_map": { "root": {} },
  "duration_ms": 1234
}

Upload KB JSON from the dashboard

If you already have a scan JSON (from CI, from a teammate, or from a dry-run output file), you can upload it from the dashboard Knowledge Base page.

8) Troubleshooting

Need help? Contact us from Privacy Policy or explore Pricing.

GuideAI SDK Installation & Usage

1) Install the SDK on your website

Notes

2) Public API (what you can call)

3) What the SDK sends automatically

Session + page basics

Interaction + friction

UTM + referrer capture

4) Configuration reference (script tag data-*)

Required

Endpoints

Sessions + batching

Privacy / enrichment

Guides + bubble

Recording + feedback

Extension mode

Announcements

Attributes that are currently ignored

5) How to update configuration

6) Knowledge Base & Scanner (how GuideAI understands your UI)

Ways to get a KB into GuideAI

7) GuideAI Scanner — Installation & Usage Guide

Installation

Quick Start

Command-Line Options

Common Usage Patterns

Knowledge Base Output Structure

Upload KB JSON from the dashboard

8) Troubleshooting

4) Configuration reference (script tag `data-*`)