3Guide SDK Installation & Usage

<script
  src="https://cdn.3guideai.com/sdk/guideai.js"
  data-site-id="site_YOUR_SITE_ID"
  data-token="pk_live_YOUR_TOKEN"
></script>

<script
  src="https://cdn.3guideai.com/sdk/guideai-tracking.js"
  data-site-id="site_YOUR_SITE_ID"
  data-token="pk_live_YOUR_TOKEN"
></script>

<script>
(function(siteId, publicToken, apiUrl, cdnUrl){
  (function(p, e, n, d){
    var v, w, x, o;
    o = p[d] = p[d] || {};
    o._q = o._q || [];
    o._loaded = false;
    v = ['initialize','identify','updateOptions','pageLoad',
         'markFeature','showGuideById','dismissGuide',
         'validateGuideById','on','destroy','flushNow',
         'clearSession','startRecording','stopRecording',
         'cancelRecording','saveGuide',
         'showNPSSurvey','showCSATSurvey'];
    for (w = 0, x = v.length; w < x; ++w) (function(m){
      o[m] = o[m] || function(){
        o._q[m === 'initialize' ? 'unshift' : 'push'](
          [m].concat([].slice.call(arguments, 0))
        );
      };
    })(v[w]);
    var y = e.createElement(n);
    y.async = true;
    y.src = (cdnUrl || 'https://cdn.3guideai.com') + '/sdk/guideai.js';
    y.setAttribute('data-site-id', siteId);
    y.setAttribute('data-token', publicToken);
    if (apiUrl) y.setAttribute('data-api-url', apiUrl);
    var z = e.getElementsByTagName(n)[0];
    z.parentNode.insertBefore(y, z);
  })(window, document, 'script', 'guideai');
})(
  'site_YOUR_SITE_ID',
  'pk_live_YOUR_TOKEN',
  undefined, // apiUrl (optional)
  undefined  // cdnUrl (optional)
);
</script>

<script>
(function(siteId, publicToken, apiUrl, cdnUrl){
  (function(p, e, n, d){
    var v, w, x, o;
    o = p[d] = p[d] || {};
    o._q = o._q || [];
    o._loaded = false;
    v = ['initialize','identify','updateOptions','pageLoad','track',
         'trackFeature','markFeature','on','destroy','flushNow',
         'clearSession','showNPSSurvey','showCSATSurvey'];
    for (w = 0, x = v.length; w < x; ++w) (function(m){
      o[m] = o[m] || function(){
        o._q[m === 'initialize' ? 'unshift' : 'push'](
          [m].concat([].slice.call(arguments, 0))
        );
      };
    })(v[w]);
    var y = e.createElement(n);
    y.async = true;
    // NOTE: Use guideai-tracking.js for tracking-only
    y.src = (cdnUrl || 'https://cdn.3guideai.com') + '/sdk/guideai-tracking.js';
    y.setAttribute('data-site-id', siteId);
    y.setAttribute('data-token', publicToken);
    if (apiUrl) y.setAttribute('data-api-url', apiUrl);
    var z = e.getElementsByTagName(n)[0];
    z.parentNode.insertBefore(y, z);
  })(window, document, 'script', 'guideai');
})(
  'site_YOUR_SITE_ID',
  'pk_live_YOUR_TOKEN',
  undefined, // apiUrl (optional)
  undefined  // cdnUrl (optional)
);
</script>

<script
  src="https://cdn.3guideai.com/sdk/guideai.js"
  data-site-id="site_abc123"
  data-token="pk_live_xyz789"
  data-api-url="https://api.3guideai.com"
  data-cdn-url="https://cdn.3guideai.com"
  data-bubble-enabled="true"
  data-bubble-position="bottom-right"
  data-bubble-icon="robot"
  data-bubble-mode="drift"
  data-bubble-label=""
  data-widget-mode="guide"
  data-guides-enabled="true"
  data-auto-advance-on-target-click="true"
  data-chip-dismiss-seconds="300"
  data-theme-primary="#6366f1"
  data-theme-background="#ffffff"
  data-theme-text="#111827"
  data-theme-font="Inter"
></script>

