Docs/Get started

Quickstart

Four steps from zero to a served ad: account, site, slot, SDK. Every step below tells you exactly what you should see when it worked — and where to look if it didn't.

First time integrating an ad network?

The words "slot", api_key, "fill" and imp_id are explained in plain language, with analogies, on Core concepts. It takes two minutes and makes the rest of this page click into place — worth reading first if any of those are new to you.

What you'll need

  • Five minutes and an email address — no credit card, no approval wait for sandbox testing.
  • A website, app, or game to embed the ad in (any of the 9 native SDKs, or plain web).
  • Nothing else. There is no separate "developer account" step — signing up is your publisher account.

1. Create a publisher account

Sign up from the dashboard — this is the fastest path and also creates your session for the following steps.

bash
# or automate it directly against the API:
curl -X POST https://api.adx.theaimart.co/api/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"...","role":"publisher"}'

Prefer the UI? Create a free publisher account — no credit card required.

✅ Expected result

You're redirected into the dashboard and logged in. If you used the API directly, you get back a 200 with a session — no api_key yet, that comes from the next step (a login and an ad-serving credential are two different things).

2. Register a site or app

Registering a site returns your api_key — a publisher-scoped, public client identifier (pk_…). It is safe to embed in a shipped client binary; it is not a server secret and grants no account access.

bash
curl -X POST https://api.adx.theaimart.co/api/v1/publishers/sites \
  -H "Content-Type: application/json" -H "Cookie: __session=..." \
  -d '{"name":"My App","domain":"example.com","kind":"web"}'
# -> { "site_id": "...", "api_key": "pk_..." }

kind is one of web, app, ios, android, flutter, react_native.

✅ Expected result

A JSON body containing site_id and an api_key starting with pk_. Copy the api_key somewhere — you'll paste it directly into your SDK in step 4. Don't worry about keeping it secret; see what api_key actually protects.

3. Create an ad slot

A slot is a pre-configured ad unit — format and size live on the slot, not the request. Creating one returns the slot_id your SDK will reference.

bash
curl -X POST https://api.adx.theaimart.co/api/v1/publishers/sites/{site_id}/slots \
  -H "Content-Type: application/json" -H "Cookie: __session=..." \
  -d '{"name":"Homepage banner","format":"banner","size":"300x250"}'
# -> { "slot_id": "8b1f2c3d-....-uuid" }

Pick a v1-ready format

format is one of banner, video, interstitial, native, rewarded. For this SDK generation, use banner, interstitial or native — rewarded has no internal-demand fill yet, and video serves over the VAST path, which today's SDKs intentionally don't ship against. See Getting credentials for the full caveat.

✅ Expected result

A slot_id (a UUID). If this is your very first Slot, it can take a short moment to become fully active — if step 4 returns a "slot not found"-style no-fill immediately after creating it, wait a few seconds and retry before assuming something's broken.

4. Install your SDK

Put the api_key and slot_id from the previous steps into the SDK for your platform:

ts
import { AdxWebClient } from "@theaimart/adx-web";

// 1. Construct the client once with your api_key from step 2:
const client = new AdxWebClient({ apiKey: "pk_your_publisher_key" });

// 2. Ask for an ad using the slot_id from step 3:
const ad = await client.requestAd({ slotId: "8b1f2c3d-....-uuid", pageUrl: location.href });

// 3. Render it if filled, and report once it's actually been seen:
if (ad.filled) {
  // render ad.creative — image via <img>/<a>, HTML via a sandboxed iframe
  if (ad.isTrackable) await client.reportViewable(ad.impId!);
} else {
  // No-fill is normal — render nothing. ad.reason may explain why (optional).
  console.log("no fill:", ad.reason);
}

That's the Web SDK; every other platform has the identical shape — construct a client with your api_key, call requestAd/request_ad with the slot_id, render, then report viewability. See the full SDK reference for your platform's install command, drop-in component and API surface.

✅ Expected result

In sandbox mode (next section), ad.filled is true almost every time, with a real-looking creative.assetUrl you can render immediately. In production before you have real advertiser demand or house ads configured, seeing ad.filled === false on some requests is completely normal — it means "no fill this time," not "broken."

Getting zero fills every single time, including in sandbox? See Troubleshooting — it's almost always the User-Agent.

Test in sandbox mode

Every account includes a sandbox mode (the Sandbox tab in the publisher dashboard) that serves real creative payloads with zero billing or tracking side effects — verify your rendering and beacon wiring before going live.

Go-live checklist

Before you turn sandbox mode off and point real traffic at your integration, confirm:

  • You handle both the filled and no-fill cases — a no-fill must render nothing, not an error state.
  • You only fire the viewability beacon when ad.isTrackable is true (house ads and no-fills have no imp_id).
  • You never auto-refresh a slot faster than every 30 seconds.
  • If you're server-side (Node/Python/Rust), you forward each real end user's own User-Agent and IP — not your server's.
  • Any HTML/OpenRTB creative renders through the SDK's own sandboxed iframe/WebView — you haven't customized that away.

What's next

  • Read the wire contract to understand exactly what the backend sends back and why the SDKs encode requests the way they do.
  • Check User-Agent rules if you're building a custom client — the single most common cause of unexplained no-fill.
  • Read the security model before rendering any OpenRTB/HTML creative yourself.
  • Bookmark Troubleshooting — it covers every symptom in this section (and more) with the exact fix.