Docs/Get started

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.

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 to create both in about two minutes.

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 the ad has genuinely been on screen (≥50% visible for ≥1 second — the industry-standard definition of "actually seen"), you fire one viewability beacon. This is how the advertiser is charged fairly and how you get paid. See Beacons.

Every official SDK (see SDK reference) does steps 1, 2 and 4 for you — you only ever write step 3, the actual rendering.

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	The IAB/MRC industry standard for "this ad was actually seen": at least 50% of its pixels on screen for at least 1 continuous second. Below that threshold, it doesn't count.

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. Most common case. Fully trackable (has 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) so you never show a blank space. Not trackable — no `imp_id`, so you skip the viewability beacon for these.

The money side, briefly

Name	Type	Required	Notes
`Auction`	string	Optional	Every request runs a tiny, instant auction among interested advertisers — the highest effective bid wins the impression. This happens server-side; you never see it happen, you just get the winner back.
`Second-price auction`	string	Optional	The winner pays roughly what the second-highest bidder offered, not their own (higher) bid — the standard fair-pricing mechanism used by essentially every modern ad exchange.
`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) so advertisers aren't charged for fake views. See User-Agent rules — this is the single most common reason a correct-looking integration gets zero fills.
`Identity cookie (_an_id)`	string	Optional	A cookie the server sets to recognize the same visitor across requests, used for frequency capping (not showing the same ad 50 times) and for paying the attention dividend. Not personally identifying.
`Sandbox mode`	string	Optional	A test mode on your account that serves real-looking ads with zero billing or tracking side effects, so you can verify your integration before it touches real money. See the Quickstart.

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 — the XML format used for video ads. Out of scope for this SDK generation; see the wire contract overview.
`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.

Introduction

Quickstart