@happyvertical/smrt-ads

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

SMRT框架的广告发布和跟踪模型

中文使用文档
文档目录9 节
  1. 安装
  2. 使用量
  3. 一级瀑布
  4. API 密码
  5. 模型
  6. 收款
  7. 数字
  8. 依赖关系
  9. 贡献者指南

@happyvertical/ smrt-ads (欢快的垂直)

S-m-r-t框架的广告投放和跟踪模型. 支持以分级瀑布、IAB广告格式、加权A/B变异测试和不可变事件跟踪为主的广告团体提供.

安装

pnpm add @happyvertical/smrt-ads

使用量

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,
});

一级瀑布

广告通过分级优先排序(下数=高优先排序):

  1. 赞助 (优先事项1) -- -- 保费安排、固定定价
  2. 标准 (优先事项2) -- -- 经常方案广告、CPM定价
  3. 房屋 (优先事项3) -- -- 自我促进倒置广告

在某一层级内,根据相对权重选择变化。 与 weight: 2 被选中的可能性是 weight: 1。 。 。 .

API 密码

模型

导出说明
AdDeliveryTier瀑布交付的优先级(名称、优先级、定价模式)
AdFormatIAB标准广告尺寸(宽度,高度,格式) Type:横幅/内地/视频)
AdGroup具有目标选择规则、预算、区域限制和日期范围的运动
AdVariation具有A/B分布重量的组内创造性变体. 非正常状态 impressions编号 :clicks 计数
AdEvent不可移动跟踪事件(印象/点击/转换). 只创建 - 没有更新/删除 . cli: false (高数量)

收款

AdDeliveryTierCollection, (中文(简体) ), AdFormatCollection, (中文(简体) ), AdGroupCollection, (中文(简体) ), AdVariationCollection, (中文(简体) ), AdEventCollection

数字

导出数值
AdEventTypeimpression, (中文(简体) ), click, (中文(简体) ), conversion
AdFormatTypebanner, (中文(简体) ), native, (中文(简体) ), video
AdGroupStatusdraft, (中文(简体) ), active, (中文(简体) ), paused, (中文(简体) ), completed
AdVariationStatusdraft, (中文(简体) ), active, (中文(简体) ), paused
PricingModelfixed, (中文(简体) ), cpm, (中文(简体) ), cpc, (中文(简体) ), cpa

依赖关系

  • @happyvertical/smrt-core -- ORM 和代码生成
  • @happyvertical/smrt-tenancy -- 多租户范围界定(关于AdGroup、AdVariation、AdEvent的选择)
  • 端点 : @happyvertical/smrt-assets, (中文(简体) ), @happyvertical/smrt-commerce, (中文(简体) ), @happyvertical/smrt-properties, (中文(简体) ), @happyvertical/smrt-tags

贡献者指南

见 AGENTS.md 用于软件包结构、变化、验证、, 和贡献者的指导.

版本与发布记录

@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 是什么?

SMRT框架的广告发布和跟踪模型

如何安装 @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 和提交记录判断。