Analytics Hooks

Monitor ad fetching in real-time with analytics hooks. Perfect for logging, metrics, and debugging.

Available Hooks

Hook	Triggered When
`onAdFetched`	Ad is successfully fetched
`onError`	Request fails
`onEmpty`	No ad available

Basic Usage


import Ads from 'notpixel';
 
const ads = new Ads({
  publisherId: 'pub-xxx',
  hooks: {
    onAdFetched: (event) => {
      console.log('Ad fetched:', event.ad.id);
      console.log('Latency:', event.latencyMs, 'ms');
      console.log('From cache:', event.cached);
    },
    onError: (event) => {
      console.error('Error:', event.error);
      console.error('Input:', event.input);
    },
    onEmpty: (event) => {
      console.log('No ad available');
      console.log('Reason:', event.reason);
    },
  },
});

Event Types

onAdFetched


interface AdFetchedEvent {
  ad: Ad;           // The fetched ad
  latencyMs: number; // Time taken to fetch
  cached: boolean;   // Whether from cache
  input: string;     // Original input
}

onError


interface AdErrorEvent {
  error: string;    // Error message
  input: string;    // Original input
}

onEmpty


interface AdEmptyEvent {
  reason: 'no_ad' | 'low_relevance' | 'budget_exhausted';
  input: string;    // Original input
}

Empty reasons:

no_ad — No ads available for this context
low_relevance — Ads exist but didn’t meet minimum relevance score
budget_exhausted — Advertiser budget is depleted

Integration Examples

Send to Analytics Platform


const ads = new Ads({
  publisherId: 'pub-xxx',
  hooks: {
    onAdFetched: (e) => {
      analytics.track('ad_fetched', {
        adId: e.ad.id,
        latency: e.latencyMs,
        cached: e.cached,
      });
    },
    onError: (e) => {
      analytics.track('ad_error', { error: e.error });
    },
  },
});

Log to Console (Debug)


const ads = new Ads({
  publisherId: 'pub-xxx',
  hooks: {
    onAdFetched: (e) => console.log(`[AD] ${e.ad.id} (${e.latencyMs}ms)`),
    onError: (e) => console.error(`[AD ERROR] ${e.error}`),
    onEmpty: (e) => console.warn(`[AD EMPTY] ${e.reason}`),
  },
});

Async Hooks

Hooks can be async — the SDK won’t wait for them to complete:


hooks: {
  onAdFetched: async (e) => {
    await sendToDatabase(e);
  },
}