@kasabeh/a3d-sdk

Native 3D advertising SDK for Three.js / React Three Fiber.

Add native 3D ads to your Three.js or React Three Fiber scene in under 5 minutes. The SDK runs an OpenRTB 2.6 auction (ext.threeds), loads the winning GLB creative, bills the impression via a single-use token when the model actually renders, and tracks viewability aligned with the IAB/MRC Intrinsic In-Game (IIG) 2.0 guidelines.

Install

npm install @kasabeh/a3d-sdk three @react-three/fiber @react-three/drei

Quick start (React Three Fiber)

import { Canvas } from '@react-three/fiber'
import { A3DAds } from '@kasabeh/a3d-sdk'

function App() {
  return (
    <Canvas>
      <MyScene />
      <A3DAds
        siteId="your-site-id"
        endpoint="https://api.a3d.io"
        placements={[
          {
            id: 'hero-product',
            position: [0, 1, 0],
            sceneType: 'showroom',
            surfaceType: 'pedestal',
            maxDimensions: { width: 0.5, height: 1.0, depth: 0.5 },
          },
        ]}
      />
    </Canvas>
  )
}

Manual control (hook)

import {
  useA3DAds, A3DModel, A3DSponsoredTag, A3DViewability, openAdClick,
} from '@kasabeh/a3d-sdk'

function MyAdSlot({ placement }) {
  const { resolvedAd, loading, modelUrl } = useA3DAds(placement, undefined, {
    endpoint: 'https://api.a3d.io',
    fallbackModelUrl: '/my-house-ad.glb',
  })
  if (loading || !modelUrl) return null
  return (
    <group position={placement.position}>
      <A3DModel
        url={modelUrl}
        ad={resolvedAd}
        onClick={resolvedAd ? () => openAdClick(resolvedAd) : undefined}
      />
      <A3DViewability placement={placement} ad={resolvedAd} />
      <A3DSponsoredTag offset={0.5} />
    </group>
  )
}

Vanilla JS (no React)

import { A3DClient } from '@kasabeh/a3d-sdk'

const a3d = new A3DClient({ siteId: 'your-site-id', endpoint: 'https://api.a3d.io' })
const ads = await a3d.requestBids(placements)
for (const [placementId, ad] of ads) {
  const model = await a3d.loadModel(ad.modelUrl)
  scene.add(model)
  a3d.fireImpression(placementId, ad)
}

Exports

| Export | Kind | Description | |---|---|---| | <A3DAds /> | component | Drop-in: bid, load, render, sponsored tag, billing + IIG viewability | | useA3DAds(placement, site?, opts?) | hook | Auction for one placement; returns { resolvedAd, loading, modelUrl, refetch } | | <A3DModel /> | component | Load + auto-fit a GLB; bills on render when given ad | | <A3DSponsoredTag /> | component | Billboarded "Sponsored" badge | | <A3DViewability /> | component | IIG viewability + engagement tracker | | openAdClick(ad) | function | Tracked click through the ad server redirect | | fireBillableImpression(ad, endpoint?) | function | Manually bill a rendered creative | | fireEvent(payload) | function | Record a custom event (rotate, zoom, hover) | | A3DClient | class | Imperative client for plain Three.js |

Placement shape

{
  id: string
  position: [number, number, number]
  sceneType: string          // kitchen | office | gallery | showroom | ...
  surfaceType: string        // table | shelf | pedestal | floor | ...
  maxDimensions: { width: number; height: number; depth: number } // meters
  tags?: string[]
  interaction?: string[]     // view | rotate | zoom | hover | pickup
  placementType?: 'static' | 'floating' | 'interactive'
  bidfloor?: number          // minimum CPM in USD
}

Peer dependencies

The SDK does not bundle these — your scene already has them:

• react >= 18
• react-dom >= 18
• three >= 0.160
• @react-three/fiber >= 8
• @react-three/drei >= 9

License

MIT