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.
OptionTypeDescription
querystringUser’s search query or intent text.
contextstringPage context or category.
limitnumberNumber of ads to fetch (1–8, default 1).
userIdstringStable user identifier (not PII).
sessionIdstringSession identifier.
signalsSignal[]Typed intent signals.
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:
ParameterDescription
api_keyYour channel API key (required).
placementDefault ad placement type (default: sponsored_result).

​
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.

Need server-side integration?

Use the REST API for full control over ad fetching and rendering from your backend.