Core concepts
If this is your first time integrating an ad network, start here. Every other page in these docs assumes you know these dozen words — this page is the only one that doesn't.
You don't need to memorize this
Skim it once so the words feel familiar, then jump to the Quickstart. Every technical page links back here the first time it uses a term you might not know.Advertising questions, answered
These definitions describe advertising concepts, not a promise of ADX operating availability. Use the linked references for calculations, examples and current runtime limits.
What is an ad network?
An ad network connects publisher inventory with advertiser demand, often packaging inventory and managing delivery or commercial terms. Its aggregation role differs from an exchange auction, although one business may provide both.
How does an ad exchange work?
An ad exchange coordinates transactions between eligible sellers and buyers. In real-time bidding, buyers evaluate an opportunity, submit bids and receive a decision under the auction rules. A completed auction does not prove that the creative rendered or that an impression was valid.
What is programmatic advertising?
Programmatic advertising uses software to arrange advertising transactions and delivery. Real-time bidding is one transaction method; automated guaranteed or private arrangements may use different pricing and allocation rules.
What is the difference between CPM and CPC?
CPM expresses a cost per 1,000 impressions. CPC expresses a cost per click. For a hypothetical spend of $20, 10,000 impressions and 40 valid clicks imply a $2 CPM and a $0.50 CPC. Neither metric alone establishes profitability, viewability or publisher net earnings.
How does ad revenue sharing work?
Revenue sharing allocates an agreed revenue base among participants. If the hypothetical eligible base is $160 and a publisher share is 70%, the publisher portion is $112 before any separately applicable adjustments. Verify the base, fees, invalid-traffic adjustments, currency and settlement terms; these assumptions are not ADX commercial terms.
How do developers monetize applications with advertising?
Developers select an eligible placement and runtime, request an ad, render supported creative safely and report permitted measurement events. Revenue depends on valid delivery, demand and commercial eligibility. Server SDKs do not supply a visible surface; the host must render and measure it.
How are invalid impressions detected?
Invalid-traffic systems combine signals such as automated-client indicators, repeated activity, inconsistent event sequences and traffic-source review. No single User-Agent rule proves that traffic is valid. Backend filtering source does not establish detection accuracy; investigate false positives and reconcile excluded events before interpreting revenue.
What is an ad placement?
An ad placement is an intended location or moment for advertising, represented by a slot in the ADX contract. Its size, format and surrounding experience must fit the host application. A slot identifier is a routing input, not evidence of approval, fill or a paid impression.
For eCPM, CPM and publisher RPM formulas, read the measurement guide. For fill rate, see eligible request denominators and worked examples.
Technical references: IAB Tech Lab OpenRTB describes bidding interfaces. MRC viewability guidelines distinguish display and video measurements; their criteria are not a certification of this integration.
The three things you create
Before you can show a single ad, you set up three things once, in this order. Everything else in the docs is about the fourth step — actually asking for an ad.
| Name | Type | Required | Notes |
|---|---|---|---|
Site | string | Optional | Your website or app, registered in the adx dashboard. Think of it as your account for one property — you can have several (e.g. one Site per app). Registering a Site gives you an api_key. |
api_key | string | Optional | A public ID (looks like pk_abc123…) that says "ads shown using this key are yours, pay this account." It is not a password — it's safe to put directly in an app you ship to users, the same way every ad SDK (AdMob, AdSense, etc.) works. |
Slot | string | Optional | A single ad placement — e.g. "banner at the bottom of the homepage" or "interstitial between game levels." Think of it like a picture frame you hang on a wall: the frame's size and position never change, but a different picture (a different ad) can appear in it every time someone visits. Creating a Slot gives you a slot_id. |
slot_id | string | Optional | The ID of one specific Slot. You pass this (or a slot_name) every time you ask for an ad, so the server knows which "frame" it's filling. |
Put together: your Site owns one api_key, and inside it you create one or more Slots, each with its own slot_id. See the Quickstart for the local no-fill example and account prerequisites.
The lifecycle of one ad
Every single ad that ever appears on your site or app goes through the same four beats, in order:
| Name | Type | Required | Notes |
|---|---|---|---|
1. Request | string | Optional | Your code asks the server: "I have this slot_id — got anything to show?" This is one HTTP call. See Requesting an ad. |
2. Fill / No-fill | string | Optional | Fill means yes, here's an ad. No-fill means no — nothing to show right now (could be no advertiser demand, could be your traffic looked suspicious, could be a dozen other reasons). A no-fill is normal and expected sometimes; your app should simply show nothing. See Response shapes. |
3. Render | string | Optional | If filled, you draw the creative — the actual image or markup — on screen. This is the only step your code fully controls; the SDK gives you the pieces (image URL, click link, or sandboxed HTML) and you place them. |
4. Report | string | Optional | Once a supported display placement meets its visibility requirements, send one viewability beacon. This reports a measurement event; it does not establish valid billable delivery or settled publisher earnings. See Beacons. |
SDK responsibilities depend on the runtime. Browser and native renderers have different capabilities; server SDKs require host rendering and visibility measurement. Check the runtime matrix before integration.
Words describing one ad response
| Name | Type | Required | Notes |
|---|---|---|---|
Creative | string | Optional | The actual ad content: an image + a click link, or a small chunk of HTML markup from an advertiser. Never trust it blindly — see the security model. |
imp_id | string | Optional | "Impression ID" — a one-time receipt number for this specific ad showing. You need it to send the viewability beacon. Some ad types (house ads, no-fills) have no imp_id because they can't be tracked that way. |
Click-through | string | Optional | What happens when someone taps/clicks the ad — they get sent to the advertiser's page. The click_url the server gives you already handles the tracking; you just open it. |
Viewability | string | Optional | A measurement of an opportunity to see an ad, separate from attention or billing. Display and video requirements differ; use the applicable measurement guidelines. |
Where an ad actually comes from
A "fill" can come from three different sources — you render all three almost identically, but it's worth knowing the difference:
| Name | Type | Required | Notes |
|---|---|---|---|
Internal | string | Optional | An advertiser using theaimart directly bought this impression through an auction. A response path in the contract; live demand is not guaranteed. A paid response can have an imp_id). |
OpenRTB (external DSP) | string | Optional | A DSP (Demand-Side Platform — a company that buys ads on behalf of advertisers, e.g. a trading desk) won this impression through a real-time auction. Comes back as raw HTML markup instead of a plain image, and needs the sandboxed-rendering treatment covered in the security model. |
House ad | string | Optional | A backfill/fallback ad (often promoting your own product, or filling inventory that got no bids) when configured. A response may still be no-fill. Not trackable — no imp_id, so you skip the viewability beacon for these. |
The money side, briefly
| Name | Type | Required | Notes |
|---|---|---|---|
Auction | string | Optional | A server-side decision among eligible bids under configured rules. A request can return no-fill; eligibility, floors and demand affect the outcome. |
Second-price auction | string | Optional | An auction rule where the clearing price depends on the next eligible bid and applicable floors or increments. OpenRTB can describe first-price and second-price-plus auctions; inspect the actual transaction rather than assuming one universal rule. |
eCPM | string | Optional | "Effective Cost Per Mille" — revenue per 1,000 ad impressions. The number publishers use to compare how well a Slot is monetizing, e.g. "this banner Slot runs at ₹120 eCPM." |
paise | string | Optional | Money amounts in the API are in paise (1/100 of a rupee) as whole integers — e.g. clearing_price_paise: 120 means ₹1.20 — the same reason APIs use cents instead of dollars: no floating-point rounding bugs. |
Trust & safety words you'll see
| Name | Type | Required | Notes |
|---|---|---|---|
WAF | string | Optional | "Web Application Firewall" — a security filter in front of the server that blocks suspicious-looking requests. It's the reason every SDK encodes URLs a specific way — an ordinary URL can accidentally look like an attack to it. |
Fraud score / bot filter | string | Optional | The server silently down-ranks or rejects traffic that looks automated (scrapers, bots, headless browsers) as part of invalid-traffic handling; source-level filtering does not establish detection efficacy. See User-Agent rules — this is one possible cause of no-fill, alongside demand and account eligibility. |
Identity cookie (_an_id) | string | Optional | A visitor identifier used by backend identity and frequency-cap paths. Treat persistent identifiers as privacy-relevant data; collection, retention and use need appropriate consent and policy review. Reader rewards are not a universally available feature. |
Sandbox mode | string | Optional | A testing workflow that must be explicitly confirmed by the operator. Use the injected local mock in the Quickstart unless a sandbox with known billing and tracking behavior has been verified. |
Acronym cheat-sheet
| Name | Type | Required | Notes |
|---|---|---|---|
SSP | string | Optional | Supply-Side Platform — the seller's side of ad tech (this is what adx is, from a publisher's point of view). |
DSP | string | Optional | Demand-Side Platform — the buyer's side; a company advertisers use to bid on impressions. |
OpenRTB | string | Optional | The open industry standard protocol SSPs and DSPs use to run real-time bidding auctions between each other. |
IAB | string | Optional | Interactive Advertising Bureau — the industry body that defines standards like the viewability threshold used here. |
VAST | string | Optional | Video Ad Serving Template — a video ad response interface. A separate Web helper exists; receiving VAST does not supply a video player or establish native SDK video support. Check runtime availability. |
UA | string | Optional | Shorthand for User-Agent, the HTTP header identifying what software made the request. See User-Agent rules. |
us_privacy / TCF (euconsent_v2) | string | Optional | Standardized strings representing a user's privacy consent choices (US CCPA and EU GDPR/TCF respectively) that your app passes through unchanged. |
Comfortable with all of that? Head to the Quickstart to create your first Site and Slot, or jump straight to the SDK reference for your platform.