---
title: Banners
description: HTML overlays for apps and CMS sites — modal, fullscreen, inline.
---

# Banners

HTML banners (in-app / site overlays) for promos, plans, and CTAs. Closer to Braze/OneSignal HTML In-App Messages than to RevenueCat Paywalls.

## Admin

- **Application** → **Banners**
- **CMS site** → **Banners**

Create with a stable `code`, HTML, placement and size → **Preview** → set status to `published`.

| Field | Values |
|-------|--------|
| `placement` | `modal` (blur + close), `fullscreen`, `inline` |
| `size_preset` | `auto`, `9:16`, `16:9`, `4:3`, `square` |
| `status` | `draft` / `published` / `archived` (public API returns published only) |

Use normal `<a href="…">` links in HTML. Images need absolute URLs from Public assets.

## SDK

### Application

```ts
import { createRaidBossClient } from "@raidboss/platform-sdk";

const platform = createRaidBossClient({
  apiUrl: "YOUR_API_URL",
  applicationCode: "YOUR_APP_CODE",
  publicKey: "YOUR_PUBLIC_KEY",
});

const { data: banner } = await platform.getBanner("welcome_promo");
// banner.html_body, placement, size_preset, backdrop_blur, show_close

const { data: list } = await platform.listBanners({ placement: "modal" });
```

Flutter: `getBanner`, `listBanners`.

### CMS site

```ts
const { data } = await platform.getSiteBanner("YOUR_SITE_CODE", "home_promo");
const { data: all } = await platform.listSiteBanners("YOUR_SITE_CODE");
```

## Client presentation

The platform returns HTML + metadata — it does **not** render the overlay. Your app/site:

1. Call `getBanner(code)` when needed.
2. Render WebView / iframe overlay.
3. For `modal` — dimmed/blur backdrop and close control if `show_close`.
4. For `fullscreen` — fill the screen; use `size_preset` for aspect.
5. Analytics: `trackEvent("banner_shown" | "banner_cta", { banner_code })`.

## API

| Method | Path |
|--------|------|
| GET | `/v1/applications/{code}/banners` |
| GET | `/v1/applications/{code}/banners/{bannerCode}` |
| GET | `/v1/sites/{siteCode}/banners` |
| GET | `/v1/sites/{siteCode}/banners/{bannerCode}` |

Requires `X-Public-Key`. Admin CRUD: `/v1/banners/owners/{application\|cms_site}/{key}`.