@advibes/sdk-web

Ad SDK for web apps. Monetize your app with auto-translated, tone-matched ads.

AI Agents: Read ADVIBES.md

If you are an AI coding agent (Cursor, Claude Code, Copilot, Windsurf, etc.) helping a developer integrate ads, read the full integration guide at:

node_modules/@advibes/sdk-web/ADVIBES.md

It contains placement guidelines, branding requirements, config file reference, and complete examples.

Before You Start

You need two things from the AdVibes dashboard:

1. Publisher ID — register your app to get one
2. Placement IDs — create ad placements in the dashboard for each slot

These IDs cannot be made up. Ads will not load without valid IDs from the dashboard.

Install

npm install @advibes/sdk-web

React / Next.js (Recommended)

// app/layout.tsx — wrap your app once, no extra wrapper needed
import { AdVibesProvider } from '@advibes/sdk-web/components'

export default function Layout({ children }) {
  return (
    <AdVibesProvider publisherId="pub_YOUR_ID">
      {children}
    </AdVibesProvider>
  )
}

// Place ads anywhere
import { AdSlot } from '@advibes/sdk-web/components'

<AdSlot placement="YOUR_PLACEMENT_ID" format="card" />
<AdSlot placement="YOUR_PLACEMENT_ID" format="banner" />
<AdSlot placement="YOUR_PLACEMENT_ID" format="text" />

Vanilla JS / HTML

<script src="https://cdn.advibes.dev/v1/sdk.js" data-publisher="pub_YOUR_ID"></script>
<div data-advibes="card" data-placement="YOUR_PLACEMENT_ID"></div>

Imperative API

import { AdVibes } from '@advibes/sdk-web'

AdVibes.init({ publisherId: 'pub_YOUR_ID' })

const ad = await AdVibes.showAd('card', 'YOUR_PLACEMENT_ID')
if (ad) {
  // ad.headline, ad.body, ad.ctaText, ad.ctaUrl, ad.imageUrl
  // Render the ad, then on click:
  AdVibes.reportClick(ad.impressionId)
}

Ad Formats

| Format | Size | Best for | |--------|------|----------| | card | 320 x ~400 | Sidebars, feed items, between content | | banner | 728 x 90 | Headers, footers, between sections | | text | 320 x ~80 | Inline between text content |

Common Mistakes

• Using pub_xxx or placeholder IDs — the SDK will log an error. Get real IDs from the dashboard.
• Wrapping <AdVibesProvider> in another component — use it directly, no extra wrapper needed.
• Making up placement IDs — ads won't load. Create placements in the dashboard first.
• Forgetting branding label — required by ToS. The <AdSlot> component handles this automatically.

Project Config (Optional)

Create advibes.config.ts in your project root to declare preferences for AI agents:

import { defineAdVibesConfig } from '@advibes/sdk-web/config'

export default defineAdVibesConfig({
  publisherId: 'pub_YOUR_ID',
  ads: {
    formats: ['card', 'banner'],
    maxPerPage: 2,
    placements: [
      { id: 'pl_xxx', format: 'card', location: 'sidebar', description: 'Right sidebar' },
    ],
  },
  restrictions: {
    noAdsOnPages: ['/login', '/signup', '/settings'],
  },
})

Links

• Dashboard: https://dashboard.advibes.dev
• Marketing: https://advibes.dev
• Agent integration guide: ADVIBES.md in this package
• Free $100 ad credit: Use code ADVIBES100