EasyGuide SDK

Zero-dependency, lightweight guide playback engine for interactive product tours.

零依赖的轻量级引导播放引擎，用于创建交互式产品引导和新手教程。

Demo / 演示

Open demo/index.html in a browser to see all features in action:

packages/sdk/demo/index.html

Installation / 安装

npm install @ai-dap/sdk
# or
pnpm add @ai-dap/sdk
# or
yarn add @ai-dap/sdk

Quick Start / 快速开始

Offline Mode / 离线模式 (No server needed / 无需服务器)

import { DapSDK } from '@ai-dap/sdk';

const sdk = await DapSDK.init({
  guides: [
    {
      id: 'onboarding-tour',
      appId: 'my-app',
      name: 'Product Tour',
      description: 'A quick tour of the main features',
      status: 'published',
      version: 1,
      trigger: { type: 'manual' },
      theme: { primaryColor: '#6366f1' },
      steps: [
        {
          id: 'step-1',
          order: 1,
          title: 'Welcome!',
          content: 'Let me show you around.',
          target: { css: '#hero-element' },
          position: 'bottom',
          highlight: true,
          scrollToTarget: true,
        },
      ],
      createdAt: new Date().toISOString(),
      updatedAt: new Date().toISOString(),
    },
  ],
  debug: true,
});

// Start a guide
sdk.startGuide('onboarding-tour');

SaaS Mode / 云端模式 (Fetch guides from API / 从 API 获取引导)

const sdk = await DapSDK.init({
  sdkKey: 'dap_your_sdk_key',
  apiBaseUrl: 'https://api.easyguide.com',
});

// Guides are auto-fetched from the API
sdk.startGuide('guide-id');

Configuration / 配置参考

DapSDK.init(options) / 初始化选项

| Option | Type | Default | Description | |--------|------|---------|-------------| | sdkKey | string | - | Platform SDK key (SaaS mode / 云端模式密钥) | | apiBaseUrl | string | - | API base URL (SaaS mode / API 基础地址) | | guides | Guide[] | - | Inline guide configs (offline mode / 离线引导配置) | | visitorId | string | auto-generated | Custom visitor identifier (自定义访客 ID) | | autoStart | boolean | true | Auto-start guides after init (是否自动开始引导) | | locale | string | 'zh-CN' | Locale code for i18n (国际化语言代码) | | debug | boolean | false | Enable console logging (启用调试日志) |

Note: Use either sdkKey + apiBaseUrl (SaaS mode) or guides (offline mode). Both can be combined.

API Reference / API 参考

DapSDK — Main SDK Class / 主入口类

const sdk = await DapSDK.init(options: SdkConfig): Promise<DapSDK>

| Method | Description | |--------|-------------| | getState() | Get readonly SDK state (获取 SDK 只读状态) | | getPlayer() | Get the GuidePlayer instance (获取播放器实例) | | getAnalytics() | Get the AnalyticsCollector instance (获取分析器实例) | | startGuide(guideId) | Start a specific guide by ID (按 ID 启动引导) | | stopGuide() | Stop the currently playing guide (停止当前引导) | | setLocale(locale) | Change locale at runtime (运行时切换语言) | | destroy() | Clean up and remove SDK (销毁 SDK 实例) |

GuidePlayer — Step-by-step Playback / 逐步引导播放器

const player = sdk.getPlayer();

| Method | Description | |--------|-------------| | start(guide) | Start playing a guide (开始播放引导) | | next() | Go to next step (下一步) | | prev() | Go to previous step (上一步) | | showStep(index) | Jump to a specific step (跳转到指定步骤) | | complete() | Complete the guide (完成引导) | | dismiss() | Dismiss the guide (关闭引导) | | stop() | Stop programmatically (程序化停止) | | isActive() | Check if a guide is playing (是否正在播放) | | getState() | Get player state (获取播放器状态) | | refresh() | Re-render current step (刷新当前步骤) | | on(event, callback) | Subscribe to events (订阅事件) | | destroy() | Clean up (销毁) |

HelpWidget — Floating Help Button / 帮助浮动按钮

import { HelpWidget } from '@ai-dap/sdk';

const widget = new HelpWidget({
  guides: publishedGuides,
  onGuideStart: (guideId) => sdk.startGuide(guideId),
  theme: { primaryColor: '#6366f1' },
});

widget.mount();   // Add to DOM
widget.open();    // Open panel
widget.close();   // Close panel
widget.toggle();  // Toggle open/close
widget.unmount(); // Remove from DOM
widget.setGuides(newGuides); // Update available guides
widget.setPlaying(true);     // Update playing state
widget.isOpen();             // Check if panel is open

Tooltip — Guide Tooltip / 引导提示框

import { Tooltip } from '@ai-dap/sdk';

const tooltip = new Tooltip();
tooltip.show({
  targetElement: document.querySelector('#my-element'),
  title: 'Step Title',
  content: 'Description text',
  position: 'bottom',    // top|bottom|left|right|top-start|top-end|bottom-start|bottom-end|center
  isFirst: true,
  isLast: false,
  stepIndex: 0,
  totalSteps: 3,
  onNext: () => { /* ... */ },
  onPrev: () => { /* ... */ },
  onDismiss: () => { /* ... */ },
});
tooltip.hide();
tooltip.applyTheme(theme);

