Skip to content
Docs/Get started

Publisher quickstart

Start with a safe local SDK test, then register and review the property before requesting production advertising.

Confirm runtime and origin availability

Check the capability matrix first. SDK publication, device rendering, publisher approval and available demand are separate. Browser serving requires an approved origin; live requests may have billing side effects.

1. Install and test locally

Node version 1.0.0 is published. This example injects a mock transport and makes no network requests, impressions or charges.

bash
npm install @theaimart/adx@1.0.0
safe-no-fill.ts
import { Adx, type Transport } from '@theaimart/adx';

const mockTransport: Transport = {
  async request() {
    return { status: 200, body: '{"fill":false,"reason":"local_test"}', getHeader: () => null };
  }
};
const client = new Adx({ apiKey: 'pk_local_example', transport: mockTransport });
const ad = await client.requestAd({ slotId: '00000000-0000-4000-8000-000000000000' });
if (!ad.filled) {
  console.log('No-fill handled safely:', ad.reason);
}
// No render, viewability report or billing occurs in this mock example.
// Use live credentials only after property review and sandbox validation.

Expected result: a no-fill message. Leave the placement empty and do not send a viewability report. For Web, React Native or a device runtime, use the runtime reference and its source/distribution instructions.

2. Create a publisher account

Create your account through the website. Complete email verification where requested. Account creation does not establish approval or generate paid revenue.

3. Register and verify a property

In the publisher workspace, add accurate site or app details. The source returns a site id and site-scoped api_key. Web properties start pending and require domain ownership verification before serving. Confirm the origin and account eligibility before enabling live requests.

4. Create a placement

Configure an eligible ad slot in the property and retain its id as the SDK slotId. Format and size are placement properties, not request fields. Choose a format your host runtime actually renders; see format limits.

5. Validate a confirmed sandbox

The publisher interface has a sandbox workflow. Verify its activation and returned payloads before testing, or continue with local mocks. A normal call to the production serving endpoint is not assumed to be a sandbox request.

Before live traffic

  • Property and origin are eligible and account review is complete.
  • Handle filled, malformed, rejected and no-fill responses without interrupting the host product.
  • Render creatives through the selected runtime’s isolated renderer. Flutter and Unity HTML need host-provided rendering.
  • Reserve space and measure host performance; asynchronous loading does not guarantee Core Web Vitals.
  • Report viewability only after the documented visibility threshold, only for trackable impressions. Receiving a response is not a view.
  • Do not share identity cookies across users. Forward permitted real-user context for server-mediated requests. The reviewed backend may still attribute IP to the server; validate the trusted proxy path.
  • Pass applicable privacy signals and implement the consent obligations of your property.

Reproducible package test

The frontend repository includes a lockfile-backed executable example and a measured local experiment. See the Node SDK experiment for commands, raw results, environment and limitations.

Next steps

Read credential and API boundaries, request fields, response handling, tracking and troubleshooting.