adsense-sdk

Lightweight ad-serving, rendering, and behavioral telemetry SDK for the AdSense platform.

Highlights:

• Three ad formats: inline, banner, popup
• Behavioral tracking: cursor velocity, scroll depth, dwell time, hover time
• Session-based telemetry and interaction events
• Zero runtime dependencies
• UMD bundle suitable for CDN delivery

Requirements

• Browser environment (uses window, document, and fetch)
• Modern browsers (for IntersectionObserver and fetch)
• HTTPS recommended for production

Installation

npm

npm install adsense-sdk

CDN (UMD)

<script src="https://unpkg.com/adsense-sdk/dist/adsense-tracker.umd.min.js"></script>

Quick start

ESM (React, Vue, Next.js)

import { init, requestAd } from "adsense-sdk";

init({
   apiKey: "ask_xxxxxxxxxxxx",
   endpoint: "https://adsense-gowd.onrender.com/api/v1",
   slots: ["ad-sidebar", "ad-footer"],
   delay: 3000,
   debug: true,
});

requestAd("ad-banner");

UMD (plain HTML)

<div id="ad-sidebar"></div>

<script src="https://unpkg.com/adsense-sdk/dist/adsense-tracker.umd.min.js"></script>
<script>
   AdSenseTracker.init({
      apiKey: "ask_xxxxxxxxxxxx",
      endpoint: "https://adsense-gowd.onrender.com/api/v1",
      slots: ["ad-sidebar"],
      delay: 5000,
   });
</script>

Ad slot markup

Inline ads render inside an element you provide by ID.

<div id="ad-sidebar"></div>
<div id="ad-footer"></div>

Banner and popup ads are inserted by the SDK and do not require a slot.

Configuration

| Option | Type | Default | Description | |---|---|---|---| | apiKey | string | required | API key from your dashboard (starts with ask_) | | endpoint | string | required | Backend API base URL (include /api/v1) | | slots | string[] | [] | DOM element IDs for inline ad placement | | delay | number | 0 | Delay before initial ad requests (ms) | | telemetryInterval | number | 5000 | Interval between telemetry pings (ms) | | debug | boolean | false | Enable console debug logging |

API reference

init(config: AdsenseConfig): void

Initializes the SDK, creates or restores a session ID, starts telemetry, and requests ads for configured slots.

requestAd(slotId?: string): Promise<ServedAd | null>

Manually requests an ad. If slotId is provided, renders an inline ad in that element.

getSessionId(): string

Returns the current session ID stored in sessionStorage.

trackClick(adId: number): void

Sends a click interaction for a given ad ID.

destroy(): void

Stops telemetry and flushes tracking data. Call on SPA route changes if needed.

Types

ServedAd fields returned by the backend:

interface ServedAd {
   id: number;
   title: string | null;
   body_copy: string | null;
   cta_text: string | null;
   image_url: string;
   target_url: string | null;
   ad_type: "banner" | "popup" | "inline" | string;
}

Backend endpoints used

The SDK calls these endpoints relative to endpoint:

• GET /serve/ad?session_id=...&page_url=...&ad_slot_id=...
• POST /serve/telemetry
• POST /serve/interaction
• POST /serve/ad/{ad_id}/click?session_id=...

The SDK sends the API key in the X-API-Key header.

Tracking details

Page-level telemetry (automatic):

• Cursor velocity (px/s)
• Scroll depth (0 to 1)
• Page dwell time (seconds)

Ad-level interactions (automatic):

• Hover time on the ad element
• Ad visibility time
• Mouse enter count
• Time to click and time to close

Event types: | Event | When | |---|---| | hover | Mouse leaves the ad element (hover duration is included) | | click | Manual trackClick() call | | cta_click | CTA link click on SDK-rendered ads | | close | User dismisses banner or popup | | view | Page unload flush |

Ad formats

Inline renders inside the target element. Banner is a fixed bottom bar. Popup is a centered modal with an overlay.

Notes

• This SDK runs in the browser only. In SSR frameworks, call init in a client-only context.
• Ensure your backend CORS settings allow the site where the SDK runs.

Troubleshooting

• 401 Unauthorized: invalid API key or key is disabled.
• 404 No ads available: no eligible ads for the project/session.
• 502 Bad Gateway: backend unreachable. If using a Next.js proxy route, set BACKEND_URL or NEXT_PUBLIC_API_BASE_URL to your backend base URL, including /api/v1.
• Ads not showing: check that slot IDs exist in the DOM and that your delay is not too long.

Repository

Source: https://github.com/KRISHNA-JAIN15/AdSense

License

MIT