Spotlight — Element Highlight / 元素聚光灯

import { Spotlight } from '@ai-dap/sdk';

const spotlight = new Spotlight();
spotlight.highlight(document.querySelector('#target'));
spotlight.clear();
spotlight.applyTheme(theme);

Overlay — Full-screen Dimmer / 全屏遮罩

import { Overlay } from '@ai-dap/sdk';

const overlay = new Overlay();
overlay.show();
overlay.hide();
overlay.applyTheme(theme);

AnalyticsCollector — Event Tracking / 事件追踪

const analytics = sdk.getAnalytics();
analytics.start();                          // Start periodic flush
analytics.stop();                           // Stop and flush
analytics.track('guide_started', { guideId: 'tour-1' });
analytics.setGuideContext(guideId, stepId); // Set current context

Guide Step Format / 引导步骤格式

Each step in a Guide.steps array follows this structure:

interface GuideStep {
  id: string;                // Unique step ID (唯一标识)
  order: number;             // Display order (排序, 1-based)
  title: string;             // Tooltip title (标题)
  content: string;           // Tooltip content (内容)
  target: {
    css: string;             // CSS selector (CSS 选择器)
    fallback?: string;       // Fallback selector (备选选择器)
    waitTimeout?: number;    // Max wait time in ms (最大等待时间)
  };
  position: Position;        // Tooltip position (提示框位置)
  imageUrl?: string;         // Optional image URL (可选图片)
  highlight: boolean;        // Whether to spotlight the target (是否高亮)
  scrollToTarget: boolean;   // Whether to scroll to target (是否滚动到目标)
}

Position Values / 位置取值

top | bottom | left | right | top-start | top-end | bottom-start | bottom-end | center

Full Guide Structure / 完整引导结构

interface Guide {
  id: string;                // Unique guide ID
  appId: string;             // Application ID
  name: string;              // Guide name (引导名称)
  description: string;       // Guide description (引导描述)
  status: 'draft' | 'published' | 'archived';
  steps: GuideStep[];        // Ordered array of steps (步骤数组)
  trigger: {
    type: 'page_load' | 'selector_appears' | 'url_match' | 'manual' | 'schedule' | 'event';
    selector?: string;       // For selector_appears trigger
    urlPattern?: string;     // For url_match trigger
    delay?: number;          // Delay in ms before auto-start
    maxShowCount?: number;   // Max times to show this guide
  };
  theme: {
    primaryColor?: string;   // Brand color (品牌色)
    fontFamily?: string;     // Custom font (自定义字体)
    borderRadius?: number;   // Border radius (圆角大小)
    overlayColor?: string;   // Overlay background color
    overlayOpacity?: number; // Overlay opacity (0-1)
    cssVariables?: Record<string, string>;
  };
  version: number;           // Guide version (版本号)
  i18n?: Record<string, Record<string, { title: string; content: string }>>;
  createdAt: string;
  updatedAt: string;
}

Events / 事件

The GuidePlayer emits the following events (via player.on(event, callback)):

| Event | Payload | Description | |-------|---------|-------------| | start | (guide: Guide) | Guide started (引导开始) | | step:enter | (index: number, step: GuideStep) | Step entered (进入步骤) | | step:exit | (index: number) | Step exited (离开步骤) | | complete | (guide: Guide) | Guide completed (引导完成) | | dismiss | (guide: Guide) | User dismissed (用户关闭) | | stop | (guide: Guide) | Programmatically stopped (程序停止) |

Analytics Events / 分析事件

The AnalyticsCollector automatically tracks:

| Event | When / 触发时机 | |-------|-----------------| | sdk_initialized | SDK init completes (SDK 初始化完成) | | guide_started | Guide begins playing (引导开始播放) | | guide_completed | User finishes all steps (用户完成所有步骤) | | guide_dismissed | User dismisses early (用户提前关闭) | | step_viewed | A step is displayed (步骤被展示) |

Progress Persistence / 进度持久化

The SDK automatically saves guide progress to localStorage under the key dap_guide_progress. Completed guides won't auto-start again.

import { getProgress, updateProgress, isGuideCompleted, getLastStepIndex } from '@ai-dap/sdk';

isGuideCompleted('tour-1');        // boolean
getLastStepIndex('tour-1');        // number
getProgress();                     // Record<string, GuideProgress>
updateProgress('tour-1', 3, false); // Update step 3, not completed

Shadow DOM / 隐私 DOM 隔离

The HelpWidget uses Shadow DOM for complete style isolation. Widget styles are injected inside the shadow root and will never conflict with your application's CSS.

Tooltip, Spotlight, and Overlay use light DOM with CSS variables for theming, making them fully customizable.

Keyboard Navigation / 键盘导航

When a guide is active, the following keyboard shortcuts are available:

| Key | Action | |-----|--------| | ArrowRight / ArrowDown | Next step (下一步) | | ArrowLeft / ArrowUp | Previous step (上一步) | | Escape | Dismiss guide (关闭引导) |

Browser Support / 浏览器支持

| Browser | Version | |---------|---------| | Chrome | 90+ | | Firefox | 88+ | | Safari | 14+ | | Edge | 90+ |

License

MIT