# @happyvertical/smrt-ads 中文文档

规范地址：https://npmcn.com/package/%40happyvertical/smrt-ads/

版本：0\.62\.1
npm 元数据更新时间：2026-11-17T07:53:33.061Z
中文译文更新时间：2026-11-17T10:30:32.910Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40happyvertical/smrt-ads
原文对照：https://npmcn.com/package/%40happyvertical/smrt-ads/?lang=original
项目主页：https://github.com/happyvertical/smrt#readme
源码仓库：https://github.com/happyvertical/smrt

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：506 kB，42 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-06-23T01:18:24.588Z
- 最新版本发布：2026-11-17T07:53:32.855Z
- 近 30 天下载量：14034（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：366（近 12 个月 366 个）

## 中文简介

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

## 安装

```sh
npm install @happyvertical/smrt-ads
```

也可以使用：`pnpm add @happyvertical/smrt-ads`、`yarn add @happyvertical/smrt-ads`、`bun add @happyvertical/smrt-ads`

## README

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

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

## 安装

```bash
pnpm add @happyvertical/smrt-ads
```

## 使用量

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

### 收款

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

### 数字

| 导出 | 数值 |
| --- | --- |
| `AdEventType` | `impression`, (中文(简体) ), `click`, (中文(简体) ), `conversion` |
| `AdFormatType` | `banner`, (中文(简体) ), `native`, (中文(简体) ), `video` |
| `AdGroupStatus` | `draft`, (中文(简体) ), `active`, (中文(简体) ), `paused`, (中文(简体) ), `completed` |
| `AdVariationStatus` | `draft`, (中文(简体) ), `active`, (中文(简体) ), `paused` |
| `PricingModel` | `fixed`, (中文(简体) ), `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`](https://npmcn.com/package/%40happyvertical/smrt-ads/AGENTS.md) 用于软件包结构、变化、验证、, 和贡献者的指导.

## 常见问题

### @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 和提交记录判断。

