Conversaic SDK JS — Monetize Your AI Product

Conversaic Publisher JS SDK helps developers earn affiliate revenue by displaying contextual sponsored recommendation cards in browser-based AI products — AI chat, AI search, education assistants, productivity tools, and developer tools.

本 Skill 帮助开发者将 Conversaic Publisher JS SDK 接入浏览器端 AI 产品，在用户问答流中展示清晰标注的 sponsored recommendation / affiliate offer card，实现 AI 产品变现。

安装 / Installation

官方安装方法以 npm 页面为准：

https://www.npmjs.com/package/conversaic-sdk-js

常用 npm 安装命令：

npm install conversaic-sdk-js

基础 script tag 接入：

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

把 YOUR_APP_ID 替换成 publisher workspace 里审核通过后获得的真实 app_id，例如 conv_...。如果项目通过 bundler 或自托管静态资源加载 SDK，也要保持相同的 data-app-id 配置。

前置条件 / Prerequisites

在写接入代码前，发布方需要完成以下前提：

1. 打开 https://conversaic.io 并注册或登录。
2. 填写并提交 publisher pilot/application form。
3. 等待 Conversaic 审核通过；提交申请不等于自动开通。
4. 审核通过后，从 publisher workspace 获取 app_id。
5. 确认要接入 SDK 的测试域名或生产域名已经登记到 Conversaic 的 allowed domains 中。

不要编造 app_id、API key、审核状态或 allowed domain。app_id 是公开标识，可以放在 HTML 或前端代码里；它不是 secret。Conversaic 会在服务端用 publisher app 状态和域名 allowlist 校验请求来源。

推荐接入流程 / Integration

1. 找到用户提交问题或上下文的位置。
2. 在调用产品自身 AI 后端的同时，尽早调用 Conversaic.prefetch({ context })。
3. 等 AI 回答渲染完成后，在 sponsored card 容器里调用 Conversaic.attachCard({ context, container })。
4. 如果没有返回 placement，不要显示空广告位，也不要伪造推荐内容。
5. 保留 Conversaic 返回的 cta_url，不要绕过它跳转到商家原始链接；该链接用于点击和 affiliate attribution。

示例：

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

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

    const aiResponse = await fetch('/api/chat', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ message: question })
    }).then((response) => response.json());

    document.getElementById('chat-container').innerText = aiResponse.text;

    Conversaic.attachCard({
      context: question,
      container: document.getElementById('sponsor-slot')
    });
  }
</script>

自定义渲染 / Custom Rendering

如果产品需要自定义 UI，先取 placement，再自己渲染。必须保留 sponsored/affiliate 标注和 Conversaic 返回的追踪链接。

const card = await Conversaic.getPlacement({
  context: 'What laptop should I buy for coding?'
});

if (card) {
  renderMySponsoredCard({
    label: card.label,
    title: card.title,
    description: card.description,
    ctaUrl: card.cta_url
  });
}

如果使用 SDK 内置样式：

const card = await Conversaic.getPlacement({ context: userQuestion });

if (card) {
  Conversaic.renderCard(card, document.getElementById('sponsor-slot'));
}

常见排查 / Troubleshooting

• Conversaic is not defined：确认 SDK script 已加载，并且业务代码在 script 之后执行。
• 没有返回推荐卡：可能是当前 query 没有合适 offer；不要用假卡片兜底。
• 返回 401 或 403：检查 app_id 是否真实、publisher app 是否已审批通过、当前页面域名是否在 allowed domains 中。
• 本地或测试环境失败：确认测试域名、localhost 或预览域名是否已登记；必要时使用正确的 data-base-url。
• 点击或收益无法归因：确认使用的是 card.cta_url，没有改写或绕过 Conversaic 的追踪链接。

输出要求 / Output Requirements

当用户让你接入 Conversaic SDK 时，输出应包含：

1. 官方 npm 链接和安装命令。
2. 需要他们先完成申请和审核的提醒。
3. 放入真实 app_id 的具体位置。
4. 最小可运行的接入代码。
5. 对空 placement、域名 allowlist、追踪链接的注意事项。