<script
  src="https://cdn.3guideai.com/sdk/guideai-tracking.js"
  data-site-id="site_abc123"
  data-token="pk_live_xyz789"
  data-api-url="https://api.3guideai.com"
  data-cdn-url="https://cdn.3guideai.com"
  data-recording="true"
  data-idle-timeout="20000"
  data-session-timeout-ms="1800000"
  data-batch-size="50"
  data-batch-interval-ms="30000"
  data-geolocation="off"
  data-help-hints="true"
  data-feedback-auto-prompt="true"
  data-feedback-prompt-delay-ms="300000"
  data-feedback-prompt-min-pageviews="10"
  data-announcement-surface="modal"
  data-announcement-frequency="once"
  data-announcement-display-mode="auto"
  data-announcement-auto-show-delay-ms="500"
  data-chip-dismiss-seconds="300"
  data-theme-primary="#6366f1"
  data-theme-background="#ffffff"
  data-theme-text="#111827"
  data-theme-font="Inter"
></script>

// Manual page_view for custom routing
window.guideai.pageLoad("/dashboard/settings");

// app/layout.tsx
import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        {/* Full SDK — or use guideai-tracking.js for tracking-only */}
        <Script
          src="https://cdn.3guideai.com/sdk/guideai.js"
          data-site-id="site_YOUR_SITE_ID"
          data-token="pk_live_YOUR_TOKEN"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

<!-- index.html -->
<!DOCTYPE html>
<html>
  <head>
    <title>My App</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
    <script
      src="https://cdn.3guideai.com/sdk/guideai.js"
      data-site-id="site_YOUR_SITE_ID"
      data-token="pk_live_YOUR_TOKEN"
    ></script>
  </body>
</html>

// nuxt.config.ts
export default defineNuxtConfig({
  app: {
    head: {
      script: [
        {
          src: "https://cdn.3guideai.com/sdk/guideai.js",
          "data-site-id": "site_YOUR_SITE_ID",
          "data-token": "pk_live_YOUR_TOKEN",
          defer: true,
        },
      ],
    },
  },
});

<!DOCTYPE html>
<html>
  <head>
    <title>My Website</title>
  </head>
  <body>
    <h1>Welcome</h1>

    <!-- Add before closing body tag -->
    <script
      src="https://cdn.3guideai.com/sdk/guideai.js"
      data-site-id="site_YOUR_SITE_ID"
      data-token="pk_live_YOUR_TOKEN"
    ></script>
  </body>
</html>

# Run with npx (no install)
npx guideai-scan --key sk_live_YOUR_KEY --dir ./my-app

# Or install globally
npm install -g @guideai/scanner
guideai-scan --key sk_live_YOUR_KEY --dir ./my-app

npx guideai-scan --dir ./my-app --dry-run --output scan-result.json

{
  "framework": "nextjs-app-router",
  "routes": [
    {
      "path": "/dashboard",
      "page_title": "Dashboard",
      "component_name": "Dashboard",
      "dynamic_segments": [],
      "auth_required": false,
      "headings": ["Dashboard", "Analytics"]
    }
  ],
  "ui_map": { /* hierarchical component tree */ },
  "duration_ms": 1234
}

// vite.config.ts
import { guideaiPlugin } from "@guideai/scanner/plugins/vite";

export default defineConfig({
  plugins: [
    guideaiPlugin({
      key: process.env.GUIDEAI_KEY,
    }),
  ],
});

// webpack.config.js
const { GuideAIWebpackPlugin } = require("@guideai/scanner/plugins/webpack");

module.exports = {
  plugins: [
    new GuideAIWebpackPlugin({
      key: process.env.GUIDEAI_KEY,
    }),
  ],
};

<!-- Copilot enabled by default with bubble -->
<script
  src="https://cdn.3guideai.com/sdk/guideai.js"
  data-site-id="site_YOUR_SITE_ID"
  data-token="pk_live_YOUR_TOKEN"
  data-bubble-enabled="true"
  data-widget-mode="guide"
></script>

<script
  src="https://cdn.3guideai.com/sdk/guideai-tracking.js"
  data-site-id="site_YOUR_SITE_ID"
  data-token="pk_live_YOUR_TOKEN"
  data-recording="true"
></script>

// Track custom events
window.guideai.track("checkout_started", {
  cart_value: 99.99,
  item_count: 3,
});

// Track feature usage
window.guideai.trackFeature("dark_mode", "Toggled Dark Mode");

// Mark feature as used (for audience targeting)
window.guideai.markFeature("used_export");

<!-- Set the bubble icon -->
<script
  src="https://cdn.3guideai.com/sdk/guideai.js"
  data-site-id="site_YOUR_ID"
  data-token="pk_live_YOUR_TOKEN"
  data-bubble-icon="owl"
