Gengage AI Assistant — Frontend SDK

Embeddable AI shopping assistant widgets for e-commerce — chat, contextual Q&A, similar products, and an optional find-similar PDP image overlay — 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/chat.iife.js"></script>
<script>
  const chat = new window.Gengage.GengageChat();
  chat.init({
    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/overlay.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' },
    simbut: { mountTarget: '#product-gallery' },
  });
</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 plus reusable product-card renderer configured by labels, field mappings, media, and CSS variables | | SimBut | @gengage/assistant-fe/simbut | PDP image-overlay pill that opens a findSimilar flow for the current product | | Native | @gengage/assistant-fe/native | Android/iOS WebView bridge + overlay bootstrap |

The chat widget includes a built-in history entry point in the header. Past chat sessions are stored per account/user in localStorage, while the active session restore cache continues to use IndexedDB for cross-navigation handoff flows.

Customization

Theme tokens — no fork required:

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

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

SimRel product cards — use createSimRelRenderer for richer product cards without account-specific SDK code:

import { initOverlayWidgets } from '@gengage/assistant-fe/overlay';
import { createSimRelRenderer } from '@gengage/assistant-fe/simrel';

await initOverlayWidgets({
  // ...
  simrel: {
    mountTarget: '#similar-products',
    renderer: createSimRelRenderer({
      labels: { cta: 'View' },
      fields: {
        subtitle: ['categoryNames', 'extras.category_names'],
      },
      media: { promotionIconUrl: '/assets/promo.svg' },
    }),
  },
});

SimBut customization — use theme tokens, i18n.findSimilarLabel, and onFindSimilar for the PDP image-overlay pill.

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

See docs/customization.md for the fork and merchant-customization playbook.

Development

npm install
npm run dev -- koctascomtr --sku=1000465056   # Local dev server with HMR
npm run koctascomtr                            # Merchant shortcut with the seeded demo SKU
npm run trendyolcom                            # Another merchant shortcut using its default PDP SKU
npm run typecheck                              # TypeScript strict check
npm run test                                   # Unit tests
npm run test:chat-history                      # Targeted history + restore regression suite
npm run build                                  # Build to dist/
npm run catalog                                # Visual component catalog at :3002
npm run docs:build                             # Build contributor docs with VitePress

Using a local backend:

npm run dev -- koctascomtr --sku=1000465056 --backend-url=http://localhost:7860

The local demos use the shared defaultDevBackend value from demos/shared/default-dev-backend.ts. For account-specific testing, set MIDDLEWARE_URL to the backend service location provided for your Gengage account:

MIDDLEWARE_URL=http://localhost:7860 npm run dev -- koctascomtr --sku=1000465056

Merchant demo pages under demos/ now seed a default PDP SKU for direct launch flows, and the affected PDP shells hydrate their breadcrumb, summary content, and gallery imagery from middleware productDetails when the backend is available.

Documentation

| Doc | Description | |-----|-------------| | Docs Index | Full documentation map | | API Reference | Public entry points and config surfaces | | Architecture | System design, widget lifecycle, data flows | | Wire Protocol | Backend NDJSON streaming contract | | Customization | CSS tokens, component overrides, XSS rules | | i18n | Locale resolution and string overrides | | Error Handling | Offline, retry, and recovery behavior | | 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 | | AGENTS | Coding-agent architecture and code-path index | | Contributing | Shared SDK contribution workflow |

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)
  simbut/     # PDP image overlay pill widget (GengageSimBut class)
  native/     # Native WebView bridge exports
demos/        # Merchant-branded demo pages and framework integration examples
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.