# `ad pmax-create` JSON 配置说明

`siluzan-tso ad pmax-create` / `ad pmax-validate` **仅**接受 `--config-file` 指向的 JSON 文件。

**与 Search 智投隔离**：勿使用 `campaign-create-template.json` 或 `ad campaign-create`。PMax 使用 `ad pmax-create`，同步返回 `campaignId`。

模板 JSON：同目录 [`pmax-create-template.json`](pmax-create-template.json)。

---

## Agent 常见坑

| 场景 | 正确做法 |
|------|----------|
| 创建 PMax | `pmax-validate` → 用户确认 → `pmax-create` |
| 文案超长 | `pmax-validate --json-out` 读 `lengthViolations`（含完整 `text`）；**勿自动截断**，列改写方案给用户确认后再改 JSON 并重跑 validate（同 Search `campaign-validate`） |
| 金额 | JSON 填**主币种「元」**；CLI 提交前 `budget`、`targetCpa_BidingAmount` ×100 |
| 图片 | **只填 `imagePaths`** 指向本地 PNG/JPEG；`pmax-create` 会自动 multipart 上传并用 assetId 创建（勿把 Base64 提交进 Git） |
| 视频 | JSON 填 **`videoPath`**（别名 `video` 亦可）；`pmax-create` 成功后 **必定**经 PyAPI 上传并链接（含 `--json-out`）。已有 YouTube 用 `youtubeUrlOrId` |
| 附加资产 | 可选填 **`campaignExtensions`** |
| 改已上线 PMax | `ad pmax-get` / `pmax-edit` / `pmax-assets-update` 等（见 `references/google-ads/pmax-api.md`） |
| 列表复核 | `ad campaigns -a <id> --json-out ./snap`，`channelTypeV2` 应为 `PERFORMANCE_MAX` |

---

## 推荐命令顺序

```bash
siluzan-tso ad geo search -a <accountId> -q "United States"
siluzan-tso ad pmax-validate --config-file ./pmax.json --json-out ./snap-pmax
# 用户确认方案后：
siluzan-tso ad pmax-create --config-file ./pmax.json --json-out ./snap-pmax
siluzan-tso ad campaigns -a <accountId> --json-out ./snap
```

---

## 字段说明（camelCase）

| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `account` | string | ✅ | Google 媒体客户 ID（`list-accounts` → `mediaCustomerId`） |
| `name` | string | ✅ | 广告系列名称 |
| `budget` | number | ✅ | 日预算（**元**），如 `50` = 主币种 50.00/天 |
| `budgetName` | string | | 预算资源名称 |
| `assetGroupName` | string | | 首个资产组名称；缺省由服务端生成 |
| `finalUrls` | string[] | ✅ | 至少 1 个 `https://` 落地页 |
| `businessName` | string | ✅ | BUSINESS_NAME：1 条，≤25 字符 |
| `headlines` | string[] | ✅ | HEADLINE：3–15 条，每条 ≤30 字符（CJK×2） |
| `longHeadlines` | string[] | ✅ | LONG_HEADLINE：1–5 条，每条 ≤90 字符 |
| `descriptions` | string[] | ✅ | DESCRIPTION：2–5 条，每条 ≤90 字符 |
| `imagePaths.marketing` | string | ✅* | MARKETING_IMAGE 横图 1.91:1，≤5MB（创建 JSON 1 张；资产组 API 最多 20） |
| `imagePaths.square` | string | ✅* | SQUARE_MARKETING_IMAGE 方图 1:1，≤5MB（创建 1 张；最多 20） |
| `imagePaths.logo` | string | ✅* | LOGO 方图 1:1，≤5MB（创建 1 张；最多 5） |
| `marketingImageAssetId` | string | ✅* | 已上传横图 asset.id（与 path/base64 三选一） |
| `squareMarketingImageAssetId` | string | ✅* | 已上传方图 asset.id |
| `logoImageAssetId` | string | ✅* | 已上传 Logo asset.id |
| `marketingImageBase64` | string | ✅* | 内联 Base64（不推荐；无 path 时用） |
| `squareMarketingImageBase64` | string | ✅* | 内联方图 Base64 |
| `logoImageBase64` | string | ✅* | 内联 Logo Base64 |
| `targetedLocations` | `{ id }[]` | | 地理 criterion ID，如 `{ "id": "2840" }`（美国） |
| `targetedLanguages` | `{ id }[]` | | 语言 ID，如 `{ "id": 1000 }`（英语） |
| `biddingStrategyTypeV2` | string | | 默认 `MAXIMIZE_CONVERSIONS` |
| `targetCpa_BidingAmount` | number | | `TARGET_CPA` 或带目标 CPA 的 `MAXIMIZE_CONVERSIONS` 时必填（**元**） |
| `targetRoas` | number | | `TARGET_ROAS` 时必填（如 `2.5` = 250%） |
| `videoPath` | string | | YOUTUBE_VIDEO（可选）：本地视频 ≥10s；与 `youtubeUrlOrId` 二选一，创建时最多 1 条；更多视频创建后用 `pmax-youtube-link` / `pmax-assets-update` 追加 |
| `videoTitle` | string | | PyAPI 上传标题（默认文件名） |
| `videoDescription` | string | | PyAPI 上传描述（可选） |
| `youtubeUrlOrId` | string | | 已有 YouTube URL 或 11 位 ID；`pmax-create` 后自动链接 |
| `youtubeAssetName` | string | | 链接 YouTube 时的资产显示名 |
| `campaignExtensions` | object | | 创建成功后自动挂载的 Campaign 级扩展（见下表） |

\* 三张图各须有一种来源（路径或 Base64）。

### `campaignExtensions`（可选，CLI 编排）

**不**随 `POST .../campaign/pmax` 提交；活动创建成功后 CLI 自动调用 `extensionmanagement`。

| 子字段 | 类型 | 说明 |
|--------|------|------|
| `callouts` | string[] | 宣传信息（CALLOUT），每条 ≤25 字符，各创建 1 个扩展 |
| `structuredSnippets` | object[] | `{ header, values }`；`values` 至少 3 项 |
| `leadForm` | object | 潜在客户表单；字段同 `pmax-lead-form-template.json` 的 `leadForm` |
| `businessMessage` | object | WhatsApp 私信；字段同 `pmax-whatsapp-template.json` 的 `businessMessage` |

标头可选值：`ad extension snippet-headers`。WhatsApp 需 Google API 白名单（见 `pmax-whatsapp-template.md`）。

若挂载失败，活动仍已创建；`--json-out` 的 `campaignExtensions` 段含各条 `ok` / `error`，可手动 `ad extension *` 补挂。

### 出价策略（PMax 支持子集）

| 值 | 说明 |
|----|------|
| `MAXIMIZE_CONVERSIONS` | 默认 |
| `MAXIMIZE_CONVERSION_VALUE` | 最大化转化价值 |
| `TARGET_CPA` | 目标 CPA（须 `targetCpa_BidingAmount`） |
| `TARGET_ROAS` | 目标 ROAS（须 `targetRoas`） |

---

## 成功响应（create）

网关同步返回（camelCase）：

| 字段 | 说明 |
|------|------|
| `campaignId` | 活动 ID |
| `assetGroupId` | 首个资产组 ID |
| `budgetId` | 日预算 ID（后续 PATCH 改预算时需与 `budget` 成对） |

---

## 范围说明

- **支持**：Lead Gen / 非 Shopping 的 Performance Max
- **不含**：Shopping PMax、Listing groups；信号与其它编辑见 `ad pmax-signals-*` 等（`references/google-ads/pmax-api.md`）

命令与流程见 `references/google-ads/pmax-api.md`。
