flam-interactive-ads

Embed interactive Flam video ads in plain HTML or React.

Installation

npm install flam-interactive-ads

Plain HTML

Drop a script tag and use the <flam-ad> custom element. No JavaScript needed.

<script src="https://unpkg.com/flam-interactive-ads/dist/ads.js" defer></script>

<flam-ad></flam-ad>

Default behaviour (no attributes):

• The element expands to fill its parent (width: 100%; height: 100% via the SDK stylesheet).
• The ad auto-sizes from the video's native dimensions, scaled down to fit within the parent while preserving aspect ratio.
• object-fit defaults to "contain" — the ad is letterboxed inside the parent; no cropping.

All attributes are optional:

<!-- fixed size, custom class, cover fit -->
<flam-ad width="400" height="300" classname="my-ad" object-fit="cover"></flam-ad>

Attributes

| Attribute | Type | Default | Description | |---|---|---|---| | width | number | — | Display width in px. Sets style.width on the element. Omit to fill the parent width. | | height | number | — | Display height in px. Sets style.height on the element. Omit to fill the parent height. | | classname | string | — | One or more space-separated CSS classes added to the element. | | object-fit | "contain" \| "cover" | "contain" | contain fits the ad inside the container (letterboxed). cover scales the ad to fill the container completely, clipping any overflow. |

class (the standard HTML attribute) is also supported and applied natively by the browser.

React

Initialize the SDK once at your app entry, then drop <FlamAdSlot> anywhere.

// main.tsx
import { FlamAds } from 'flam-interactive-ads';
FlamAds.init();

import { FlamAdSlot } from 'flam-interactive-ads/react';

function AdBanner() {
  return (
    <FlamAdSlot
      width={400}
      height={300}
      objectFit="cover"
      onReady={({ slotId }) => console.log('ready', slotId)}
      onClick={({ url }) => console.log('clicked', url)}
      onError={({ message }) => console.error(message)}
    />
  );
}

Default behaviour (no props):

• The host <div> expands to fill its parent (width: 100%; height: 100%).
• The ad auto-sizes from the video's native dimensions, scaled down to fit within the parent.
• objectFit defaults to "contain" — letterboxed inside the container, no cropping.

Props

| Prop | Type | Default | Description | |---|---|---|---| | width | number | — | Display width in px. Omit to auto-size from the parent width. | | height | number | — | Display height in px. Omit to auto-size from the parent height. | | objectFit | "contain" \| "cover" | "contain" | contain fits the ad inside the container (letterboxed). cover scales the ad to fill the container completely, clipping any overflow. | | onReady | ({ slotId }) => void | — | Fires when the ad is visible and ready. | | onClick | ({ slotId, markerId, url }) => void | — | Fires when a clickable marker is clicked. | | onMarkerChange | ({ slotId, markerId }) => void | — | Fires when the active marker changes. | | onError | ({ slotId, message }) => void | — | Fires on initialization or playback error. | | onMute | ({ slotId, muted }) => void | — | Fires when the user toggles mute. | | className | string | — | CSS class on the host <div>. | | style | CSSProperties | — | Inline styles on the host <div>. |

Programmatic API

For full control outside of React:

import { FlamAds } from 'flam-interactive-ads';

const sdk = FlamAds.init();
const slot = sdk.createSlot({
  container: document.getElementById('ad')!,
  width: 400,
  height: 300,
  objectFit: 'cover',   // optional, defaults to 'contain'
});

slot
  .on('ready', ({ slotId }) => console.log('ready', slotId))
  .on('click', ({ url }) => console.log('clicked', url))
  .on('error', ({ message }) => console.error(message));

// Later — mute or clean up
slot.mute(true);
slot.destroy();