conversaic-sdk-js
v1.0.1
Published
Conversaic Publisher JS SDK — browser SDK for affiliate sponsor card integration in conversational AI products
Downloads
231
Maintainers
gengxing-appReadme
conversaic-sdk-js
Browser SDK for integrating Conversaic affiliate sponsor cards into conversational AI products.
Zero-dependency, single-file SDK. Works with any frontend framework or vanilla HTML.
Installation
Option A: npm (Recommended)
npm install conversaic-sdk-js<script src="node_modules/conversaic-sdk-js/conversaic.js"
data-app-id="YOUR_APP_ID">
</script>Option B: Self-hosted
Download conversaic.js and serve it from your own static assets.
Quick Start
<!DOCTYPE html>
<html>
<head>
<script src="node_modules/conversaic-sdk-js/conversaic.js"
data-app-id="conv_your_app_id"
data-base-url="https://api.conversaic.io">
</script>
</head>
<body>
<div id="chat-container"></div>
<div id="sponsor-slot"></div>
<script>
// When user asks a question:
async function onUserMessage(question) {
// 1. Start prefetching sponsor card (parallel with AI call)
Conversaic.prefetch({ context: question });
// 2. Call your AI backend
const aiResponse = await fetch('/api/chat', {
method: 'POST',
body: JSON.stringify({ message: question })
}).then(r => r.json());
// 3. Display AI response
document.getElementById('chat-container').innerText = aiResponse.text;
// 4. Attach sponsor card (renders immediately if prefetch finished)
Conversaic.attachCard({
context: question,
container: document.getElementById('sponsor-slot')
});
}
</script>
</body>
</html>API Reference
Conversaic.init(options)
Manual initialization (optional — the SDK auto-inits from data-* attributes on the script tag).
Conversaic.init({
appId: 'conv_your_app_id',
baseUrl: 'https://api.conversaic.io' // optional, defaults to same origin
});| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| appId | string | ✅ | Your Conversaic publisher app ID |
| baseUrl | string | — | API base URL (default: window.location.origin) |
Conversaic.prefetch(options)
Start fetching a sponsor card in the background. Call this as early as possible (e.g., when the user submits a message) to minimize latency.
Conversaic.prefetch({ context: 'What laptop should I buy for coding?' });| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| context | string | ✅ | The user's question or conversation context |
Conversaic.attachCard(options)
Fetch (or use prefetched) sponsor card and render it into a DOM container.
Conversaic.attachCard({
context: 'What laptop should I buy for coding?',
container: document.getElementById('sponsor-slot')
});| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| context | string | ✅ | The user's question (should match prefetch context) |
| container | HTMLElement | ✅ | DOM element to render the card into |
Conversaic.getPlacement(options)
Fetch a sponsor card without rendering it. Returns the card data object.
const card = await Conversaic.getPlacement({
context: 'Best running shoes for beginners'
});
if (card) {
console.log(card.title); // "REI Outdoor & Fitness Gear"
console.log(card.description); // "Find the best gear for your next adventure"
console.log(card.cta_url); // "https://tracking.example.com/click?offer=rei&..."
}Returns: Promise<Card | null>
interface Card {
title: string;
description: string;
cta_url: string;
label: string;
tracking_ids: {
impression_id: string;
click_id: string;
};
}Conversaic.renderCard(card, targetEl)
Render a card object into a DOM element with built-in styling.
const card = await Conversaic.getPlacement({ context: '...' });
if (card) {
Conversaic.renderCard(card, document.getElementById('sponsor-slot'));
}Conversaic.reportImpression(options)
Manually report an impression (called automatically by renderCard and attachCard).
Conversaic.reportImpression({
impressionId: card.tracking_ids.impression_id,
clickId: card.tracking_ids.click_id
});Configuration via Script Tag
| Attribute | Description |
|-----------|-------------|
| data-app-id | Your Conversaic publisher app ID (required) |
| data-base-url | API base URL (optional, defaults to same origin) |
How It Works
- Publisher registers on the Conversaic platform and gets an
app_id - SDK loads on the publisher's page and reads the
app_id - When a user asks a question, the SDK sends the context to Conversaic's matching API
- Conversaic matches relevant sponsor offers based on the query intent
- SDK renders a clearly labeled sponsor card with tracking
- Clicks and impressions are tracked for attribution and payouts
User question → SDK.prefetch(context) → Matching API → Sponsor Card
↓
AI response → SDK.attachCard(context, container) → Rendered CardSecurity
app_idis a public identifier (safe to embed in HTML)- Authentication is enforced server-side via domain allowlist
- The browser automatically sets the
Originheader — JavaScript cannot forge it - Only requests from domains registered to the publisher app receive placements
Browser Support
Works in all modern browsers (Chrome, Firefox, Safari, Edge). No polyfills needed.
License
Proprietary — see LICENSE for terms.
© 2026 Conversaic. All rights reserved.