@action-x/ad-sdk

An ad SDK for AI conversation experiences, with zero framework dependencies. Works with Vanilla JS, Vue, React, Angular, Svelte, and more.

Installation

npm install @action-x/ad-sdk
# or
yarn add @action-x/ad-sdk
# or
pnpm add @action-x/ad-sdk

Import styles (required):

import '@action-x/ad-sdk/style.css';

AdCard Component

Below are AdCard wrapper examples for different frameworks. The component takes query and response from the AI conversation, then automatically requests and renders an ad card after the response is complete.

Vue 3

<!-- AdCard.vue -->
<template>
  <div ref="adEl" />
</template>

<script setup>
import { ref, onMounted, onUnmounted } from 'vue';
import { AdManager } from '@action-x/ad-sdk';
import '@action-x/ad-sdk/style.css';

const props = defineProps(['query', 'response']);
const adEl = ref(null);
let manager;

onMounted(async () => {
  manager = new AdManager({
    apiBaseUrl: 'https://your-api.example.com/api/v1',
    apiKey: 'ak_your_api_key',
  });

  await manager.requestAds({ query: props.query, response: props.response });

  manager.render(adEl.value);
});

onUnmounted(() => manager?.destroy());
</script>

React

// components/AdCard.tsx
import { useEffect, useRef } from 'react';
import { AdManager } from '@action-x/ad-sdk';
import '@action-x/ad-sdk/style.css';

interface Props {
  query: string;
  response: string;
}

export function AdCard({ query, response }: Props) {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const manager = new AdManager({
      apiBaseUrl: 'https://your-api.example.com/api/v1',
      apiKey: 'ak_your_api_key',
    });

    manager
      .requestAds({ query, response })
      .then(() => {
        if (containerRef.current) {
          manager.render(containerRef.current);
        }
      });

    return () => manager.destroy();
  }, [query, response]);

  return <div ref={containerRef} />;
}

Vanilla JavaScript

import { AdManager } from '@action-x/ad-sdk';
import '@action-x/ad-sdk/style.css';

const manager = new AdManager({
  apiBaseUrl: 'https://your-api.example.com/api/v1',
  apiKey: 'ak_your_api_key',
});

// Request and render ads after the AI response is complete
await manager.requestAds({
  query: 'Recommend a Bluetooth headset',
  response: 'Here are several popular Bluetooth headset options...',
});

manager.render(document.getElementById('ad-card'));

CDN (No Build Tool)

<link rel="stylesheet" href="https://unpkg.com/@action-x/ad-sdk/style.css" />
<script src="https://unpkg.com/@action-x/ad-sdk/dist/index.umd.js"></script>

<div id="ad-card"></div>

<script>
  const { AdManager } = ActionXAdSDK;

  const manager = new AdManager({
    apiBaseUrl: 'https://your-api.example.com/api/v1',
    apiKey: 'ak_your_api_key',
  });

  manager
    .requestAds({ query: 'User question', response: 'AI response' })
    .then(() => {
      manager.render(document.getElementById('ad-card'));
    });
</script>

Usage Example

Render an Ad Card After AI Response Completes

Using React as an example, render AdCard after streaming output finishes:

import { useState } from 'react';
import { AdCard } from './components/AdCard';

export function ChatMessage() {
  const [query, setQuery] = useState('');
  const [response, setResponse] = useState('');
  const [isStreaming, setIsStreaming] = useState(false);

  async function handleSend(userQuery: string) {
    setQuery(userQuery);
    setIsStreaming(true);
    setResponse('');

    // Receive AI response as a stream
    const stream = await fetchAIResponse(userQuery);
    let fullResponse = '';
    for await (const chunk of stream) {
      fullResponse += chunk;
      setResponse(fullResponse);
    }

    setIsStreaming(false);
    // After response completes, AdCard will request and render automatically
  }

  return (
    <div>
      <div className="response">{response}</div>

      {/* Show ad card after response streaming ends */}
      {!isStreaming && response && (
        <AdCard query={query} response={response} />
      )}
    </div>
  );
}

Configuration

new AdManager(config)

| Parameter | Type | Required | Description | |------|------|------|------| | apiBaseUrl | string | Yes | API base URL, e.g. https://your-api.example.com/api/v1 | | apiKey | string | Yes | API authentication key | | cardOption | CardOption | No | Card options with sensible defaults |

Card Options cardOption

| Parameter | Type | Default | Description | |------|------|--------|------| | variant | 'horizontal' \| 'vertical' \| 'compact' | 'horizontal' | Layout style | | count | number | 1 | Number of ads to request |

Customization example:

new AdManager({
  apiBaseUrl: '...',
  apiKey: '...',
  cardOption: {
    variant: 'vertical',
    count: 2,
  },
});

requestAds(context)

| Parameter | Type | Required | Description | |------|------|------|------| | query | string | Yes | User question | | response | string | Yes | AI response text |

render(container, options?)

| Parameter | Type | Description | |------|------|------| | container | HTMLElement | Mount container | | options.onClick | (ad) => void | Click callback | | options.onImpression | (ad) => void | Impression callback |

Event Listeners

manager.on('adsUpdated',   (slots) => { /* ad data ready */ });
manager.on('adsLoading',   ()      => { /* requesting */ });
manager.on('adsError',     (err)   => { /* request failed */ });
manager.on('adClicked',    (adId, slotId) => { });
manager.on('adImpression', (adId, slotId) => { });

Version: 0.1.0 | License: MIT