Quickstart

Your first ad

Keep your login, model and interface. wavebird handles ad placement, consent synchronization and rendering. Start with your saved Dashboard project and connect its generated files to your app.

This guide uses Next.js App Router with JavaScript or TypeScript, an authenticated app and durable database storage. For Python, another framework or direct REST, choose your integration path first.

Choose your integration path
  1. 01 Set up your app

    • Create an account, confirm your email and save your app in Dashboard. Choose its formats, timing, consent mode and TypeScript or JavaScript. Setup selects the current released package. Existing integrations keep their saved version.
    • Verify your domain before receiving API keys. Download the HTTPS proof file and upload it to the exact public URL on your website, then select Verify. DNS TXT is an alternative. One method is enough; proofs expire after seven days. Close the dialog to continue later through Verify domain in the header. Existing projects do not need a new proof for their unchanged domain.
    • Then save the full HTTPS app URL and its approved origin: scheme, host and optional port, without a path. www and non-www are separate hosts and need their own proof.

    Check: Overview shows your saved app and the matching integration guide.

  2. 02 Install the matching package

    • JavaScript and TypeScript use @wavebirdai/api 0.1.0-beta.19. Run the command beside your app's package.json. Keep the same version selected in Overview.
    • Copy the project-specific files from Overview. The short examples below explain their connection points, not complete standalone files. Existing integrations stay pinned until you choose and verify an upgrade.
    • The source ZIP contains no secrets. Download Server ENV separately. If the generator reports an existing file, keep it and merge the connection hooks from Overview into your app; do not overwrite your model or login code.
    terminal
    npm install @wavebirdai/api@0.1.0-beta.19

    Check: The installed package and Dashboard guide have the same version.

  3. 03 Set server ENV

    • After domain verification, complete API key setup for this project. A Browser Publishable Key is not required for this server integration. In Overview, use Server ENV to reveal the key and download the completed file. API Keys also offers Download complete Server ENV. The key-only download does not include your preference secret or origins.
    • Store the file on your server and restart the app after changes. Keep keys and the Preference Secret out of browser bundles, repositories and AI chats. Retain the Preference Secret across deployments.
    • For local development, add only the exact loopback origin you open to server ENV, including its port. localhost and 127.0.0.1 are different. Keep the saved public app URL and verified origins unchanged.
    .env.local
    WAVEBIRD_API_BASE_URL=https://api.wavebird.aiWAVEBIRD_CLIENT_ID=wbproj_replace_with_saved_project_idWAVEBIRD_SECRET_KEY=sk_test_replace_with_saved_server_keyWAVEBIRD_PREFERENCE_SECRET=replace_with_saved_preference_secretWAVEBIRD_PUBLIC_ORIGINS=https://replace-with-your-registered-origin

    Check: Your backend has this project's values. No secret is exposed to the browser.

  4. 04 Connect your backend

    • Copy the complete backend file from Overview to its named path. Install server-only for the Next.js backend import. Connect authorizePublisherRequest and sessionIdForRequest to your existing validated server session. Do not return true for every request or use a cookie/token as the session identifier.
    • Connect publisherTurnStorage to durable, atomic storage. The package includes createPostgresTurnStorage for an existing PostgreSQL pool. Install its table through your normal migration process. Do not replace the store with an in-memory map.
    • Connect existingGeneration to your model stream, retaining authentication, input validation and cancellation. Unconnected hooks intentionally reject requests. Ad failures must not prevent an authorized model response.
    app/api/wavebird/[...action]/route.js
    async function authorizePublisherRequest(request) {  void request;  return false;} async function sessionIdForRequest(request) {  // Connect the validated app session; never return a cookie or token.  void request;  return null;} async function existingGeneration(_signal) {  throw new Error("Connect your existing authenticated generation stream");}

    Check: Authorized app requests use the existing model and a session-bound turn store.

  5. 05 Connect the result area

    • Copy the matching WavebirdPlacement component from Overview. Mount it beside the result, clear of the input and scrolling transcript. Supply the real app user and conversation identifiers.
    • Place the component in your layout and set positionHint to above, below, sidebar or between in the server configuration. The saved position is the default when omitted. Moving the component does not grant additional formats, timing or sizes.
    • Connect ads.connectGeneration to your existing request, response consumer and abort signal. Call onDelta as output arrives. Call onPresented when the result is visible, or resolve the consumer only after presentation. After timing waits for both generation completion and presentation.
    • Keep the slot within the available width. The package selects a supported size that fits. Dispose on unmount and rebind on session or conversation changes. Never delay model output for consent, an ad response or Clip playback.
    • If your app uses Content Security Policy, allow https://api.wavebird.ai for the renderer in script-src, frame-src and connect-src. Merge these sources into your existing policy, preserving nonces and other protections. Do not use wildcards or disable CSP.
    your existing result component.jsx
    import { WavebirdPlacement } from "@/components/WavebirdPlacement"; export function AdBesideResult({ projectId, userId, conversationId, onAdsReady }) {  return <WavebirdPlacement clientId={projectId} userId={userId} conversationId={conversationId} onReady={onAdsReady} />;} export function connectExistingGeneration(ads, send, consume, signal) {  return ads.connectGeneration({    request: headers => send(headers, signal),    consume: (response, { onDelta, onPresented }) => consume(response, onDelta, onPresented ?? (() => {})),    signal  });}

    Check: Your app streams normally and the ad follows the saved timing and turn.

  6. 07 Verify the integration

    • With your Server Test Key, make a normal consent choice and generate a result. Check the visible creative and its matching entry in Test Logs. A successful placement response alone does not prove display.
    • Check decline, withdrawal, No-Fill, Stop, a new turn and a narrow screen. A short During generation may finish before an ad can appear. For Clip, also check playback, natural completion and cleanup.
    • For an empty slot, identify whether the failure is in app authentication, consent, placement, renderer loading or the hosted frame. Record status/error categories and relative timings, not signed URLs, cookies, headers or a HAR. Do not disable browser protections.
    • A frame error alone does not prove a CSP block. Check the browser's policy violation message and your CSP before changing it. Frequency limits apply to the supplied session; a configured daily limit does not establish a person across sessions.
    • frequency_cap_exceeded means a configured limit was reached. In Test responses, decision.metadata.frequency identifies the policy and limit; reset_at is null when no reliable reset time is available. frequency_session_required needs a valid session. frequency_service_unavailable, frequency_context_unavailable and frequency_configuration_invalid are technical failures, not evidence that the user saw too many ads.

    Check: Your integration handles successful delivery and empty/error outcomes. Test traffic is nonpayable.

  7. 08 Prepare Live delivery

    • Complete the Live requirements shown for your project, including company, privacy and payout information where requested. Publisher payout details receive earnings; they are not an advertiser budget payment.
    • Request Live access through Dashboard when eligible. Use Live credentials only after approval. Installing a package, passing a test or saving payout details alone does not activate paid traffic.

    Check: Dashboard confirms the remaining requirements or approved Live access.

Common integration questions →

Need help with your integration?

Share the affected endpoint, request ID, and the behavior you expected. Leave out keys and user content.

Contact the team