Ad Sales Engine SDK Docs

1 Overview

The Ad Sales Engine powers all ad delivery, targeting, analytics, and monetization across NovaReelOS. Built on a modular, event-driven architecture, it handles the full lifecycle from campaign creation through impression logging and revenue attribution.

Every ad event flows through the unified 45/55 revenue split — creators earn 45% of all ad revenue their content generates, platform retains 55%. This split is consistent across every surface: Video, Posts, Music, Shop, and LIVE.

2 Architecture

The SDK is organized into focused modules, each responsible for a single domain:

/ad-engine /src /auction auctionEngine.ts bidValidator.ts pricingModel.ts /delivery deliveryEngine.ts frequencyCap.ts adSelector.ts /targeting interestGraph.ts audienceMatch.ts engagementPredictor.ts /brandSafety safetyScore.ts riskDetector.ts /events eventBus.ts eventTypes.ts eventIngestor.ts /analytics campaignAnalytics.ts creatorAnalytics.ts /api campaigns.ts delivery.ts analytics.ts /utils logger.ts validator.ts errorHandler.ts /tests package.json README.md

3 Installation

bash

npm install @novareelos/ad-engine

4 Initialize SDK

javascript

import { AdEngine } from "@novareelos/ad-engine";

const engine = new AdEngine({
  apiKey: process.env.NOVAREELOS_API_KEY,
});

The AdEngine constructor accepts your API key and initializes all sub-modules. All subsequent calls are made through the engine instance.

5 Core Modules

Campaigns

Create and manage ad campaigns with budgets, targeting, and deliverables.

Delivery

Serve ads to surfaces with frequency capping and intelligent ad selection.

Analytics

Track and report campaign performance — impressions, clicks, conversions.

Events

Log and process monetization events through the event bus.

Targeting

Audience and interest graph targeting with engagement prediction.

Brand Safety

Content suitability scoring, risk detection, and advertiser-safe filters.

6 API Reference

POST /api/campaigns

Create a new ad campaign.

json

{
  "title": "Summer Launch Campaign",
  "budget": 5000,
  "targeting": {
    "interests": ["fitness", "lifestyle"],
    "regions": ["US"]
  },
  "deliverables": ["video", "post"]
}

GET /api/ads/serve?creatorId={id}&surface={surface}

Serve an ad to a specific creator surface.

json — response

{
  "adId": "ad_8f3k2j",
  "creativeUrl": "https://cdn.novareelos.com/ads/creative_001.mp4",
  "campaignId": "camp_29xk1"
}

POST /api/ads/log

Log an ad event (impression, click, or conversion).

json

{
  "type": "impression" | "click" | "conversion",
  "adId": "ad_8f3k2j",
  "creatorId": "123",
  "surface": "video"
}

GET /api/analytics/campaign/{id}

Get performance analytics for a specific campaign.

GET /api/analytics/creator/{id}

Get ad revenue analytics for a specific creator.

7 Event Types

The following event types are supported by the ad event pipeline:

Event	Description	Revenue Impact
`impression`	Ad viewed by a user	CPM-based billing
`click`	User clicked on an ad	CPC-based billing
`conversion`	Conversion completed (signup, purchase)	CPA-based billing
`live_adbreak`	Ad break served during a LIVE stream	Flat-rate per break
`shop_purchase`	Purchase completed via ad link	Commission-based

8 Revenue Calculation

The SDK automatically applies the 45/55 revenue split to all ad events. This split is immutable and consistent across every surface.

Creator 45%

Platform 55%

Creator receives 45% of all revenue Platform receives 55%

Surface	Creator Share	Platform Share
Video	45%	55%
Posts	45%	55%
Music	45%	55%
Shop	45%	55%
LIVE	45%	55%

9 Brand Safety

The brand safety module scores all content on a 0–100 suitability scale. Advertisers can set minimum thresholds to ensure their ads appear alongside brand-appropriate content.

Content Suitability Score

0 = high risk — 100 = fully advertiser-safe

Example: score 82/100

Risk Detection — Automated content risk analysis
Advertiser Filters — Category and keyword exclusion lists
Automatic Review — Flagged content bypasses ad delivery until cleared
Suitability Tiers — Full, Limited, or No ad eligibility

10 Code Examples

Create Campaign

javascript

const campaign = await engine.campaigns.create({
  title: "Summer Launch Campaign",
  budget: 5000,
  targeting: {
    interests: ["fitness", "lifestyle"],
    regions: ["US"],
  },
  deliverables: ["video", "post"],
});

Serve Ad

javascript

const ad = await engine.delivery.serve({
  creatorId: "123",
  surface: "video",
});

Log Event

javascript

await engine.events.log({
  type: "impression",
  adId: "abc123",
  creatorId: "123",
  surface: "video",
});