Gengage AI Assistant — Frontend SDK

Embeddable AI shopping assistant widgets for e-commerce — chat, contextual Q&A, and similar products — built with vanilla TypeScript, zero framework dependencies.

Backend services require a gengage.ai subscription. See LEGAL.md and TRADEMARKS.md.

Choose Your Integration

CDN Script Tag (fastest)

<script src="https://unpkg.com/@gengage/assistant-fe/dist/gengage-assistant.iife.js"></script>
<script>
  GengageAssistant.initFromConfig({
    version: '1',
    accountId: 'YOUR_ACCOUNT_ID',
    middlewareUrl: 'https://YOUR_BACKEND_URL',
  });
</script>

npm / ES Module

npm install @gengage/assistant-fe

import { GengageChat, bootstrapSession } from '@gengage/assistant-fe';

const chat = new GengageChat();
await chat.init({
  accountId: 'mystore',
  middlewareUrl: 'https://YOUR_BACKEND_URL',
  session: { sessionId: bootstrapSession() },
});

Google Tag Manager

<script type="module">
  import { initOverlayWidgets } from 'https://cdn.jsdelivr.net/npm/@gengage/assistant-fe/dist/index.js';

  await initOverlayWidgets({
    accountId: 'YOUR_ACCOUNT_ID',
    middlewareUrl: 'https://YOUR_BACKEND_URL',
    sku: window.productSku,
    pageContext: { pageType: 'pdp' },
    chat: { variant: 'floating' },
    qna: { mountTarget: '#qna-section' },
    simrel: { mountTarget: '#similar-products' },
  });
</script>

Mobile WebView (Android / iOS / React Native)

import { initNativeOverlayWidgets, applyNativeSession } from '@gengage/assistant-fe/native';

applyNativeSession({ sessionId: 'native-session-id', userId: 'native-user-id' });

const { controller, bridge } = await initNativeOverlayWidgets({
  accountId: 'YOUR_ACCOUNT_ID',
  middlewareUrl: 'https://YOUR_BACKEND_URL',
  pageContext: { pageType: 'pdp', sku: '12345' },
  chat: { variant: 'floating', mobileInitialState: 'full' },
});

See docs/native-mobile-sdk.md for iOS WKWebView, Android WebView, and React Native examples.

Widgets

| Widget | Import | What it does | |--------|--------|-------------| | Chat | @gengage/assistant-fe/chat | Floating AI drawer with streaming responses, product cards, comparison tables | | QNA | @gengage/assistant-fe/qna | Contextual action buttons for product pages | | SimRel | @gengage/assistant-fe/simrel | AI-powered similar/related product grid | | Native | @gengage/assistant-fe/native | Android/iOS WebView bridge + overlay bootstrap |

Customization

Theme tokens — no fork required:

chat.init({
  theme: { primaryColor: '#f27a1a', headerBg: '#1a1a2e' },
});

Component overrides — swap any UI component via the json-render registry.

Full fork — replace src/chat/components/ entirely; keep catalog.ts + index.ts.

See CUSTOMIZATION-GUIDE.md for the full playbook.

Development

npm install
npm run dev -- koctascomtr --sku=1000465056   # Local dev server with HMR
npm run typecheck                              # TypeScript strict check
npm run test                                   # 1056 unit tests
npm run build                                  # Build to dist/
npm run catalog                                # Visual component catalog at :3002

Documentation

| Doc | Description | |-----|-------------| | Architecture | System design, widget lifecycle, data flows | | Wire Protocol | Backend NDJSON streaming contract | | Customization | CSS tokens, component overrides, XSS rules | | GTM Quickstart | Copy-paste GTM embedding patterns | | Security | Production CSP, postMessage origins, sanitization | | Analytics | Event taxonomy and attribution | | Mobile SDK | Android/iOS/React Native integration | | New Account | Adding a new merchant demo |

Project Structure

src/
  common/     # Shared: types, NDJSON parser, event bus, sanitizer, utilities
  chat/       # Chat widget (GengageChat class + components)
  qna/        # QNA widget (GengageQNA class + components)
  simrel/     # Similar products widget (GengageSimRel class + components)
  native/     # Native WebView bridge exports
demos/        # 12 merchant-branded demo pages
catalog/      # Visual component catalog (mock data, no backend)
docs/         # Architecture, wire protocol, customization, analytics
tests/        # Vitest unit tests + Playwright E2E

License

Licensed under the GENGAGE FRONTEND SOURCE-AVAILABLE LICENSE v1.0 — see LICENSE.

Backend services are proprietary and require a gengage.ai subscription.