@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 natively in the format the server chose for your slot, 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. It also sends one HEAD request to {backendUrl}/v1/health, with no data, so the first ad request reuses an open connection.

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

interface FetchAdsParams {
  messages: {
    role: 'user' | 'assistant' | 'summary'
    content: string
    id?: string // your id for the turn, the same on every request
    createdAt?: Date | string // when the turn happened; a string needs a time zone
  }[]
  context?: { type: string; description: string }[]
  maxHeight?: number // CSS px the slot can give the ad; unset is unbounded
  maxWidth?: number // CSS px; unset is unbounded
}

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.

Give each message an id and createdAt when the turn happens, and send the same values every time the turn is sent again. They tell Elo when each turn happened, and the id connects the turn to Search API calls that send it as X-Elo-Message-Id. For a summary message, use the id and time of the turn it summarizes, even when the summary is written later. Without createdAt, Elo records when it received the message, which is later than the turn. An id or createdAt the SDK can't use is left out with a console warning; the request still goes out.

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

maxHeight and maxWidth describe the space your slot has, and the server chooses the format that fits: the card needs 192px, the strip 72px, and a shorter slot gets no ad. The card takes the height its copy needs inside that slot, as on iOS and Android. Leave them unset for a slot in the chat transcript, which gets the card. The ad arrives with the choice as ad.presentation, and <EloAd> renders it. You never pick the format yourself. The same maxHeight / maxWidth parameters exist on iOS and Android.

// A slot above the composer: the server sends the strip.
const res = await sdk.fetchAds({ messages, maxHeight: 72 })

ad.presentation holds the format and the publisher's render settings for it, which Elo sets per publisher and format:

interface AdPresentation {
  format: 'strip' | 'card' // always set by fetchAds
  cta_enabled?: boolean // false hides the CTA button; default true
  cta_variant?: 'control' | 'icon' | 'icon_bounce' | 'icon_shimmer' // default 'control'
  tap_surface?: 'cta' | 'full' // with a CTA: the button alone or the whole ad; default 'cta' on the strip, 'full' on the card
  tap_inset?: number // where the ad itself is the link: px of inert band at each edge, up to the format's padding; default 0
}

A layout you render yourself should honour cta_enabled. Unknown values from a newer server read as the defaults.

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 in the format it names and handles render + impression tracking. Accepts an optional className and inline style. The card shows the "Ad" disclosure on its own line under the title, and the strip leads its title line with it (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.

What sits in the trailing slot follows the creative: a filled capsule carrying the cta_text when the ad has one, a chevron when it doesn't, or when the publisher's cta_enabled is false. Demand sources set the label, and most don't send one. Treat both as normal.

• Card (ad.presentation.format is card, or absent): set like a feed ad, as on iOS and Android. A header row holds a 36px image beside the title, with the "Ad" disclosure under the title; the description follows at full width on up to three lines; and the CTA capsule sits on a 44px row of its own at the trailing edge, or a chevron closes the header row. The card takes the height its copy needs, for an unbounded slot or one at least 192px tall. By default a single link wraps the whole card, so every part of it clicks through and the CTA capsule is decoration inside that link.
• Strip (strip): one 72px row for a slot beside the composer, with a 40px image and a one-line headline and description. With a CTA, the button is the strip's only link, grown to a 44px target, and the rest of the strip opens nothing: a click near the composer that misses the button is not an ad click. Without a CTA the strip is itself the link, less the presentation.tap_inset band at its edges.

With a CTA, the publisher's presentation.tap_surface swaps either default: cta makes the button the only link on the card too, and full makes the whole strip the link with the pill as decoration. Wherever the ad itself is the link, tap_inset takes a band off each edge, up to the format's padding (12px on the card, 14px on the strip).

The CTA's cta_variant adds an arrow after the label (icon), and for icon_bounce / icon_shimmer a short pop or shimmer once the ad has been at least half visible for one second, repeated every few seconds while it stays in view. There is no motion when the reader prefers reduced motion.

Every click inside the ad is reported to Elo's analytics endpoint through sdk.trackTap, including which part it hit and whether it opened the destination. A middle click on the link opens the ad in a new tab and is reported like any other click. A click within one second of opening an ad opens nothing, so a double click opens one tab and counts one click; it is reported with opened: false.

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.trackTap(ad, tap)

Only needed if you render the ad yourself instead of using <EloAd>, which reports taps for you. It records where inside the card a click landed — the region under the pointer, the position as a fraction of the card's own size, the card's size, whether the click opened the destination, the time since the impression, and a per-showing index — so the tap heatmap and the missed-CTA rate are measurable.

sdk.trackTap(ad, {
  region: 'cta', // thumbnail | headline | description | cta | chevron | chrome
  x: 0.82, // 0..1 across the card, 0 is the left edge
  y: 0.5, // 0..1 down the card, 0 is the top edge
  width: 320, // the card's size in CSS pixels
  height: 88,
  opened: true, // false for a click on an inert part of your layout
})

• Coordinates are relative to the card, never the page or the screen.
• A tap with opened: true also sends the ad's click notices, so a layout reporting taps doesn't also need sdk.trackClick(ad).
• Every click is one event, with no dedup and no limit per showing.
• Only ads fetched through fetchAds can be reported: the ad server joins the event to the ad opportunity.
• Analytics, never billing. A network failure is retried twice, waiting longer each time; an event the ad server rejected is not retried.
• Mirrors the tap reporting EloAdView does on iOS and Android.

sdk.setDebugObserver(observer, { capturePayloads? })

Receive each debug event as it happens, for in-app diagnostics during development. The SDK keeps no history or counts of its own; a page that wants a recent-loads list or tracking totals records the events itself. Pass null to stop. An observer that throws is ignored. Mirrors Elo.setDebugObserver on iOS and Android.

const totals = { delivered: 0, failed: 0 }
sdk.setDebugObserver((event) => {
  if (event.type === 'tracking_completed' && event.event === 'impression') {
    if (event.outcome.kind === 'delivered') totals.delivered += 1
    else totals.failed += 1
  }
})

| Event | When | | --- | --- | | initialized | init() finished, with its status. Earlier events belong to the previous session. | | ad_operation | A fetchAds call finished: outcome (loaded, no_fill, error), latency, message and context counts, the maxHeight / maxWidth sent, and the format, ctaEnabled, ctaVariant, tapInset and tapSurface received. | | tracking_attempted / tracking_completed | A render, impression, click or tap started, and how it resolved (delivered, failed, or unobservable for a click, which is a browser navigation). The two share an operationId. | | request_payload_captured / response_payload_captured | With capturePayloads: true only: the ad request body and the ad response. |

capturePayloads also fills a tap's payloadJSON with the body it posts. It is off by default: message content and context descriptions are removed from the request body, but it keeps consent strings and any user data set with setUserData, including the plain email address and phone number. Use it in development only, and don't send the events anywhere.

Styling

The card exposes stable class hooks you can target:

• .elo-ad — the ad container, with .elo-ad-card or .elo-ad-strip for its format
• .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-cta-target — the link around the CTA button, where the button is the ad's only link
• .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.