@adxensor/publisher-sdk

v1.0.5

Published

2 months ago

AdXensor publisher SDK — serve ads, track impressions, clicks, views and pageviews directly from any website or web app.

@adxensor/publisher-sdk

AdXensor Publisher SDK — Serve ads, track impressions, clicks, views and pageviews directly from any website or web app. Works as a CDN <script> snippet or as an npm package. Zero runtime dependencies.

How it works

Publisher website                  AdXensor (core.adxensor.com)
────────────────────────────────────────────────────────────────
1. Page loads tag.js          →    Fires pageview event
2. SDK finds <ins> slots       →    GET /v1/ad?zone=SIZE&site=ID
3. Renders creative            ←    Returns image URL + click URL
4. Ad enters viewport (50%)   →    POST /v1/events/impression
5. Visible ≥ 1 second          →    POST /v1/events/view
6. User clicks ad              →    POST /v1/events/click
                                    Redirect → Advertiser URL

Country, browser and OS are resolved server-side from the visitor's IP and User-Agent — the SDK never reads or stores personal data.

CDN snippet (recommended)

Paste once in your <head>, then place <ins> tags wherever you want ads.

1. Load the SDK

<script async
  src="https://cdn.adxensor.com/tag.js"
  data-ad-client="pub-XXXXXXXX">
</script>

Replace pub-XXXXXXXX with your Site ID from the AdXensor publisher dashboard.

2. Place an ad slot

<ins class="adxensor"
     style="display:block"
     data-ad-slot="header-banner"
     data-ad-format="728x90">
</ins>

That's it. The SDK automatically fills every <ins class="adxensor"> on the page.

AdSense-style push (fill one slot at a time)

If you prefer to control when each slot loads — identical to Google AdSense:

<ins class="adxensor"
     style="display:block"
     data-ad-slot="sidebar"
     data-ad-format="300x250">
</ins>
<script>
  (window.adxensor = window.adxensor || []).push({});
</script>

Pre-load queue (calls before the script is ready)

<script>
  window.adxensor = window.adxensor || [];
  window.adxensor.push({});   // queued, executed once tag.js is ready
</script>
<!-- tag.js can be anywhere on the page -->
<script async src="https://cdn.adxensor.com/tag.js" data-ad-client="pub-XXXXXXXX"></script>

CDN script attributes

| Attribute | Required | Description | |---|---|---| | data-ad-client | ✅ | Your Site ID from the publisher dashboard | | data-api-key | — | Optional publisher API key for authenticated sites | | data-lazy-load | — | Set to "false" to disable lazy loading | | data-debug | — | Enables verbose console logs |

npm package

Install if you use a bundler (Vite, webpack, Next.js, etc.).

npm install @adxensor/publisher-sdk

Basic setup

import { AdXensor } from '@adxensor/publisher-sdk';

const adx = new AdXensor({
  siteId:   'pub-XXXXXXXX',  // your Site ID
  apiKey:   'YOUR_API_KEY',  // optional
  lazyLoad: true,            // default: true
  debug:    false,
});

adx.init(); // fires pageview + fills all <ins class="adxensor"> slots

Fill a specific slot programmatically

// By CSS selector
adx.defineSlot('#my-banner', { format: '300x250' });

// On a specific element
const el = document.getElementById('my-banner') as HTMLElement;
adx.fill(el, { format: '728x90' });

Singleton (one instance per page)

import { AdXensor } from '@adxensor/publisher-sdk';

// Always returns the same instance
const adx = AdXensor.getInstance({ siteId: 'pub-XXXXXXXX' });
adx.init();

React / Next.js example

'use client';
import { useEffect } from 'react';
import { AdXensor } from '@adxensor/publisher-sdk';