></script>

<!-- Or use a custom image -->
<script
  src="https://cdn.3guideai.com/sdk/guideai.js"
  data-site-id="site_YOUR_ID"
  data-token="pk_live_YOUR_TOKEN"
  data-bubble-image="https://yoursite.com/mascot.gif"
></script>

data-bubble-position="bottom-right"  <!-- default -->
data-bubble-position="bottom-left"

<!-- Drift mode (default) -->
data-bubble-mode="drift"

<!-- Crawl mode (ant walk along edges) -->
data-bubble-mode="crawl"

<!-- Drift fine-tuning -->
data-bubble-drift-spring="0.0003"
data-bubble-drift-damping="0.993"
data-bubble-drift-min-interval="18000"
data-bubble-drift-max-interval="26000"

<!-- Crawl fine-tuning -->
data-bubble-crawl-speed="40"
data-bubble-crawl-climb-walls="true"
data-bubble-crawl-corner-pause-ms="1500"
data-bubble-crawl-persistent-speech="true"
data-bubble-crawl-message-interval-ms="8000"

<!-- Custom theme (Full SDK) -->
<script
  src="https://cdn.3guideai.com/sdk/guideai.js"
  data-site-id="site_YOUR_ID"
  data-token="pk_live_YOUR_TOKEN"
  data-theme-primary="#0ea5e9"
  data-theme-background="#f8fafc"
  data-theme-text="#0f172a"
  data-theme-font="Plus Jakarta Sans"
></script>

<!-- Custom theme (Tracking SDK) -->
<script
  src="https://cdn.3guideai.com/sdk/guideai-tracking.js"
  data-site-id="site_YOUR_ID"
  data-token="pk_live_YOUR_TOKEN"
  data-theme-primary="#0ea5e9"
  data-theme-background="#f8fafc"
  data-theme-text="#0f172a"
  data-theme-font="Plus Jakarta Sans"
></script>

data-announcement-surface="modal"   <!-- centered overlay (default) -->
data-announcement-surface="banner"  <!-- top banner strip -->
data-announcement-surface="drawer"  <!-- bottom sheet -->

data-announcement-frequency="once"             <!-- show once ever -->
data-announcement-frequency="once_per_session" <!-- once per session -->
data-announcement-frequency="once_per_day"     <!-- daily -->
data-announcement-frequency="every_visit"      <!-- every page load -->

data-announcement-display-mode="auto"    <!-- show immediately -->
data-announcement-display-mode="beacon"  <!-- show pulsing dot first -->

<script
  src="https://cdn.3guideai.com/sdk/guideai.js"

  <!-- Required -->
  data-site-id="site_abc123"
  data-token="pk_live_xyz789"

  <!-- Endpoints -->
  data-api-url="https://api.3guideai.com"
  data-cdn-url="https://cdn.3guideai.com"

  <!-- Bubble appearance -->
  data-bubble-enabled="true"
  data-bubble-position="bottom-right"
  data-bubble-icon="owl"
  data-bubble-label="Help"
  data-bubble-mode="drift"
  data-widget-mode="combined"

  <!-- Drift fine-tuning -->
  data-bubble-drift-spring="0.0003"
  data-bubble-drift-damping="0.993"
  data-bubble-drift-min-interval="18000"
  data-bubble-drift-max-interval="26000"
  data-bubble-drift-enabled="true"

  <!-- Theme -->
  data-theme-primary="#7c3aed"
  data-theme-background="#ffffff"
  data-theme-text="#111827"
  data-theme-font="Inter"

  <!-- Guides -->
  data-guides-enabled="true"
  data-auto-advance-on-target-click="true"
  data-feedback-auto-prompt="true"
  data-feedback-prompt-delay-ms="300000"
  data-feedback-prompt-min-pageviews="10"
  data-chip-dismiss-seconds="300"

  <!-- Analytics & session -->
  data-recording="true"
  data-idle-timeout="20000"
  data-session-timeout-ms="1800000"
  data-batch-size="50"
  data-batch-interval-ms="30000"
  data-geolocation="off"

  <!-- Announcements -->
  data-announcement-surface="modal"
  data-announcement-frequency="once"
  data-announcement-display-mode="auto"
  data-announcement-auto-show-delay-ms="500"
  data-announcement-close-on-backdrop="true"

  <!-- Help hints -->
  data-help-hints="true"
  data-help-hints-cache-ttl-ms="86400000"
></script>