JavaScript SDK

Drop-in JavaScript SDK for displaying AIARCO ads on websites and SPAs. Auto-renders ads with built-in impression tracking.

Drop-in script tag for websites and single-page apps. Handles fetching, rendering, and impression tracking automatically.

Installation

Add the script tag to your page. Pass your channel API key as a query parameter:

<script src="https://ads-api.aiarco.com/api/v1/sdk.js?api_key=aiarco_YOUR_KEY"></script>

This creates a global window.AIARCO object with all SDK methods. The SDK is lightweight (~4KB) and has no external dependencies.

Quick Start

Render a single ad in a container:

<!-- 1. Add the SDK -->
<script src="https://ads-api.aiarco.com/api/v1/sdk.js?api_key=aiarco_YOUR_KEY"></script>
 
<!-- 2. Add a container -->
<div id="aiarco-ad"></div>
 
<!-- 3. Render an ad -->
<script>
  AIARCO.renderAd("aiarco-ad", {
    query: "best coffee machines",
    context: "shopping",
  });
</script>

API Reference

AIARCO.fetchAd(opts)

Fetch offers from the API. Returns a Promise resolving to the full API response.

const data = await AIARCO.fetchAd({
  query: "wireless earbuds",
  context: "electronics",
  limit: 3,
  userId: "usr_abc123",
});
 
// data.offers — array of offer objects
// data.ad — first offer (legacy compat)
// data.impression_id — first offer ID (legacy compat)

AIARCO.renderAd(containerId, opts)

Fetch and render a single ad into a DOM element. Automatically sets up IntersectionObserver for viewability tracking.

AIARCO.renderAd("aiarco-ad", {
  query: "running shoes",
  context: "sports",
});

AIARCO.renderAds(containerId, opts)

Fetch and render multiple ads into a container. Defaults to 3 ads.

AIARCO.renderAds("aiarco-ads", {
  query: "project management tools",
  context: "software",
  limit: 4,
});

AIARCO.trackImpressions(ids)

Manually track impression viewability for one or more offer IDs. This is handled automatically by renderAd and renderAds via IntersectionObserver, but can be called directly for custom rendering.

// Track after confirming visibility
AIARCO.trackImpressions(["offer-id-1", "offer-id-2"]);

AIARCO.getSystemPromptOffers(opts)

Fetch offers and return a serialized XML string for injection into an LLM system prompt. See Woven Offers for the complete guide.

const systemPromptSuffix = await AIARCO.getSystemPromptOffers({
  query: userMessage,
  limit: 3,
});
 
// Append to your base system prompt
const fullPrompt = baseSystemPrompt + "\n\n" + systemPromptSuffix;

AIARCO.trackWovenImpressions(ids)

Track which woven offer IDs appeared in the rendered LLM response. Only call for offers whose clickUrl was included in the rendered text.

// After rendering the LLM response
const appearedIds = offers
  .filter((o) => renderedHtml.includes(o.clickUrl))
  .map((o) => o.id);
 
AIARCO.trackWovenImpressions(appearedIds);

Configuration

The SDK auto-configures from the script tag URL parameters:

Automatic Features

• Viewability tracking — when using renderAd or renderAds, the SDK automatically tracks when ads are visible to the user.
• Device detection — automatically detects device type and sends it with each request.
• Locale detection — detects the user's locale automatically.
• Deduplication — each impression is only tracked once.