MirrorTour AI SDK

AI-powered website tour guide using Mirror AI. Features voice input, conversation history, offline mode, and custom branding.

Installation

NPM

npm install mirrortour-ai

CDN (jsDelivr - Free)

<!-- Latest version -->
<script src="https://cdn.jsdelivr.net/npm/mirrortour-ai/dist/mirrortour-ai.iife.js" 
        data-mirror-key="YOUR_MIRROR_KEY">
</script>

<!-- Or specific version -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/mirrortour-ai.iife.js" 
        data-mirror-key="YOUR_MIRROR_KEY">
</script>

unpkg (Alternative CDN)

<script src="https://unpkg.com/mirrortour-ai/dist/mirrortour-ai.iife.js" 
        data-mirror-key="YOUR_MIRROR_KEY">
</script>

Usage

ES Module

import { MirrorTourAI } from 'mirrortour-ai';

MirrorTourAI.init({
  mirrorKey: 'YOUR_MIRROR_KEY',
  position: 'bottom-right',
  theme: 'dark',
  // Custom branding
  title: 'My Assistant',
  primaryColor: '#6366f1',
  secondaryColor: '#14b8a6'
});

Script Tag (Auto-init)

<script src="mirrortour-ai.iife.js" 
        data-mirror-key="YOUR_MIRROR_KEY"
        data-position="bottom-right"
        data-theme="dark">
</script>

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | mirrorKey | string | required | Your Mirror AI API key | | apiUrl | string | auto-detect | Backend API URL | | position | string | 'bottom-right' | Orb position (bottom-right, bottom-left) | | theme | string | 'dark' | UI theme (dark, light) | | autoGreet | boolean | true | Auto-greet on first open | | voice | string | 'af_heart' | Kokoro TTS voice ID |

Branding Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | title | string | 'MirrorTour' | Assistant name in header | | primaryColor | string | '#6366f1' | Primary color (Tour mode) | | secondaryColor | string | '#14b8a6' | Secondary color (Chat mode) | | logo | string | null | Custom logo URL | | greeting | string | null | Custom greeting message |

Features

🎤 Voice Input

Click the mic button to speak. Uses Web Speech API.

💬 Conversation History

Messages are saved to localStorage and persist across sessions.

📴 Offline Mode

Messages sent while offline are queued and automatically sent when back online.

📝 Markdown Support

Assistant responses support bold, italic, code, and links.

⏰ Timestamps

Messages show relative timestamps ("Just now", "5m ago", etc.)

🎨 Custom Branding

Fully customizable colors and title to match your brand.

API

// Get instance
const tour = MirrorTourAI.getInstance();

// Open/close modal
tour.open();
tour.close();

// Send message programmatically
tour.sendMessage('Show me pricing');

// Destroy instance
MirrorTourAI.destroy();

DOM Actions

The AI can perform these actions on your page:

| Action | Description | |--------|-------------| | scrollTo | Scroll to an element | | highlight | Highlight an element with pulse effect | | click | Click a button or link | | fillInput | Fill form fields | | navigate | Navigate to a URL (same page) | | openLink | Open external link in new tab |

Backend Setup

The SDK requires a backend server running the MirrorTour API. See the main repository for setup instructions.

Building

cd sdk
npm install
npm run build

Outputs:

• dist/mirrortour-ai.es.js - ES Module
• dist/mirrortour-ai.umd.js - UMD
• dist/mirrortour-ai.iife.js - Script tag

Publishing to NPM

npm login
npm publish

License

MIT

Website Integration Guide

Mirror Tour AI works by analyzing your website's DOM structure. Follow these guidelines for the best experience.

1. Semantic HTML Structure

• Headings: Use <h1> for main titles, <h2> for section titles.
• Navigation: Use <nav> for menus.
• Sections: Use <section> or <article> to group content.

2. Interactive Elements MUST Have IDs

For the AI to click buttons, fill inputs, or scroll to specific areas, elements must have unique IDs.

<!-- BAD -->
<button class="signup-btn">Sign Up</button>

<!-- GOOD -->
<button id="signup-btn">Sign Up</button>
<section id="pricing">...</section>

Why? The AI generates a "Page Context" that lists interactive elements by their ID (#signup-btn). If an ID is missing, the AI cannot interact with it.

3. Clear Text Content

• Avoid breaking text into many small <span> tags.
• Ensure visible text is actual text in the DOM, not images.

4. Testing Compatibility

Run this in your browser console:

document.querySelectorAll('*[id]').length

If the number is low (< 5), add more IDs to important elements (Nav links, CTA buttons, Form inputs).