Integrate yeld

Overview

yeld is an ad network for free software. Each unit requests one ad on page load, renders it natively as a sponsored card, and routes the click through yeld for attribution. On no fill it renders nothing at all.

Advertisers submit text and an optional logo — never markup, never scripts. yeld owns rendering end to end, which is why there is no third-party JavaScript in your bundle, no layout surprise, and nothing for you to sanitize.

Quick start

Five steps. Everything below assumes React; for anything else, skip to the HTTP API.

NEXT_PUBLIC_YELD_BASE_URL=https://yeld.dev

import { YeldAd } from "@yeld/react";

<YeldAd
  appId="app_k3j9x2m1p4q8"
  placement="sidebar"
/>

<YeldAd /> props

appId is the only required prop. Every other prop has a working default.

Placement rules

These are requirements, not suggestions. An integration that breaks them is not a valid integration, and apps that break them can be suspended. yeld runs in standard slots, the same way display advertising runs on the web.

Place a unit on every primary screen of the app — one per screen, never more. A typical app ends up with two to four units. A single unit at the bottom of one page is an incomplete integration.

1. 01sidebar

   A card in a persistent sidebar or rail that is present across the app. The highest-value slot there is, because one unit here covers every screen.

   <YeldAd
     appId="app_k3j9x2m1p4q8"
     placement="sidebar"
   />

2. 02post-action

   Directly beside or below the result the user just produced — a generated output, a finished export, a completed search. The highest-intent moment in the app. This slot is additive: it does not replace a persistent slot, and the unit still renders on load. The action is passed as context.event, never used as a trigger.

   <YeldAd
     appId="app_k3j9x2m1p4q8"
     placement="post-action"
     variant="post-success"
     context={{ event: "generation_complete" }}
   />

3. 03in-content

   Inline in the main content column, after the first meaningful block of content — not at the end of the page.

   <YeldAd
     appId="app_k3j9x2m1p4q8"
     placement="in-content"
   />

4. 04bottom-banner

   Full-width below the main content. A fallback only, for screens where none of the slots above exist. Never the whole integration.

   <YeldAd
     appId="app_k3j9x2m1p4q8"
     placement="bottom-banner"
     variant="compact"
   />

Native integration

The unit should look like it was designed by whoever built the app. Read your own design tokens — the Tailwind config, your CSS variables, an existing Card or Panel component — and make the unit match them. This is not decoration: a unit that reads as part of the product gets looked at, and a bolted-on banner does not.

<YeldAd
  appId="app_k3j9x2m1p4q8"
  placement="sidebar"
  appearance="plain"
/>

<YeldAd
  appId="app_k3j9x2m1p4q8"
  placement="sidebar"
  appearance="plain"
  style={{
    "--yeld-accent": "#4f46e5",
    "--yeld-radius": "8px",
    "--yeld-border": "var(--app-border)",
  } as React.CSSProperties}
/>

Optimize for conversion

Relevance is what makes a placement worth anything. yeld is paid on clicks and so are you, so the difference between a matched ad and a generic one is the difference between a slot that earns and a slot that does not.

<YeldAd
  appId="app_k3j9x2m1p4q8"
  placement="in-content"
  context={{
    page: "editor",
    event: "export_finished",
    keywords: ["svg", "icons", "design"]
  }}
/>

HTTP API

For non-React integrations. The app ID is public and there is no authentication on ad requests — the origin check does the gating.

Content-Type: application/json

{
  "appId": "app_k3j9x2m1p4q8",
  "placement": "bottom-banner",
  "context": { "page": "home" },
  "sessionId": "anon-id"
}

{
  "fill": true,
  "impressionId": "imp_ivf3k118724gfgph",
  "ad": {
    "headline": "Know when your app goes down",
    "body": "Uptime checks every 30 seconds.",
    "cta": "Start monitoring",
    "imageUrl": null,
    "logoUrl": null,
    "advertiser": "Watchtower",
    "clickUrl": "https://yeld.dev/api/v1/click/imp_ivf3k118724gfgph"
  }
}

{ "fill": false }

302 Found
Location: https://advertiser.example/landing
Cache-Control: no-store

Custom integrations

If you render the unit yourself — Vue, Svelte, plain HTML, a native app, a CLI — you take on the disclosure requirements the React SDK handles for you. All of them are mandatory.

• Show the advertiser name and a visible "Sponsored" label.
• Show "Ads by yeld" attribution.
• Render the creative text exactly as returned. Do not rewrite, truncate into nonsense, translate, or append to it.
• Send the click through ad.clickUrl, opened with rel="noopener sponsored".
• Style the unit to match the host app — that is encouraged — but keep the disclosure visible.
• Follow the placement, native, and conversion rules identically: one unit per screen across every primary screen, requested on page load, never event-gated, never in a footer.

Everything in Placement rules, Native integration, and Optimize for conversion applies identically to custom integrations: one unit per screen across every primary screen, requested on page load, never event-gated, never in a footer. There is no separate, looser standard for hand-rolled units. Styling the unit to match your app is encouraged — you own the markup, so match your own type, radius, and accent — but the "Sponsored" label and the "Ads by yeld" attribution stay visible.

Test mode

A test-mode app behaves exactly like a live one — real matching, real creatives, real no-fill responses — but every row it produces is flagged and excluded from analytics, earnings, and campaign budget accounting. Nothing you do in test mode charges an advertiser or credits a publisher.

<YeldAd appId="app_test_sandbox" placement="sidebar" />

app_test_sandbox is the seeded sandbox app. Use it to exercise rendering, the no-fill path, and the network round-trip before your own app exists. Because test-mode apps skip the origin check, it also works from any local or preview host.

Any app can be flagged as test mode on its app record — ask yeld to flip yours while you are wiring things up. Excluded from all reporting: impressions, clicks, ledger entries, publisher earnings, advertiser spend, and campaign budget consumption. Swap in your real app ID before you ship.

Economics

Cost per click, and nothing else. Impressions are free: the advertiser is charged their campaign's CPC bid only when a valid click is recorded. Of that amount the publisher takes 70% and yeld takes 30%.

The ledger entry is written in the same database transaction as the click, so a recorded click and its money always agree. Unique constraints on the click and the ledger entry make double-billing impossible even under concurrent requests. Campaigns stop serving once total budget is spent, and once daily budget is spent for the day.

Publisher details covers payouts and reporting; advertiser details covers bids, budgets, and creative review.

Privacy

Contextual only. There is no behavioral profile to build, which is why there is nothing for your users to opt out of.

• Matching is contextual: your app's registered category plus any context you pass. No user profile is involved.
• No device or browser fingerprinting.
• No third-party cookies.
• No cross-site or cross-app behavioral profiles.
• No reading of your users' content, your page contents, or the DOM around the unit.
• No advertiser scripts or advertiser markup — yeld controls rendering, so nothing third-party enters your bundle.
• One anonymous session ID in localStorage, used only for duplicate and frequency detection.

Full detail in the privacy policy. You remain responsible for whatever notices your own users require.