Skip to main content

Commerce Media SDK Guides

Surfside's commerce media SDKs let you request and render banners, videos, and product carousels from your own site or app. There are four ways to integrate, depending on your stack and how much control you want over rendering.

Headless Workflow​

Build bid requests and parse bid responses yourself while controlling your own rendering. Built on @surfside/ads-core, this workflow is framework-agnostic and works equally well in server-side and browser contexts.

React Components​

Ready-to-use components — SurfsideBanner, SurfsideVideo, SurfsideCarousel, and SurfsideDynamicZone — that request, render, and track ads automatically. Drop them into your component tree with no manual bid requests or response parsing required.

React Hooks​

Direct access to ad fetching and state management, letting you own the rendering. Use these when the built-in components don't fit your design or you need to compose ad state with other application state.

Both React workflows are provided by the @surfside/ads-react package and require React 17 or later.

Web Components​

Framework-agnostic custom elements — <surf-banner>, <surf-video>, <surf-carousel>, and <surf-dynamic-zone> — that request, render, and track ads automatically, the same way the React components do. Provided by the @surfside/ads package, loaded with a single <script> tag; no build step or JavaScript initialization required.

The rest of this section is organized by task rather than by workflow — each guide below covers the Headless, React Components, React Hooks, and Web Components approaches side by side, so you can compare them or jump straight to the one you're using.