@elo-ads/web-sdk

The Elo web SDK for rendering in-chat, conversation-aware ads in React apps. It fetches an ad for the current conversation, renders it as a native card, and handles render + viewable-impression tracking for you.

The product is Elo (elo.ad). This is the JS/web SDK, a sibling to the iOS and Android SDKs.

Install

npm install @elo-ads/web-sdk

It's a browser package and must be consumed through a bundler (Vite, Next.js, webpack) — it is not meant to run in plain Node. react and react-dom (v18 or v19) are peer dependencies.

Quick start

import { EloSDK, EloAd } from '@elo-ads/web-sdk'
import type { AdCreative } from '@elo-ads/web-sdk'
import { useEffect, useState } from 'react'

const sdk = new EloSDK({
  publisherId: 'YOUR_PUBLISHER_ID',
  adUnitId: 'YOUR_AD_UNIT_ID',
  backendUrl: 'https://api.withgrowl.com',
})

export function ChatAd({ messages }: { messages: { role: 'user' | 'assistant' | 'summary'; content: string }[] }) {
  const [ad, setAd] = useState<AdCreative | null>(null)

  useEffect(() => {
    sdk.init().then((result) => {
      if (result.status !== 'ready') return // e.g. 'gdpr_consent_missing'
      sdk.fetchAds({ messages }).then((res) => setAd(res.ad))
    })
  }, [])

  // No-fill: when `ad` is null, render nothing.
  return ad && <EloAd sdk={sdk} ad={ad} />
}

<EloAd> fires the render event on mount and a viewable impression once the card has been ≥50% visible for 1 second — you don't fire any tracking yourself.

API

new EloSDK(config: EloConfig)

