@happyvertical/smrt-ads

中文文档
0.62.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 1.4万

Advertising delivery and tracking models for SMRT framework

原始使用文档
文档目录9 节
  1. Installation
  2. Usage
  3. Delivery Tier Waterfall
  4. API
  5. Models
  6. Collections
  7. Enums
  8. Dependencies
  9. Contributor guide

@happyvertical/smrt-ads

Advertising delivery and tracking models for the s-m-r-t framework. Supports priority-based ad group delivery with a tier waterfall, IAB ad formats, weighted A/B variation testing, and immutable event tracking.

Installation

pnpm add @happyvertical/smrt-ads

Usage

import {
  AdDeliveryTier, AdDeliveryTierCollection,
  AdGroup, AdGroupCollection,
  AdVariation, AdVariationCollection,
  AdEvent, AdEventCollection,
  AdEventType, PricingModel, AdGroupStatus
} from '@happyvertical/smrt-ads';

// Define delivery tiers (lower priority number = served first)
const tiers = await AdDeliveryTierCollection.create({ db });
const sponsorship = await tiers.create({
  name: 'Sponsorship',
  priority: 1,
  pricingModel: PricingModel.FIXED,
});

const standard = await tiers.create({
  name: 'Standard',
  priority: 2,
  pricingModel: PricingModel.CPM,
});

// Create an ad group with targeting and budget
const groups = await AdGroupCollection.create({ db });
const group = await groups.create({
  name: 'Holiday Campaign',
  tierId: sponsorship.id,
  contractId: 'contract-uuid',
  status: AdGroupStatus.ACTIVE,
  dailyBudget: 100.00,
  totalBudget: 3000.00,
  startDate: new Date('2024-06-01'),
  endDate: new Date('2024-08-31'),
});
group.setTargeting({ device: 'desktop', geo: 'US' });
group.setZoneIds(['zone-1', 'zone-2']);
await group.save();

// Add variations with weights for A/B testing
// weight=2 is selected 2x more often than weight=1
const variations = await AdVariationCollection.create({ db });
const varA = await variations.create({
  groupId: group.id,
  name: 'Version A - Blue CTA',
  weight: 2,
  status: 'active',
});

// Track an immutable event (create-only, no update/delete)
const events = await AdEventCollection.create({ db });
await events.create({
  variationId: varA.id,
  zoneId: 'zone-uuid',
  siteId: 'site-uuid',
  eventType: AdEventType.IMPRESSION,
});

Delivery Tier Waterfall

Ads are selected by tier priority (lower number = higher priority):

  1. Sponsorship (priority 1) -- guaranteed premium placements, FIXED pricing
  2. Standard (priority 2) -- regular programmatic ads, CPM pricing
  3. House (priority 3) -- self-promotional fallback ads

Within a tier, variations are selected by relative weight. A variation with weight: 2 is twice as likely to be chosen as one with weight: 1.

API

Models

ExportDescription
AdDeliveryTierPriority tier for waterfall delivery (name, priority, pricingModel)
AdFormatIAB standard ad dimensions (width, height, formatType: banner/native/video)
AdGroupCampaign with targeting rules, budget, zone restrictions, and date range
AdVariationCreative variant within a group with weight for A/B distribution. Denormalized impressions/clicks counts
AdEventImmutable tracking event (impression/click/conversion). Create-only -- no update/delete. cli: false (high-volume)

Collections

AdDeliveryTierCollection, AdFormatCollection, AdGroupCollection, AdVariationCollection, AdEventCollection

Enums

ExportValues
AdEventTypeimpression, click, conversion
AdFormatTypebanner, native, video
AdGroupStatusdraft, active, paused, completed
AdVariationStatusdraft, active, paused
PricingModelfixed, cpm, cpc, cpa

Dependencies

  • @happyvertical/smrt-core -- ORM and code generation
  • @happyvertical/smrt-tenancy -- multi-tenant scoping (optional on AdGroup, AdVariation, AdEvent)
  • Peer: @happyvertical/smrt-assets, @happyvertical/smrt-commerce, @happyvertical/smrt-properties, @happyvertical/smrt-tags

Contributor guide

See AGENTS.md for package architecture, invariants, validation, and contributor guidance.

版本与发布记录

@happyvertical/smrt-ads 共发布 366 个版本,首次发布于 2026/06/23;过去 12 个月发布了 366 个版本。

版本发布日期距今
0.62.1latest2026/11/17今天
0.62.02026/11/17今天
0.61.62026/11/161 天前
0.61.52026/11/161 天前
0.61.42026/11/161 天前
0.61.32026/11/152 天前

关于 @happyvertical/smrt-ads 的常见问题

@happyvertical/smrt-ads 是什么?

Advertising delivery and tracking models for SMRT framework

如何安装 @happyvertical/smrt-ads?

在项目目录运行 npm install @happyvertical/smrt-ads,或使用 pnpm add / yarn add / bun add。

@happyvertical/smrt-ads 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@happyvertical/smrt-ads 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@happyvertical/smrt-ads 可以商用吗?

@happyvertical/smrt-ads 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@happyvertical/smrt-ads 的下载量有多少?

根据 npm 官方下载统计,@happyvertical/smrt-ads 在 2026/10/17 – 2026/11/15 这 30 天内被下载 14,034 次,日均约 468 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@happyvertical/smrt-ads 还在维护吗?

最新版本 0.62.1 发布于 2026/11/17(今天);至今共发布 366 个版本,其中过去 12 个月发布了 366 个;首次发布于 2026/06/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。