Quickstart

This guide fetches an approved ad and tracks it. It assumes a publisher has already set up tiers and approved at least one ad. If you are the publisher setting things up, start with the Publisher quickstart.

Get your workspace ID

Copy your workspace ID from the dashboard Install page or Settings → General. The serving API is scoped by this ID, and it is safe to ship in client-side code.

Install the SDK

npm install @revinel/sdk

Building with React? Install @revinel/react instead for hooks with built-in tracking.

Fetch an ad

import { createRevinelClient } from "@revinel/sdk"

const revinel = createRevinelClient({ workspaceId: "your-workspace-id" })

const ad = await revinel.getAd()

getAd resolves to an ad or null when nothing is eligible. An empty result is normal, so always handle it.

Render it

An ad gives you a name, a websiteUrl (the click destination), and your custom fields under meta. Draw it however your design calls for.

if (ad) {
  const link = document.createElement("a")
  link.href = ad.websiteUrl
  link.textContent = ad.name
  document.querySelector("#revinel-slot")?.append(link)
}

Track impressions and clicks

Record an impression when the ad becomes visible, and a click when someone follows it. Both are fire-and-forget.

if (ad) {
  await revinel.recordImpression(ad.id)
  // and on click:
  await revinel.recordClick(ad.id)
}

With React

@revinel/react wraps all of the above in hooks. useTracking wires a viewable-impression observer and click handler for you:

import { RevinelProvider, useAd, useTracking } from "@revinel/react"

const AdSlot = () => {
  const { data: ad } = useAd({ weight: { gte: 2.5 } })
  const { impressionRef, getClickProps } = useTracking(ad?.id)

  if (!ad) return null

  return (
    <a ref={impressionRef} href={ad.websiteUrl} {...getClickProps()}>
      {ad.name}
    </a>
  )
}

export const Ads = () => (
  <RevinelProvider workspaceId="your-workspace-id">
    <AdSlot />
  </RevinelProvider>
)

What’s next

Serving ads for weighted rotation, placement with weight, and deduping a grid with excludeIds.
Custom fields and the @revinel/sdk typed meta section to render banners, taglines, and more.
Troubleshooting if an ad does not appear.

Revinel API

Guides

SDKs

API endpoints

With React

What’s next

​With React

​What’s next

With React

What’s next