| Field | Type | Required | Description | | ------------- | ----------- | -------- | ------------------------------------------------------ | | publisherId | string | Yes | Your Elo publisher ID. | | adUnitId | string | Yes | The ad unit to request. | | backendUrl | string | Yes | Elo ad server URL (e.g. https://api.withgrowl.com). | | coppa | 0 \| 1 | No | COPPA flag passed through to the ad server. | | tfua | 0 \| 1 | No | "Tag for users under age of consent" flag. |

sdk.init(): Promise<InitResult>

Resolves the visitor ID (localStorage → cookie → generated), starts a session, and reads consent signals. Returns { status: 'ready' } when ad requests can proceed, or { status: 'gdpr_consent_missing' } when GDPR applies but no TCF consent string is present (don't request ads in that case). Call once before fetchAds. Calling it again starts a new session and clears the SDK's tracking state, so ads shown under the new session report independently of the old one.

sdk.fetchAds(params: FetchAdsParams): Promise<AdResponse>

interface FetchAdsParams {
  messages: { role: 'user' | 'assistant' | 'summary'; content: string }[]
  context?: { type: string; description: string }[]
}

Requests an ad for the current conversation. Send the full message history for the most relevant ad, or — for long conversations — a single summary-role message plus the most recent turns. The response is:

interface AdResponse {
  request_id: string
  ad: AdCreative | null // null on no-fill
  ecpm: number | null
}

Throws if the request fails (non-2xx response).

The returned ad carries two identities. opportunity_id is this showing — one per serve, and what the ad server keys render, impression, and click on; correlate delivery on it. ad_id is the creative, stable across opportunities; group by it. They mirror EloAd.id and EloAd.creativeId on iOS and Android.

sdk.setUserIdentifier(identifier: string | null)

Publishers with their own account system can supply the identity they already have (e.g. their user ID). When set, it is sent as visitor_id in place of the SDK's anonymous ID on ad requests and tracking pings, so delivery, frequency capping, and reporting follow the user rather than the browser. Mirrors Elo.setUserIdentifier on iOS and Android.

• Held in memory only: re-set it after sign-in on each page load, and call setUserIdentifier(null) on sign-out.
• The anonymous ID stays persisted underneath; clearing restores the identity the browser had before.
• Values are trimmed, a blank string clears, and identifiers over 256 Unicode code points are rejected with a console warning.
• Tracking pings use the identity that was in effect when the ad was fetched.

sdk.setUserData(data: EloUserData | null)

Publishers who know more about their signed-in user can share it for upcoming targeting features. The data rides along on ad requests as an optional user object; it is stored server-side and never joins tracking pings. It has no effect on ad selection today: the fields are recorded and nothing else.

interface EloUserData {
  age?: number // integer
  gender?: 'male' | 'female' | 'other'
  email?: string // case and whitespace don't matter
  phone?: string // E.164, e.g. "+15551234567"
}

• Contact details are hashed on receipt. email and phone travel over HTTPS and are SHA-256 hashed at the ad server before anything is stored, so Elo never persists a plain email address or phone number. You don't need to hash them yourself.
• A phone number must carry its country code. Without one the number is ambiguous, so it is dropped rather than guessed at.
• Held in memory only: re-set it after sign-in on each page load, and call setUserData(null) on sign-out.
• Each call replaces the whole object; there is no merging.
• Each invalid field is dropped with a console warning; valid fields are kept.
• The server discards user data entirely on requests flagged COPPA or TFUA, and on any request where GDPR applies.

<EloAd sdk={sdk} ad={ad} className? style? sponsoredLabel? />

React component that renders an AdCreative and handles render + impression tracking. Accepts an optional className and inline style. The card leads with an "Ad" disclosure (Ad • Headline); pass sponsoredLabel to localize it for non-English surfaces. An ad image that fails to load is hidden instead of showing a broken tile — for that ad only, so the same creative gets another chance the next time it serves.

A single link wraps the whole card, so every part of it clicks through and there are no dead zones between the image, the text and the trailing slot. What sits in that trailing slot follows the creative: a filled capsule carrying the cta_text when the ad has one, a chevron when it doesn't. The capsule is decoration inside the card link, not a link of its own. Demand sources set the label, and most don't send one — treat both as normal.

sdk.trackRender(ad) / sdk.trackImpression(ad)

Only needed if you render the ad yourself instead of using <EloAd>. Call trackRender when the ad is displayed and trackImpression once it has been ≥50% visible for one continuous second.

Both are safe to call on every render pass: the SDK sends at most one render and one impression per ad opportunity, and the limit sits behind these methods rather than inside <EloAd>, so every path into tracking is covered. A repeat serve of the same creative is a new opportunity and reports again. Each resolves true only when the ad server confirmed the ping; a failed ping releases the limit so the next call retries rather than dropping the event. Neither rejects.

sdk.hasTrackedImpression(ad) reports whether an opportunity's impression is already spoken for — delivered, or in flight — so a custom layout can skip arming its own dwell timer. It goes back to false if the ping failed, since that one is retried.

Tracking before init() is refused with a console warning and does not spend the opportunity's one render or impression, so the real ping can still follow. Mirrors Elo.trackRender / Elo.trackImpression on iOS and Android.

Clicks have no counterpart here: the card's click is a browser navigation straight to the ad server, so the SDK never sends or observes a click ping.

sdk.getTrackingTotals()

Cumulative render and impression counts since the last init() — { attempted, delivered, failed, inFlight } for each. failed is the one worth watching: it sizes how many pings the ad server never confirmed, which an event log of the last few pings can't tell you. Mirrors trackingTotals in the mobile SDKs' diagnostics snapshot.

sdk.getTrackingTotals().impression
// { attempted: 12, delivered: 11, failed: 1, inFlight: 0 }

Calling init() again starts a new session and clears these counts along with the per-opportunity tracking state, so an ad shown under the new session is never suppressed by the old one.

Styling

The card exposes stable class hooks you can target:

• .elo-ad — the card container
• .elo-ad-image — the creative image
• .elo-ad-title — the title text
• .elo-ad-description — the description text
• .elo-ad-sponsored — the "Ad" disclosure label
• .elo-ad-cta — the CTA button, when the ad carries one
• .elo-ad-chevron — the trailing chevron, shown only when there is no CTA button

Privacy

The SDK reads IAB consent signals (TCF, GPP) from localStorage and forwards them with each ad request; enforcement happens server-side. You can also pass coppa / tfua flags via EloConfig. See the Elo docs for details.

Example app & E2E

example/ is a minimal React chat app that integrates the SDK against the local source and doubles as the Autosana E2E harness. Its Diagnostics panel is the observation surface for the code-managed flows in .autosana/web-e2e/, which prove render/impression/click delivery server-side via ClickHouse. See the example README.

License

Apache-2.0 © 2026 Adapt Research, Inc. See LICENSE and NOTICE.