export function AdSlot({ slot, format }: { slot: string; format: string }) {
  useEffect(() => {
    const adx = AdXensor.getInstance({ siteId: 'pub-XXXXXXXX' });
    adx.defineSlot(`[data-ad-slot="${slot}"]`, { format });
  }, [slot, format]);

  return (
    <ins
      className="adxensor"
      style={{ display: 'block' }}
      data-ad-slot={slot}
      data-ad-format={format}
    />
  );
}

Ad slot attributes

| Attribute | Description | Example | |---|---|---| | class="adxensor" | Required. Identifies the element as an ad slot | — | | style="display:block" | Required. Prevents collapsed slots | — | | data-ad-slot | Slot name (used for reporting) | "header-banner" | | data-ad-format | Ad size. Defaults to auto | "728x90" | | data-ad-lazy | Presence enables lazy loading for this slot | — |

Supported formats

| Format | Size | Placement | |---|---|---| | 728x90 | 728 × 90 | Leaderboard — top/bottom of page | | 970x90 | 970 × 90 | Super leaderboard | | 970x250 | 970 × 250 | Billboard | | 300x250 | 300 × 250 | Medium rectangle — sidebar / in-feed | | 300x600 | 300 × 600 | Half page — sidebar | | 160x600 | 160 × 600 | Wide skyscraper | | 320x50 | 320 × 50 | Mobile banner | | 320x100 | 320 × 100 | Large mobile banner | | 468x60 | 468 × 60 | Full banner | | auto | dynamic | Best fit for device + container width |

Events tracked

All events are fired automatically. No manual instrumentation needed.

| Event | Trigger | Deduplication | |---|---|---| | pageview | Page load | Once per page load | | impression | Ad rendered | Once per ad × session | | view | Ad ≥ 50% visible for ≥ 1 second (IAB MRC) | Once per ad × session | | click | User clicks the ad | 500 ms debounce |

Events are sent via navigator.sendBeacon (non-blocking, survives page unload). Falls back to fetch with keepalive: true.

Advanced usage

Access lower-level APIs

import { AdXensorApi, Tracker, getSessionId } from '@adxensor/publisher-sdk';

const api = new AdXensorApi('https://core.adxensor.com/v1', 'YOUR_API_KEY');
const sessionId = getSessionId();
const tracker = new Tracker(api, 'pub-XXXXXXXX', sessionId);

// Manual event firing
tracker.pageview();
tracker.impression('adId', 'slotId', 'impressionToken');
tracker.view('adId', 'slotId');
tracker.click('adId', 'slotId', 'clickToken');

Destroy and reset (SPA route changes)

adx.destroy();        // stop DOM observer, clear timers
AdXensor.reset();     // destroy + clear the singleton

TypeScript

The SDK is written in TypeScript and ships full type declarations.

import type {
  AdXensorConfig,
  SlotOptions,
  AdFormat,
  DeviceType,
  AdResponse,
  SlotState,
} from '@adxensor/publisher-sdk';

const config: AdXensorConfig = {
  siteId:   'pub-XXXXXXXX',
  lazyLoad: true,
};

const options: SlotOptions = {
  format: '300x250',
  lazy:   false,
};

Requirements

| Environment | Minimum version | |---|---| | Node.js (npm build) | 18+ | | Browser (CDN) | Chrome 58, Firefox 57, Safari 11, Edge 16 | | IntersectionObserver | Required for lazy load + viewability (polyfill for IE) |

Support

Dashboard — app.adxensor.com
Documentation — docs.adxensor.com
Issues — GitLab Issues
Email — [email protected]

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@adxensor/publisher-sdk

Table of Contents

How it works

CDN snippet (recommended)

1. Load the SDK

2. Place an ad slot

AdSense-style push (fill one slot at a time)

Pre-load queue (calls before the script is ready)

CDN script attributes

npm package

Basic setup

Fill a specific slot programmatically

Singleton (one instance per page)

React / Next.js example

Ad slot attributes

Supported formats

Events tracked

Advanced usage

Access lower-level APIs

Destroy and reset (SPA route changes)

TypeScript

Requirements

Support