Integration

Wire AdsRoster into your site.

AdsRoster owns booking links, clicks, and impressions. You own layout and styling. There are two ways to integrate: an LLM prompt from your placement, or a manual SDK setup.

Two ways to integrate

Use an LLM with a prompt from your placement, or install and wire the SDK yourself.

In the workspace, open a website → Placements (or the site Integration page) and click Get integration. The modal’s LLM prompt tab gives you a prompt already filled with that placement’s public key, placement slug, and rendering rules.

Copy the prompt and paste it into Cursor, Codex, or another coding agent in your website repo.
The agent installs adsroster, sets NEXT_PUBLIC_ADSROSTER_PUBLIC_KEY in env, wraps with AdsRosterProvider (no baseUrl; production is the package default), and renders spots in your UI.
Prefer this over sample keys in these docs. Never commit tunnel / localhost hosts or hardcoded keys in a shared config file.

Prefer wiring it yourself? Switch to the tab.

Booking by default

Most publishers send sponsors to AdsRoster hosted checkout via spot.bookingUrl. For a form that lives on your domain, see Custom checkout.

Checkout only works after Bachs is connected for that environment. See Settings & payments.

Let visitors browse ad placements

Purchase mode replaces ads with booking placeholders for the current visitor. Add ?__adsroster_mode=booking to your website URL (or &__adsroster_mode=booking if it already has a query). Use your own CTA to switch modes without reloading:

Code

"use client";
import { usePurchaseMode } from "adsroster";

export function AdvertiseButton() {
  const { purchaseMode, togglePurchaseMode } = usePurchaseMode();
  return (
    <button type="button" aria-pressed={purchaseMode} onClick={togglePurchaseMode}>
      {purchaseMode ? "Show current ads" : "Advertise here"}
    </button>
  );
}

For an existing handler, import AdsRoster and call AdsRoster.setPurchaseMode(true), AdsRoster.setPurchaseMode(false), or AdsRoster.togglePurchaseMode(). No controls are added to your page. The functions update only the AdsRoster URL parameter, preserving other parameters, the hash, and the current history entry.

With the updated SDK, AdSpace shows “Advertise here” and “Choose dates”. For custom layouts, useAdGroup and useAdSpace return purchaseMode and hide the campaign and tracking URLs while keeping the booking URL, price, and reservations. Render your usual empty-slot CTA when the campaign is null. Enabled slots show that CTA even when their normal fallback is hidden; paused slots stay hidden. No impressions are recorded in this mode, and existing campaigns keep running for other visitors.

These controls require SDK version 0.3.0 or later. Raw delivery API integrations must implement this presentation behavior themselves; the parameter is read by the SDK on your page.

Link to any spot, even while an ad is running

Copy a spot’s Payment link from your website dashboard, or use spot.bookingUrl from useAdGroup. useAdSpace also exposes bookingUrl and its alias advertiseUrl. These links work independently of purchase mode, including below an active ad or in your own sponsorship card. Checkout lets advertisers choose available future dates.

Code

// Add alongside your existing ad rendering, inside spots.map(...).
// Link directly to checkout; do not use clickUrl for this CTA.
{spot.enabled && (
  <a href={spot.bookingUrl} target="_blank" rel="noopener noreferrer">
    Advertise here — choose dates
  </a>
)}

NextSettings & paymentsConnect Bachs so bookings can create a real checkout.