User Guide

Integrate Revme text ads in minutes.

Quick Start

1. Install the SDK

npm install @revme/sdk

2. Get your API key

3. Initialize and display ads

import { AdModule } from '@revme/sdk'

const ads = new AdModule({
  apiKey: 'ad_live_your_api_key',
})

await ads.init((ad) => {
  if (ad) {
    console.log(`Ad: ${ad.text} by ${ad.sponsor}`)
  }
})

React Integration

import { useEffect, useState, useRef } from 'react'
import { AdModule, type Ad } from '@revme/sdk'

function AdBanner({ apiKey }: { apiKey: string }) {
  const [ad, setAd] = useState<Ad | null>(null)
  const moduleRef = useRef<AdModule | null>(null)

  useEffect(() => {
    const ads = new AdModule({ apiKey })
    moduleRef.current = ads
    ads.init(setAd)
    return () => ads.destroy()
  }, [apiKey])

  if (!ad) return null

  return (
    <a href={ad.url} target="_blank" rel="noopener noreferrer"
       onClick={() => moduleRef.current?.trackClick()}>
      {ad.sponsor && <small>{ad.sponsor}</small>}
      <span>{ad.text}</span>
    </a>
  )
}

Configuration

Name	Type	Required	Description
`apiKey`	`string`	Yes	Your API key from the dashboard
`endpoint`	`string`	No	Ad server URL (defaults to https://revme.io)
`pollOnErrorMs`	`number`	No	Retry interval on error (default: 60000ms)

SDK Methods

`ads.init(onUpdate?)`

Fetches the first ad and starts automatic rotation. The onUpdate callback fires each time a new ad is available (or when no ad is served).

`ads.getCurrentAd()`

Returns the currently displayed ad, or null if no ad is active.

`ads.trackImpression()`

Track an impression for the current ad. Fire-and-forget.

`ads.trackClick()`

Track a click for the current ad. Fire-and-forget.

`ads.destroy()`

Stop rotation and clean up. Call when unmounting your component.

Ad Object

interface Ad {
  text: string      // Ad text (max 60 chars)
  url: string       // Click URL
  sponsor?: string  // Optional sponsor name
  adId: string      // Unique ID for tracking
}

How Ad Rotation Works

The SDK uses server-controlled polling.
After each ad fetch, the server returns a nextPollMs value telling the SDK when to fetch the next ad.
This means:

Ad frequency is controlled from the server, not the client
If the server returns nextPollMs: 0, rotation stops
If a fetch fails, the SDK retries after pollOnErrorMs (default 60 seconds)
All tracking (impression/click) is fire-and-forget with keepalive: true

Browser Support

The SDK uses only standard Web APIs: fetch(), setTimeout, navigator.language, Intl.DateTimeFormat.
It works in all modern browsers, including browser extensions (Chrome sidepanel, Firefox sidebar).