SDK installation

The browser SDK is the simplest path for a web-based answer flow. It lets the publisher prefetch a placement, attach a sponsored card after the AI answer renders, and report events for attribution.

Install

npm install conversaic-sdk-js

Load the browser script

<script
  src="node_modules/conversaic-sdk-js/conversaic.js"
  data-app-id="conv_dev_your_app_id"
  data-base-url="https://api.dev.conversaic.io"
  defer>
</script>

Attribute	Required	Description
`data-app-id`	Yes	Publisher app ID for the current environment.
`data-base-url`	Yes	Conversaic backend URL. Use dev for local and dev builds.

Runtime flow

User asks

Capture the prompt or normalized topic.

Prefetch

Request a possible placement while the AI answer loads.

Render answer

Show the AI response before attaching a sponsored unit.

Attach card

Render only when Conversaic returns a placement payload.

Basic example

Create stable containers in your chat surface.

<div id="chat-response"></div>
<div id="sponsor-slot"></div>

Prefetch a possible placement while your AI answer is loading.

async function onUserMessage(question) {
  Conversaic.prefetch({ context: question });

  const response = await fetch('/api/chat', {
    method: 'POST',
    body: JSON.stringify({ message: question })
  });

  const answer = await response.json();
  document.getElementById('chat-response').innerText = answer.text;

  const container = document.getElementById('sponsor-slot');

  try {
    await Conversaic.attachCard({ context: question, container });
  } catch {
    container.replaceChildren();
  }
}

Environment values

Environment	Base URL
Local / dev	`https://api.dev.conversaic.io`
Production	`https://api.conversaic.io`

Use a dev app ID for local testing. Production app IDs should only be used after the placement and tracking path have been approved.

Common mistakes

Mistake	Fix
Rendering an empty sponsor frame	Clear the container on no-placement.
Reporting impression before visibility	Fire impression only after the card is visible.
Hiding disclosure	Keep the label on the recommendation surface.
Using production keys in local builds	Use dev app IDs and the dev backend.