Developer Documentation

Everything you need to create ad templates, integrate Rollaway Ads into your site, and interact with the JavaScript API.

Ad Template JSON Schema

Every ad sheet is defined by a single JSON object. The canonical feed lives at /ads.json.

Template fields

FieldTypeRequiredDescription
brandstringYesBrand name shown at the top of the sheet
accentstring (hex)YesPrimary accent colour, e.g. #b8541f
headlinestringYesMain headline (use \n for line breaks)
subheadstringYesSupporting tagline below the headline
bulletsstring[]YesArray of 3-5 selling points
ctastringYesCall-to-action text (e.g. ORDER NOW → example.com)
footerstringNoSmall-print promotional text
heroImagestring (URL)NoBrand logo or hero image URL
bgstring (hex)NoBackground colour override (default: #faf6eb)

Example

{
  "brand": "NEXA COFFEE",
  "accent": "#b8541f",
  "headline": "YOUR MORNING\nDESERVES BETTER",
  "subhead": "Freshly roasted. Shipped within 24 hrs.",
  "bullets": [
    "12 oz bags from $14",
    "Subscribe & save 20%",
    "Roasted the same day it ships",
    "Ethically sourced, direct trade"
  ],
  "cta": "ORDER NOW → nexa.coffee",
  "footer": "Use code RECEIPT10 for 10% off",
  "heroImage": "https://example.com/logo.png"
}

JavaScript API

The Rollaway Ads engine runs entirely client-side. There is no SDK to install — the single index.html file includes the full WebGL cloth-physics engine, ad renderer, and Supabase connector.

Key globals

VariableDescription
activeSheetThe currently displayed sheet object
freeSheetsArray of released (falling) sheets
AD_TEMPLATESBuilt-in fallback ad templates (26 entries)
LIVE_POOLLive ads fetched from Supabase
RWSupabase client instance (null if offline)

Sheet lifecycle

  1. createSheet({ pinned: true, collapseFromSlit: true }) — Creates a new sheet with cloth physics and ad texture
  2. User pulls the sheet down past the release threshold
  3. forceRelease() fires — sheet becomes free-falling, ad budget is debited via Supabase RPC
  4. A new sheet is automatically created at the dispenser

Ad delivery priority

  1. Live ads from Supabase (LIVE_POOL) — preferred if the user isn't pulling too fast
  2. Hardcoded fallback templates (AD_TEMPLATES) — used during rate limiting or when Supabase is unavailable

Embed Instructions

To add Rollaway Ads to your own site:

Option 1: Full-page embed

<iframe
  src="https://rollawayads.com"
  width="100%"
  height="100vh"
  style="border:none; position:fixed; inset:0; z-index:9999;"
  allow="accelerometer; gyroscope"
></iframe>

Option 2: Self-hosted

  1. Clone the repository
  2. Replace Supabase credentials in index.html with your own project
  3. Customise AD_TEMPLATES and /ads.json with your brand templates
  4. Deploy to any static host (Cloudflare Pages, Vercel, Netlify, etc.)

Required files

FilePurpose
index.htmlFull application (WebGL, physics, UI, Supabase)
solver.wasmWASM physics solver (6 KB, optional — JS fallback exists)
solver-worker.jsWeb Worker for off-thread physics (optional)
ads.jsonDefault ad template catalogue
public/Fallback ad images

Physics Architecture

The cloth simulation uses Verlet integration with distance constraints, solved iteratively each frame.