AI Contextual Ads SDK

A lightweight TypeScript SDK for integrating AI-powered contextual advertisements into your applications.

Installation

npm install @nigelchimz/ad-sdk

Quick Start

import { AdSDK } from '@nigelchimz/ad-sdk';

// Initialize the SDK
const adSDK = new AdSDK({
  apiKey: 'your-api-key',
  environment: 'production', // or 'development'
  enableAnalytics: true
});

// Request an ad
const ad = await adSDK.requestAd({
  context: 'User is browsing sports articles',
  userIntent: 'looking for sports equipment',
  appCategory: 'sports',
  adFormat: 'recommendation',
  maxAds: 1
});

// Display the ad
if (ad) {
  adSDK.displayAd(ad, 'ad-slot-1');
}

Configuration

SDKConfig Options

• apiKey (required): Your API key for the ad service
• environment (optional): 'development' or 'production' (default: 'development')
• apiUrl (optional): Custom API URL (overrides environment default)
• enableAnalytics (optional): Enable/disable analytics tracking (default: true)

AdRequest Options

• context (required): Contextual information about where the ad will be displayed
• userIntent (optional): User's intent or behavior context
• appCategory (optional): Category of your application
• adFormat (optional): 'conversational', 'recommendation', 'reward', or 'banner'
• maxAds (optional): Maximum number of ads to return

Methods

requestAd(request: AdRequest): Promise<AdResponse | null>

Request a contextual ad based on the provided context and parameters.

displayAd(ad: AdResponse, slotId: string): void

Display an ad in the specified DOM element.

trackClick(adId: string): Promise<void>

Manually track a click event for an ad.

getAdVariant(context: string, variants: string[]): Promise<string>

Utility method for A/B testing ad placements.

TypeScript Support

This SDK is written in TypeScript and includes full type definitions. All interfaces are exported for your convenience:

• AdRequest
• AdResponse
• SDKConfig

License

MIT