@halo-ads/core

Framework-agnostic Halo Ads SDK core — ad fetching, DOM rendering, event tracking, and user profiling.

Install

pnpm add @halo-ads/core

Key exports

| Export | Description | |---|---| | HaloAds | Main singleton — init, getAd, render, track, getProfile | | AdClient | Raw HTTP client for /v1/decide | | AdLoader | Slot-based ad loading with fill/no-fill logic | | Analytics | Event batching & flush | | EventTracker | Impression / click tracking | | DOMRenderer | Renders ad HTML into a container | | Recommendation | Client-side ad scoring (context affinity) | | ProfileStore | Persists user profile to localStorage | | MockAdProvider / MOCK_ADS | Drop-in mock for testing without an API |

Usage

import { HaloAds, MockAdProvider } from '@halo-ads/core';

// Use real API
HaloAds.init({ publisherId: 'pub_xxx', apiKey: 'pk_live_...' });

// Or use mock for local dev / testing
HaloAds.init({ publisherId: 'pub_test' });
// (core auto-selects MockAdProvider in development when no apiKey is set)

const ad = await HaloAds.getAd({ slot: 'sl_banner', format: 'banner' });

await HaloAds.render({
  container: '#ad-slot',
  slot: 'sl_banner',
  format: 'banner',
  onImpression: (ad) => console.log('seen:', ad.id),
  onClick:      (ad) => console.log('clicked:', ad.id),
});

Architecture

HaloAds (singleton)
  ├── AdClient          → POST /v1/decide
  ├── AdLoader          → manages slot state, fill/no-fill, caching
  ├── Analytics         → batches TrackEvents, flushes on interval/unload
  ├── EventTracker      → wraps Analytics with impression/click helpers
  ├── DOMRenderer       → injects ad HTML, handles theme tokens
  ├── Recommendation    → scores ads client-side against context_vector
  └── ProfileStore      → read/write UserProfile in localStorage