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

The fast path is one command — no account needed. The manual path is at the end; for non-React stacks see the script embed or 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.

Start with exactly one unit, on your app's primary screen — the screen a returning user actually works in, never an onboarding flow, a login page, or a marketing page. One well-placed unit is a complete integration; a unit buried at the bottom of a page nobody reads is not.

Adding more screens is your decision, made later: npx @yeld/cli add proposes the next placements — one per screen, in the same slot priority — whenever you want them.

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 is a coverage slot, the kind npx @yeld/cli add proposes on a second screen — the unit still renders on load, and 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.

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

Native integration

The unit should look like it was designed by whoever built the app. This is not decoration: a unit that reads as part of the product gets looked at, and a bolted-on banner does not.

Most of it is automatic. At render the unit samples the nearest opaque ancestor background to derive its colors — following class-toggled dark modes and re-adopting when your app flips theme — and the nearest rounded ancestor for its corner radii. The server picks the layout format per request from the container's measured width. Typography inherits from your font stack. The overrides below exist for the cases adoption cannot see; reach for them only when something is visibly wrong.

<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",
  "containerWidth": 720
}

{
  "fill": true,
  "impressionId": "imp_ivf3k118724gfgph",
  "format": { "key": "banner", "layout": "horizontal", … },
  "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 on the 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 on the 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.