TradPlus CLI 使用说明

修订历史

发布时间	修订说明
2026-08-06	补充 Unity Ads 插屏开屏创建说明（流程 B3）；`placement upsert` 参数表对齐 Unity Ads 填写规则
2026-07-28	正式能力基线更新为 v0.21.0-release（本次上线 CLI/MCP 版本；安装与 `tp version` 说明同步）
2026-07-28	`sdk-event-detail` 新增 `--include-closed`：与 `--group-id` + `--tradplus-placement-id` 联用时可查组内已关闭源的历史事件；默认仍仅开启源
2026-07-22	新增 `tp intermediary reorder` 调整同一广告位 / AB 分组下自定义中介组优先级
2026-07-15	SDK 事件明细补充下钻约定：`metric=adsource`/`load_time` 仅 event 800/801；800 排障优先 `error_code`
2026-07-15	SDK 事件报表支持 `--group-id` 按中介组过滤
2026-07-15	`tp report v4` 支持指标 `fillTime`（填充时长）
2026-07-06	`tp report v2` 不支持中介组过滤；使用 `--group-id` 时 CLI 输出 warning，应改用 `report v4`
2026-07-06	V4 报表 `--group-id` 支持传 `0` 表示默认中介组（所有国家组）
2026-07-03	对齐 CLI/MCP v0.17.0-release；正式环境 `version=latest` 安装包版本提示
2026-07-02	补充管理 API 与报表 OpenAPI 双后端配置（`TRADPLUS_REPORT_BASE_URL`）；扩展报表网关路由、只读模式与 §11.5 参数
2026-06-17	报表命令新增：用户价值/留存扩展、新增用户分析、设备层级数据下载；补充对应 MCP 工具说明
2026-06-12	新增数据报表查询命令（综合报表、用户价值、留存、A/B测试等）
2026-05-22	扩展配置管理与写操作命令
初版	支持开发者后台管理 API 的命令行操作

1. 简介

TradPlus CLI（命令名 **tp**）是开发者后台管理 API 与数据报表查询 API 的命令行入口。适合在终端完成应用/广告位/广告源管理、中介组与 A/B测试配置，以及综合报表查询，而不必反复登录开发者后台点选。

您可以用它做什么（业务视角）

诉求	典型命令
导出应用/广告位/广告源清单	`tp placement list` 等；见 §7.7
查看账号可见资源、广告网络授权摘要	`tp auth summarize`、`tp summarize platform`
按日期拉广告网络API收入、TradPlus统计展示/点击，或按国家地区/广告网络拆分	`tp report v4`（及 `v3` / `api` / `tp` 等子命令）
查用户价值 LTV（1–90 天）或 cohort 留存（2–90 天）	`tp report ltv`、`tp report tpltv`、`tp report retention`
查 DAU/DEU 等用户指标或 A/B测试报表	`tp report active-users`；`tp report abtest` / `confidence` / `forecast`
在测试环境核对配置后再改生产（写操作需 `--yes`）	`tp placement upsert`、`tp adseat create` 等

与开发者后台怎么选

方式	更适合
开发者后台	可视化改配置、看图表、一次性操作
CLI（本文）	批量导出、定时拉取报表数据、脚本调用、自动化流水线、`ssh` 到跳板机执行

技术特点（了解即可）

可在 Shell 脚本、定时任务、CI 中使用。
支持 compact / table / json / jsonl / csv 等输出，便于人看或导入表格。
写操作默认不执行，必须加 --yes；可先 dry-run 或 --print-request 核对。
复杂筛选、报表维度等可通过 --args '{"字段":值}' 补充（字段名与 API 文档一致）。
新增报表命令需使用最新版 CLI；若提示命令不存在，请重新安装后执行 tp version 确认（当前正式能力基线为 v0.21.0-release；也可安装时显式指定 version=v0.21.0-release）。

1.1 按角色怎么读本文（导读）

您是…	建议阅读顺序	预计时间
报表查询	§4.5 输出示例 → §5.4 速查表 → §7.7 导出 → §12	约 20 分钟
技术支持	§6 场景 B/D → §11 参数速查 → §9 写操作	按需
研发 / 自动化	§8 传参规范 → §10 功能列表 → API 文档	按需

以下为测试环境示例编号（来自示例账号，便于对照返回字段；仅当您已开通测试环境且账号下存在对应数据时适用；正式环境请使用自己开发者后台的应用/广告位编号）：

应用 12E3E378A088B78EA80AAB035E244E06
广告位 0E27DC206544B7A6CE765F262F6B56C7
广告源 656437 / 656438 / 656439（示例，以您列表为准）

关于文档中的示例

文中的应用名、条数、总收入等因账号而异；示例用于说明字段含义与命令写法，不要求数字与名称完全一致。
测试环境：须使用贵司或 TradPlus 提供的测试网关与 API Key；未开通时，用生产地址 + 只读命令即可上手。
生产环境：写操作会改动真实配置；请先不加 --yes 预演，确认无误后再执行。

2. 安装

CLI 安装包由 TradPlus 官方 CDN 分发（https://mcp.tradplusad.com/cli/tp/）；下载安装后即可在终端独立使用，无需其他工具。

推荐使用安装脚本。脚本会自动识别操作系统和 CPU 架构，下载对应的 tp 二进制包并安装。

系统	CPU 架构	安装命令
macOS / Linux	amd64 / arm64	`install-tp.sh`
Windows	amd64 / arm64	`install-tp.ps1`

2.1 macOS / Linux

复制并执行：

curl -fsSL "https://mcp.tradplusad.com/cli/tp/install-tp.sh?version=latest" | bash

如果只想确认会下载哪个版本，不实际安装：

curl -fsSL "https://mcp.tradplusad.com/cli/tp/install-tp.sh?version=latest" | bash -s -- --dry-run

2.2 Windows PowerShell

复制并执行：

iwr "https://mcp.tradplusad.com/cli/tp/install-tp.ps1?version=latest" -UseB | iex

如遇执行策略限制，可先下载安装脚本，再用下面方式执行：

powershell -ExecutionPolicy Bypass -File .\install-tp.ps1

2.3 安装后验证

tp version
tp --help

tp version 应显示 v0.21.0-release 或更高版本。若版本过旧、缺少报表子命令，请重新执行安装脚本（可使用 ?version=v0.21.0-release 或 version=latest）。

如果提示 tp: command not found，说明安装目录不在 PATH 中。请根据安装脚本输出，把安装目录加入当前 shell 或系统环境变量。

3. 配置凭证

CLI 调用 API 时需要 API Key 和密钥。可在开发者后台「我的账号」中获取。

双后端说明（必读）：配置与报表走不同网关。管理类接口（应用、广告位、广告源等）走 管理 API（Bear + Secret + sign）；多数报表走 报表 OpenAPI（仅 Bearer）。CLI 通过两个地址分别路由，一般只需正确设置 base_url，report_base_url 可自动推断（见 §3.4）。

名称	CLI / 环境变量	说明
API Key	`bear` / `TRADPLUS_BEAR`	即开发者后台「API Key」；CLI 参数名为 `bear`（历史命名）
密钥	`secret` / `TRADPLUS_SECRET`	管理 API 及开发者网关报表的请求签名
管理 API 地址	`base_url` / `TRADPLUS_BASE_URL`	生产：`https://api-developer.tradplusad.com`；测试须使用贵司或 TradPlus 提供的开发者网关（示例：`https://test-2-api-developer.tradplusad.com`）
报表 API 地址	`report_base_url` / `TRADPLUS_REPORT_BASE_URL`	生产：`https://openapi.tradplusad.com`；测试：`https://test-openapi.tradplusad.com`（见 §3.4）

3.1 写入本地配置

推荐把凭证写入本地配置，后续命令就不需要重复输入。将 <您的 API Key> 和 <您的密钥> 替换为开发者后台「我的账号」中的值：

生产环境：

tp config set \
  --bear "<您的 API Key>" \
  --secret "<您的密钥>" \
  --base-url "https://api-developer.tradplusad.com"

执行 config set --base-url 时，若未显式指定 --report-base-url，会自动配对报表地址为 https://openapi.tradplusad.com。

测试环境：

tp config set \
  --bear "<您的 API Key>" \
  --secret "<您的密钥>" \
  --base-url "https://test-2-api-developer.tradplusad.com"

测试管理网关会自动配对 https://test-openapi.tradplusad.com。也可显式指定：tp config set --report-base-url "https://test-openapi.tradplusad.com"。

查看本地配置：

tp config get

输出含 base_url 与 report_base_url（敏感字段脱敏）。配置文件默认保存到：

~/.tradplus/config.yaml

3.2 使用环境变量

适合脚本、CI、容器等不希望写入本地配置文件的场景。

export TRADPLUS_BEAR="<您的 API Key>"
export TRADPLUS_SECRET="<您的密钥>"
export TRADPLUS_BASE_URL="https://api-developer.tradplusad.com"
export TRADPLUS_REPORT_BASE_URL="https://openapi.tradplusad.com"

其中 TRADPLUS_BASE_URL 为管理 API 根地址。TRADPLUS_REPORT_BASE_URL 可省略：未设置时，若 TRADPLUS_BASE_URL 含 test- 等测试标识，则推断为 https://test-openapi.tradplusad.com，否则为 https://openapi.tradplusad.com。环境变量只在当前终端会话中生效，新的终端窗口需要重新设置，或写入自己的 shell 配置文件。

3.3 使用命令行参数

也可以在单次命令中直接传入：

tp app list --bear "<您的 API Key>" --secret "<您的密钥>"

如需显式指定网关：

tp app list \
  --bear "<您的 API Key>" --secret "<您的密钥>" \
  --base-url "https://api-developer.tradplusad.com" \
  --report-base-url "https://openapi.tradplusad.com"

鉴权优先级从高到低为：

命令行参数：--bear、--secret、--base-url、--report-base-url
环境变量：TRADPLUS_BEAR、TRADPLUS_SECRET、TRADPLUS_BASE_URL、TRADPLUS_REPORT_BASE_URL
本地配置文件：~/.tradplus/config.yaml

3.4 管理 API 与报表 API 路由

环境	管理 API（`TRADPLUS_BASE_URL`）	报表 API（`TRADPLUS_REPORT_BASE_URL`）
生产	`https://api-developer.tradplusad.com`	`https://openapi.tradplusad.com`
测试	`https://test-2-api-developer.tradplusad.com`（或贵司分配的测试开发者网关）	`https://test-openapi.tradplusad.com`

下列 CLI / MCP 能力 走报表 OpenAPI（路径如 /v4/allreport，仅 Bearer）：

tp report v3 / v4 / api / tp / abtest / forecast / confidence
tp report ltv / tpltv / retention / user-arpu / user-imp / user-ecpm
tp report device（v3/v4 设备 CSV 链接）

下列能力走 管理 API 开发者网关（路径如 /api/V2/funnelReport，Bear + Secret + sign）：

tp report active-users
tp report ltv-imp / user-type / deu-retention
tp report funnel / sdk-event / sdk-event-detail

HTTP 路径与数据报表查询 API 一致；CLI 负责按上表选择网关，调用方无需手工拼接 URL。

4. 快速开始（按步骤操作）

完成 §3 后，在终端从上到下复制执行。下列「正常时您应看到」指返回结构正确；具体应用名、条数、编号以您账号为准（练习时可参考 §1.1 示例编号）。

顺序	您执行的命令	正常时您应看到
1	`tp version`	显示 CLI 版本号（如 `x.y.z`）
2	`tp auth summarize`	摘要中含 `visible_apps_total`、`visible_adseats_total` 等字段，且为大于 0 的整数
3	`tp app list --limit 3`	列表中出现若干应用名称与 `app_uuid`
4	`tp adseat list --app-uuid "<您的应用编号>"`	列出该应用下的广告位（`adseat_list` 非空或符合后台）
5	`tp placement list --currency USD --adseat-uuid "<您的广告位编号>"`	`placements` 数组中有广告源，含 `placement_id`、`name`、`adsource_id`（见 §7.7.1）

若第 2 步摘要正常、第 5 步能列出广告源，说明安装与密钥配置正确。更多场景见 §6；导出表格见 §7.7。

查某个功能怎么写参数时，可在命令后加 --help，例如：tp report v4 --help。

4.5 终端输出示例（长什么样）

下列为在测试环境执行命令后的输出示例（字段名与结构应与您的终端一致；文中名称、条数、编号来自示例账号，您的结果以实际账号为准）。练习时可对照 §1.1 中的示例编号。

准备（只需一次，密钥勿写入文档或截图）：

$ export TRADPLUS_BASE_URL="https://test-api-developer.tradplusad.com"
$ export TRADPLUS_BEAR="<您的 API Key>"
$ export TRADPLUS_SECRET="<您的密钥>"
$ tp version
tp CLI version 1.0.0

步骤 1：确认连上的是自己的测试账号

tp auth summarize --format compact

终端实际输出（裁剪，其中数字仅为示例）：

{
  "account_visibility": {
    "authorized_api_accounts": 240,
    "visible_adseats_total": 1182,
    "visible_apps_total": 121
  },
  ...
  "samples": {
    "app_uuids": [
      "12E3E378A088B78EA80AAB035E244E06",
      ...
    ]
  }
}

在输出里找这一行	和开发者后台怎么理解
`visible_apps_total`	当前 API Key 可见的应用总数（应 > 0）
`visible_adseats_total`	可见的广告位总数（应 > 0）
`samples.app_uuids`	部分账号会返回便于试用的应用编号列表，可用于后续命令

步骤 2：打开某个应用

tp app get --app-uuid "12E3E378A088B78EA80AAB035E244E06" --format compact

{
  "app_list": [
    {
      "app_name": "QQ音乐-123123歌手5，梦想的声音高品质免费下载",
      "app_uuid": "12E3E378A088B78EA80AAB035E244E06",
      ...
    }
  ]
}

→ 应用名与开发者后台「应用管理」里一致即正常。

步骤 3：列出该应用下的广告位

tp adseat list --app-uuid "12E3E378A088B78EA80AAB035E244E06" --format compact

{
  "adseat_list": [
    {
      "adseat_uuid": "0E27DC206544B7A6CE765F262F6B56C7",
      "seat_name": "asfasdf",
      "ad_type": 4,
      ...
    }
  ]
}

→ seat_name 应与开发者后台广告位名称一致；该应用下有几条以您的列表为准。

步骤 4：列出广告位下的广告源（本示例为 3 条 Bigo 广告源）

tp placement list --currency USD --adseat-uuid "0E27DC206544B7A6CE765F262F6B56C7" --format compact

终端里会出现 "placements": [ ... ] 数组，共 3 个对象。把关键字段摘出来，和开发者后台「广告源列表」对比如下：

终端里 `placement_id`	终端里 `name`（节选）	`adsource_id`	`is_header_bidding`
656437	OpenAPI Bigo banner 11166177…	57	1（Header Bidding）
656438	QA OAP-BIGO-BNR-01…	57	1
656439	QA OAP-BIGO-BNR-02…	57	0

终端实际输出（裁剪）：

{
  "has_more": 0,
  "placements": [
    {
      "placement_id": "656437",
      "name": "OpenAPI Bigo banner 11166177 1778671995",
      "adsource_id": "57",
      "is_header_bidding": "1",
      "account_name": "默认账号",
      "seat_name": "asfasdf",
      ...
    },
    {
      "placement_id": "656438",
      "name": "QA OAP-BIGO-BNR-01 1778672197-0",
      "adsource_id": "57",
      "is_header_bidding": "1",
      ...
    },
    {
      "placement_id": "656439",
      "name": "QA OAP-BIGO-BNR-02 1778672197-1",
      "adsource_id": "57",
      "is_header_bidding": "0",
      ...
    }
  ]
}

若您只看到 0 条，请检查是否漏了 --currency USD 或广告位 UUID 是否抄错。

步骤 5：权限自检（客户 UUID 能不能看见）

tp auth scope --app-uuid "12E3E378A088B78EA80AAB035E244E06" --format compact

{
  "checks": {
    "app_access": {
      "visible": true,
      "matched_count": 1,
      ...
    },
    "placement_access": {
      "visible": true,
      "matched_count": 3,
      ...
    }
  }
}

→ visible": true 且 matched_count": 3：应用可见，且 3 条广告源都能查到。

步骤 6：一眼汇总（几条源、接了哪些广告网络）

tp summarize app --app-uuid "12E3E378A088B78EA80AAB035E244E06" --args '{"currency":"USD"}' --format compact

{
  "counts": {
    "adseats": 1,
    "placements": 3,
    ...
  },
  "platforms": [
    {
      "adsource_id": "57",
      "adsource_name": "Bigo",
      "placements": 3
    }
  ],
  "sample_placement_ids": ["656437", "656438", "656439"]
}

→ 与步骤 4 的 3 条源、Bigo(57) 一致即查对。

步骤 7：查询综合报表（测试环境 `items` 常为空）

tp report v4 --start 2026-05-01 --end 2026-05-07 \
  --args '{"app_uuids":"12E3E378A088B78EA80AAB035E244E06","metrics":"revenue,impression,click","group_by":"date","currency":"USD"}' \
  --format compact

{
  "code": 200,
  "total": 0,
  "items": [],
  ...
}

输出	含义
`"code": 200`	查询成功，不是命令写错
`"items": []`	测试账号该区间没有统计行，属正常
正式有流量账号	`items` 里会出现带 `date`、`revenue` 的多行对象

步骤 8：改配置前的「预演」（不会真正执行）

tp placement toggle --args '{"placement_ids":"656437","is_on":0}'

注意：不要加 --yes。 终端应出现：

dry-run: toggle placement
request: map[is_on:0 placement_ids:656437]
Re-run with --yes to execute.

→ request: 行表示 CLI 已解析出将要提交的参数；未加 --yes 时不会真正修改配置。上例已识别广告源 656437；确认无误后再加 --yes 才会真正关闭。

和开发者后台页面对照（示意）

开发者后台：应用「QQ音乐-…」 → 广告位「asfasdf」 → 广告源列表 3 行
         │                      │                      │
CLI：  app get / summarize   adseat list          placement list
       app_uuid 12E3…         adseat 0E27…         placement_id 656437/38/39

5. 适用角色与第一次上手

5.1 谁适合用 CLI

角色	常见用法
配置查询	导出广告源清单、按应用查广告位、导出列表 CSV
报表查询	综合报表用 `tp report v4`；LTV/留存用 `ltv`/`tpltv`/`retention`；用户指标用 `active-users`
技术支持	`auth scope` 确认客户 UUID 是否可见；`summarize app` 一眼看配置
研发 / 自动化	cron 定时拉数、CI/CD 流水线集成、脚本批量调用

不需要会写代码：会复制命令、替换 <app_uuid> 等占位符即可。需要精细参数时，用 tp <命令> --help 或本文 §11 命令参数速查。

5.2 建议的首次流程（约 5 分钟）

安装（见 §2）并执行 tp version。
配置凭证（见 §3）：在开发者后台「我的账号」复制 API Key（CLI 参数 --bear）和密钥（--secret）。

生产：base_url 使用 https://api-developer.tradplusad.com
测试/联调：使用贵司或 TradPlus 提供的测试网关与配套 API Key（勿与生产密钥混用）。

确认连的是自己的账号：

tp auth summarize

成功时能看到 visible_apps_total、visible_adseats_total 等摘要字段（输出格式见 §4.5）。 4. 试一条只读查询：

tp app list --format table --fields app_uuid,app_name,os

需要改配置时，先不要加 --yes，按 §9 写操作确认机制预演后再执行。

5.3 第一次在测试环境试跑

配置好密钥后，可参考 §4.5 终端输出示例，对照字段名与返回结构。

快速自检：执行 tp auth summarize 后 visible_apps_total 应大于 0；对已知广告位执行 tp placement list --currency USD --adseat-uuid "<编号>" 后应出现 placements 列表。

5.4 我想做什么？该复制哪条命令

不用记命令名，按目的选一行即可。将 <应用编号> / <广告位编号> 换成开发者后台实际值；练习时可使用 §1.1 示例编号。

我想…	复制这条
看账号下有多少应用	`tp auth summarize`
搜某个应用是否在权限内	`tp auth scope --app-uuid "<应用编号>"`
列出某应用下有哪些广告位	`tp adseat list --app-uuid "<应用编号>"`
列出某广告位下有哪些广告源	`tp placement list --currency USD --adseat-uuid "<广告位编号>"`
一眼看某应用接了几个广告网络、几条源	`tp summarize app --app-uuid "<应用编号>" --args '{"currency":"USD"}'`
查广告网络 ID（AdMob、Bigo 是几号）	`tp platform legacy`（见 §7.7.8）
拉某段日期的收入/展示	`tp report v4 --start 2026-05-01 --end 2026-05-07 --args '{"app_uuids":"<应用编号>","metrics":"revenue,impression,click","group_by":"date","currency":"USD"}'`
拉用户价值 LTV（广告网络 API）	`tp report ltv --start 2026-05-01 --end 2026-05-07 --args '{"app_uuids":"<应用编号>","metrics":"ltv1,ltv7,ltv30","group_by":"date,app"}'`
拉用户价值 LTV（TradPlus 统计）	`tp report tpltv --start 2026-05-01 --end 2026-05-07 --args '{"metrics":"all","group_by":"date,app"}'`
拉 cohort 留存（kp 指标）	`tp report retention --start 2026-05-01 --end 2026-05-07 --args '{"metrics":"kp1,kp7,kp30","group_by":"date,app"}'`
拉 DAU/DEU 等用户指标	`tp report active-users --start 2026-05-01 --end 2026-05-07 --app-uuid "<应用编号>"`
查看各广告网络授权摘要	`tp summarize platform --kind health --args '{"currency":"USD"}'`

6. 业务场景与工作流

下文按您平时在开发者后台做的事来写（查应用、查广告源、导出清单、看授权是否正常）。示例输出用于对照字段含义；名称与条数以您账号为准。

改配置前请记住：命令里先不要加 --yes，看清提示后再加，避免误改生产环境。

示例编号（测试环境，可选）

若您已开通测试环境，可将命令中的 <应用编号> / <广告位编号> 替换为 §1.1 中的示例 UUID 进行练习；正式环境请一律使用自己开发者后台的应用与广告位编号。

含义	示例编号（测试环境）
示例应用	`12E3E378A088B78EA80AAB035E244E06`
示例广告位	`0E27DC206544B7A6CE765F262F6B56C7`
示例广告源	`656437` 等，以您执行 `tp placement list` 的返回为准
Bigo / AdMob 广告网络 ID	`57` / `2`（`tp platform legacy` 可查完整表）

配置密钥（只需做一次，密钥向管理员索取，不要发群里或写进文档）：

tp config set \
  --bear "<您的 API Key>" \
  --secret "<您的密钥>" \
  --base-url "https://test-api-developer.tradplusad.com"

6.0 十分钟走读

按顺序操作一遍，相当于把「查应用 → 广告位 → 广告源 → 授权 → 报表」串起来。将 <应用编号> / <广告位编号> 换成您自己的，或 §1.1 示例编号中的测试环境示例值。

步	操作	通过标准
1	`tp auth summarize`	返回摘要，`visible_apps_total` > 0
2	`tp app get --app-uuid "<应用编号>"`	`app_list` 中应用名与开发者后台一致
3	`tp adseat list --app-uuid "<应用编号>"`	列出该应用下广告位（`adseat_list`）
4	`tp placement list --currency USD --adseat-uuid "<广告位编号>"`	`placements` 非空，条数与开发者后台该广告位一致
5	`tp summarize app --app-uuid "<应用编号>" --args '{"currency":"USD"}'`	`counts` 中广告位/广告源数量合理
6	`tp auth scope --app-uuid "<应用编号>"`	`app_access.visible` 为 true
7	`tp summarize platform --kind health --args '{"currency":"USD"}'`	各广告网络状态多为正常（输出中常为 `healthy`）
8	`tp report v4 --start … --end … --args '{"app_uuids":"<应用编号>","metrics":"revenue,impression,click","group_by":"date","currency":"USD"}'`	`code` 200；`items` 可为空（无流量时正常）

走完 8 步后，您已会用 CLI 完成日常「查清单 + 拉报表」。输出格式见 §4.5；导出说明见 §7.7。

场景 A：新项目接入（应用 → 广告位 → 广告源）

您要得到什么：从「应用是否存在」一路查到「某广告位下接了哪几条广告源、用的哪个授权账号」，确认配置就绪或便于复制配置。

步骤	做什么	命令
1	确认应用已在账号下	`tp app get --app-uuid "<应用编号>"`
2	只有商店链接、尚未建应用	`tp app probe --url "https://play.google.com/store/apps/details?id=com.example.app"`
3	列出应用下广告位	`tp adseat list --app-uuid "<应用编号>" --format json`
4	看广告位下所有广告源（含已关闭）	`tp placement list --currency USD --adseat-uuid "<广告位编号>" --args '{"is_on":-1}' --format json`
5	同应用下按广告网络筛广告源	`tp placement list-by-app --app-uuid "<应用编号>" --platform pangle`
6	看 AdMob 授权要填哪些字段	`tp account-template get --adsource-id 2`
7	一眼总览应用配置量	`tp summarize app --app-uuid "<应用编号>" --args '{"currency":"USD"}'`

走一遍后怎样算查对了

步骤	通过标准
1 查应用	`app_name`、`app_uuid` 与开发者后台「应用管理」一致
3 查广告位	`seat_name`、`ad_type` 与开发者后台广告位一致
4 查广告源	`placements` 条数与开发者后台该广告位下一致；含 `placement_id`、`adsource_id`、`account_name`
7 应用总览	`counts` 中广告位/广告源数量与前面步骤一致

新建应用/广告位/广告源为写操作，见 §11.7 与开发者后台管理 API。

场景 B：日常巡检（只读，不改数据）

您要得到什么：确认 API Key 能看见客户资源、应用/广告位在权限内、广告网络授权无大面积异常。不要加 --yes。

按顺序执行

① 账号能看见多少资源

tp auth summarize

应返回 visible_apps_total、visible_adseats_total 等字段且 > 0。若为 0，请检查密钥、base_url 是否配对。

② 指定应用是否在可见范围

tp auth scope --app-uuid "<应用编号>"

app_access.visible 应为 true；placement_access.matched_count 应与该应用下广告源数量大致一致。若不可见，需换有权限的 API Key 或联系管理员。

③ 单个广告位是否正常

tp summarize adseat --adseat-uuid "<广告位编号>" --args '{"currency":"USD"}'

应返回广告位名称、中介组数量等；无 A/B测试时 abtests 为空列表。

④ 各广告网络授权是否正常

tp summarize platform --kind health --args '{"currency":"USD"}'

列表里多数广告网络授权状态为正常（输出字段常为 healthy）即可；若有异常项，记录广告网络名称后联系 TradPlus 支持排查。

⑤ 抽查授权账号

tp token list

能看到多行「默认账号」及对应广告网络即可，用于核对是否接错授权。

怎样算查对了：目标应用在权限检查里为「可见」；广告位摘要与开发者后台一致；广告网络授权列表无大面积异常。

场景 C：导出清单与查询综合报表

您要得到什么：导出应用/广告源清单（管理 API），或按日期区间查询综合报表 items（报表 API）。

广告源清单

tp placement list --currency USD --adseat-uuid "<广告位编号>" \
  --format table --fields placement_id,name,adsource_id

步骤与字段说明见 §7.7.1。

应用名单

tp app list --limit 5 --format table --fields app_uuid,app_name

终端里 total 为账号下应用总数；列表中出现您关心的应用名即正常。

综合报表：执行 tp report v4 并指定起止日期。无流量时 items 可能为空；有数据时步骤见 §7.7.2。

怎样算查对了：广告源条数与开发者后台该广告位下一致；综合报表 items 行数与相同 start_date/end_date、group_by、metrics 条件下开发者后台综合报表大致相当。

场景 D：中介组与 A/B测试

您要得到什么：看清某广告位的中介组、组内 Header Bidding 区域与按价格排序区域（见开发者后台管理 API 中介组广告源列表返回结构），以及有没有进行中的 A/B测试。

步	复制执行（替换广告位编号）	通过标准
1	`tp intermediary list --adseat-uuid "<广告位编号>" --args '{"currency":"USD"}'`	返回中介组列表；`group_id` 0 常为默认「所有国家」组
2	`tp group-placement list --args '{"adseat_uuid":"<广告位编号>","currency":"USD","group_id":0}'`	含 `header_bidding_list`、`auto_optimization_list` 等块；具体结构因广告位配置而异
3	`tp abtest list --adseat-uuid "<广告位编号>"`	有 A/B测试则列出；无则为空列表

有 A/B测试时，记下 abtest_id（A/B测试 ID），再拉报表：

tp report abtest --abtest-id <A/B测试 ID> --start 2026-05-01 --end 2026-05-07
tp report confidence --abtest-id <A/B测试 ID> --start 2026-05-01 --end 2026-05-07

和开发者后台怎么对：中介组个数、组 ID 与开发者后台「中介组」一致；组内 Header Bidding 与按价格排序条数、顺序与开发者后台中介组广告源列表一致。注意：开启或关闭中介组广告源请用 group-placement toggle，不要用 intermediary upsert，否则可能误建新组。

场景 E：查广告网络 ID（对照开发者后台枚举）

您要得到什么：开发者后台或报表里写的「广告网络 ID」对应哪家广告网络；新建广告源前确认当前账号能不能接该广告网络。

① 广告网络 ID 对照表

tp platform legacy

测试环境常见编号（节选，完整列表以命令输出为准）：

编号	广告网络名称
1	Meta
2	AdMob
19	Pangle
57	Bigo

② 按「广告位类型 + 系统」看能接哪些广告网络

例如：横幅 + Android：

tp platform list --ad-type 4 --os 1

在结果里找目标广告网络名称；能否创建广告源以开发者后台管理 API 附录2（广告网络与广告位类型对照）及 tp account-template get 返回为准。

怎样算查对了：编号与开发者后台「广告网络」下拉一致；要接的广告网络在列表里且授权状态正常。

场景 F：改配置前先「预演」（不会真改）

您要得到什么：例如要关闭某条广告源，先确认系统提示的 placement_ids 无误，再决定是否真的执行。

第一步：只预演（不要加 --yes）

tp placement toggle --args '{"placement_ids":"<广告源编号>","is_on":0}'

终端会出现 dry-run 提示及 request: 行（含 placement_ids）；此时不会真正执行关闭。

第二步：确认无误后再执行（生产环境慎用）

tp placement toggle --args '{"placement_ids":"<广告源编号>","is_on":0}' --yes

怎样算查对了：预演里的 placement_ids 与 placement list 查到的编号一致；真正执行后再查广告源列表，状态与预期一致。删应用等重大操作请勿在生产环境自行尝试。

7. 综合报表查询与分析

若只需复制命令并导出 items 或列表数据，优先读 §7.7 与 §5.4；本节说明各 tp report 子命令与数据报表查询 API 的对应关系及 metrics/group_by 参数。

报表类命令通过 Bearer 鉴权（与开发者后台管理 API 的 Bear+Secret 签名方式不同，CLI 会自动处理）。tp report 子命令已覆盖数据报表查询 API 全部独立报表接口（§2 综合报表 V3、§3 V4、§4–§6 用户价值/留存、§7 A/B测试）。日常最常用 tp report v4；cohort 类 LTV/留存与 active-users（DAU/DEU）勿混用。

各类指标的业务含义见数据报表查询 API「注意事项」中的指标说明；下文侧重 CLI 怎么传参、返回长什么样。

7.1 选哪个报表子命令

数据报表查询 API 独立报表接口与 CLI 对照（均已支持）：

API 章节	接口路径	CLI 子命令
§2 综合报表 V3	`/v3/allreport`	`tp report v3`
§3 综合报表 V4	`/v4/allreport`	`tp report v4`
§4 用户价值（API）	`/v2/ltv`	`tp report ltv`
§5 用户价值（TP）	`/v2/tpltv`	`tp report tpltv`
§6 用户留存	`/v2/userActive`	`tp report retention`
§7.1 A/B 实验组	`/v4/abtestreport`	`tp report abtest`
§7.2 应用预估	`/v4/appforecastreport`	`tp report forecast`
§7.3 置信度	`/v4/abconfidencereport`	`tp report confidence`

另：tp report api / tp 对应 V4 单日三方 API / TradPlus 维度拆分；tp report active-users 为 DAU/DEU 封装（非 §6 cohort 留存）。

子命令	对应 API 能力	日期限制	说明
`report v3`	综合报表（V3）：与 v4 类似，旧版接口	支持跨天区间	见数据报表查询 API §2；新接入优先用 `v4`
`report v4`	综合报表（V4）：广告网络API收入、TradPlus统计展示/点击等，按日期、应用、广告网络、国家地区等聚合	支持跨天区间	见数据报表查询 API §3
`report api`	综合报表【三方API数据】：广告网络API请求/填充/展示等（与 TradPlus统计指标分开拉取）	仅单日（`start` 与 `end` 须同一天）	见数据报表查询 API §3（v4 三方 API）
`report tp`	综合报表【TradPlus数据】：TradPlus统计指标，可按渠道、SDK版本等维度拆分	仅单日	见 v4_api_tp.md §3
`report ltv`	用户价值 1-90 天（广告网络 API 数据，`ltv1`…`ltv90`）	跨天	见数据报表查询 API §4
`report tpltv`	用户价值 1-90 天（TradPlus 统计数据）	跨天	见数据报表查询 API §5
`report retention`	用户留存 2-90 天（`kp1`…`kp90`）	跨天	见数据报表查询 API §6
`report abtest`	A/B测试报表：各实验组对比数据	跨天	见数据报表查询 API §7.1
`report confidence`	置信度评估数据	依接口	见数据报表查询 API §7.3
`report forecast`	应用维度预估数据（需 A/B测试 ID）	依接口	见数据报表查询 API §7.2
`report active-users`	`dau`、`deu`、`arpu` 等 TradPlus统计用户指标	跨天	CLI 封装；与 `retention`（cohort 留存）不同

不要混用：revenue 为广告网络API收入，impression 在综合报表中为 TradPlus统计的展示数；dau/deu 等为 TradPlus统计用户指标，定义见数据报表查询 API。

7.2 通用参数

参数	CLI 写法	含义	示例
开始/结束日期	`--start` / `--end`	对应接口 `start_date` / `end_date`，格式 `YYYY-MM-DD`	`--start 2026-05-01 --end 2026-05-07`
应用	`--app-uuid` 或 `--args` 里 `app_uuids`	单个应用用 flag；多个用逗号分隔 UUID	`--app-uuid "15E829568BD3AD80AFBE7662A5535A25"`
广告位	`--adseat-uuid` 或 `adseat_uuids`	缩小到某一广告位	与列表命令中的 UUID 相同
指标	`--args '{"metrics":"..."}'`	逗号分隔；不传时多为 `all`	`revenue,impression,click`
聚合维度	`--args '{"group_by":"..."}'`	决定每一行代表什么粒度	`date`、`date,adsourceId`、`date,country`
货币	`currency`	`USD` 或 `CNY`（大写）	币种示例 USD
时区	`timezone`	如 `UTC+8`	与开发者后台报表时区对齐时使用
国家地区	`country` 或 `areas`	综合报表映射为 `area`；LTV/留存映射为 `areaList`	`CN,US`
分页	`start` / `limit`（在 `--args` 中）	LTV/留存单次最多 1000 条；V3/V4 综合报表 `limit` 最大 20000	`"start":0,"limit":1000`

日期、指标、分组等也可全部放在 --args 中（与 flag 合并时，同名字段以 --args 为准）。

LTV / 留存专用：group_by 须包含 date 与 app（CLI 默认 date,app）；metrics 分别为 ltv1…ltv90 或 kp1…kp90，可传 all。

7.2.1 CLI 与 API 字段对照（报表）

CLI 在发送请求前会把 flags / --args 转为接口 JSON。下表左侧为 CLI 写法，右侧为数据报表查询 API 中的字段名（HTTP body 多为 camelCase，CLI --args 用 snake_case）：

CLI / `--args`	API 字段（综合报表）	说明
`--start` / `--end`	`startDate` / `endDate`	日期 `YYYY-MM-DD`
`--app-uuid` 或 `app_uuids`	`appIdList`	多应用逗号分隔 UUID
`metrics`	`metric`	逗号分隔指标名；默认 `all`
`group_by`	`groupBy`	逗号分隔维度；默认 `date`
`currency`	`currency`	`USD` 或 `CNY`
`timezone`	`timezone`	`UTC+8` / `UTC+0` / `UTC-8`
`country` / `areas`	`area`（综合报表）或 `areaList`（LTV/留存）	ISO 3166-1 二位国家地区代码
`start` / `limit`（分页）	`start` / `limit`	偏移量与每页条数，见 §7.2.2
`bid_type`	`bidType`	`1` 常规、`2` 竞价；不传为全部
`--abtest-id`	`abtestId`	A/B测试报表必填

综合报表返回中，收入字段在 API 样例里写作 Revenue，CLI 输出中常见小写 revenue；以实际 JSON 为准。

7.2.2 分页拉取大量数据

数据报表查询 API 要求：数据需要拉取到没有返回为止，通过 start 偏移量翻页。

报表类型	`limit` 上限	建议
综合报表 V3/V4	20000	当 `total` 大于已拉取行数时，递增 `start` 继续请求
LTV / 留存	1000	同上

示例：第一页 1000 条，第二页从第 1001 条起：

tp report v4 --start 2026-05-01 --end 2026-05-31 \
  --args '{"metrics":"revenue,impression","group_by":"date,appId","currency":"USD","start":0,"limit":1000}' \
  --format json

tp report v4 --start 2026-05-01 --end 2026-05-31 \
  --args '{"metrics":"revenue,impression","group_by":"date,appId","currency":"USD","start":1000,"limit":1000}' \
  --format json

7.3 常用指标与分组（V4）

指标 metrics — 完整枚举见数据报表查询 API §2.3 / §3.3；可传 all 拉取全部。按数据源分为两类，不要混读：

类别	指标名（节选）	业务含义
广告网络 API	`revenue`、`requestApi`、`fillApi`、`fillrateApi`、`impressionApi`、`clickApi`、`ecpmApi`、`ctrApi`、`bidRequestApi`、`bidResponseApi`、`bidResponseRateApi`、`bidWinRateApi`	三方广告网络回传数据
TradPlus 统计	`dau`、`deu`、`arpu`、`newUsers`、`appRequest`、`enterAdScene`、`request`、`fill`、`impression`、`click`、`ctr`、`bidRequest`、`bidResponse`、`eventRevenue` 等	SDK 埋点统计
维度伴随字段	`sdk`、`channel`、`appVersion`、`idfa`、`bucketName`、`countryName`	常与对应 `group_by` 一起返回

日常最常用：revenue（API 收入）、impression / click（TradPlus 展示/点击）、dau / deu（用户指标）。

分组 group_by — 完整列表见 API 文档；CLI 逗号分隔写法与 API groupBy 数组等价：

维度	CLI 常见写法	说明
`date`	`date`	按日期（默认）
`appId`	`appId`	按应用
`placementId`	`placementId` / `adseat_uuid`	按广告位
`adFormat`	`adFormat`	按广告类型
`area`	`area` / `country`	按国家地区（ISO 3166-1 二位代码）
`network`	`network` / `adsourceId`	按广告网络
`networkPlacementId`	`networkPlacementId`	按广告网络 API 广告位
`adSceneId`	`adSceneId`	按广告场景
`sdk` / `channel` / `appVersion` / `idfa` / `bucketId`	同名	见下表限制

维度与广告网络 API 的限制（与 API 文档一致）：adSceneId、sdk、channel、appVersion、idfa、bucketId 等维度不支持广告网络 API 统计；选中后不会返回 requestApi/revenue 等 API 侧指标，仅保留 TradPlus 统计字段。

7.3.1 用户价值与留存（`ltv` / `tpltv` / `retention`）

对应数据报表查询 API §4–§6；与综合报表 revenue/impression 不是同一套指标。

子命令	数据源	指标 `metrics`	典型返回字段
`report ltv`	广告网络 API	`ltv1`…`ltv90` 或 `all`	`newUserNum`、`ltv7` 等
`report tpltv`	TradPlus 统计	同上	同上
`report retention`	cohort 留存	`kp1`…`kp90` 或 `all`	`newUserNum`、`kp7` 等

分组 group_by：date、app 为必填维度（CLI 默认 date,app）；可选 area、placementId、appVersion、channel（见 API 文档）。

子命令	与下列命令的区别
`ltv` vs `tpltv`	前者为广告网络 API 用户价值，后者为 TradPlus 统计用户价值
`retention` vs `active-users`	`retention` 为新增用户 cohort 的 `kp` 留存；`active-users` 为 `dau`/`deu` 等日活类指标

数据更新时间（综合报表 §2.4 / §3.4；LTV/留存 §4、§6 备注）：

时区	完整数据更新时间（北京时间）
UTC+8	当日 21:00
UTC+0	当日 20:00
UTC-8	次日 02:00

查询「昨天」数据时，若未到上述时间点，items 可能为空或不全。广告网络 API 另有各平台时区差异，见三方广告网络时区说明。

7.4 业务示例命令（测试环境）

以下示例在测试环境执行，应用 UUID 与 §6 场景 A 一致；您可将编号替换为自己账号下的应用编号。生产账号有流量时，items 会有数据行；测试环境常见 **items: [] 但 code: 200**，表示请求成功、仅该区间无统计。

示例 1：综合报表 — 按 date 查询 revenue/impression/click（单应用）

您要得到什么：按 group_by":"date" 返回的 items，每天一行（与数据报表查询 API 综合报表一致）。

tp report v4 \
  --start 2026-05-01 --end 2026-05-07 \
  --args '{"app_uuids":"12E3E378A088B78EA80AAB035E244E06","metrics":"revenue,impression,click","group_by":"date","currency":"USD"}' \
  --format json

无流量时常见：code 200，total 0，items 为空——表示查询成功、只是该区间没有数据（见 §7.7.2）。

正式环境有量时：items 里每天一行，结构见 §7.7.9 表 A。

怎样算查对了：code 为 200；group_by 含 date 时每行有日期字段；7 天区间行数与开发者后台筛选大致相当。

示例 2：按 date + network 聚合查询

您要得到什么：看清「哪天、哪个广告网络（network/adsourceId）贡献多少 revenue（广告网络API收入）」，对应综合报表 groupBy 含 network 维度。

tp report v4 \
  --start 2026-05-01 --end 2026-05-07 \
  --args '{"app_uuids":"12E3E378A088B78EA80AAB035E244E06","metrics":"revenue,impression","group_by":"date,adsourceId","currency":"USD"}' \
  --format json

有数据时每一行会同时有「日期」和「广告网络 ID」（如 57 表示 Bigo，见场景 E）。完整命令见 §7.7.2。

示例 3：综合报表【三方API数据】— 单日按广告网络查询

您要得到什么：某一天、各广告网络 requestApi/fillApi/impressionApi 等广告网络API指标，须与 report v4 区分；且 start 与 end 必须是同一天。

tp report api --start 2026-05-07 --end 2026-05-07 \
  --args '{"app_uuids":"12E3E378A088B78EA80AAB035E244E06","metrics":"requestApi,fillApi,impressionApi","group_by":"adsourceId"}' \
  --format json

怎样算查对了：仅当 start=end；返回行按广告网络（network/adsourceId）拆分；指标字段见 API 文档 fillrateApi、requestApi、impressionApi 等。

示例 4：A/B测试 — 分组对比与置信度评估

您要得到什么：A/B测试各分组的收入/展示差异，以及置信度评估结果。

# 先查 abtest_id（示例广告位下可能无 A/B测试，返回空数组属正常）
tp abtest list --adseat-uuid "0E27DC206544B7A6CE765F262F6B56C7" --format json

# 若有 A/B测试，例如 abtest_id=3267：
tp report abtest --abtest-id 3267 --start 2026-05-01 --end 2026-05-14 --format json
tp report confidence --abtest-id 3267 --start 2026-05-01 --end 2026-05-14 --format json

怎样算查对了：abtest 报表按 bucket_id（A/B分组）出数；confidence 返回置信度评估数据，样本不足时可能无有效统计。

有数据时 abtest 响应结构与数据报表查询 API §7.1.5 一致，例如：

{
  "code": 200,
  "items": [
    {
      "adseat_uuid": "C9426BEC900CB2E6A8E8C671AA8BFB12",
      "adseat_name": "插屏",
      "bucket_id": "8431",
      "bucket_name": "A组",
      "dau": 10,
      "deu": 20,
      "income": 4,
      "impression": 8,
      "est_ecpm": 500
    }
  ]
}

confidence 返回各分组的 arpu、status（1 可信 / 0 不可信）等，基准组部分字段为 -，见 API §7.3.5。

示例 5：用户指标 — DAU / DEU（勿与 revenue 混用）

您要得到什么：按天的 dau（TradPlus统计的日活跃用户数量）、deu（TradPlus统计的每日观看广告用户数）等，不是 revenue（广告网络API收入）。

tp report active-users \
  --start 2026-05-01 --end 2026-05-07 \
  --app-uuid "12E3E378A088B78EA80AAB035E244E06" \
  --format json

测试环境可能同样返回 "items": []。指标名须与接口一致（如 dau、deu）；若报 [10007] Invalid Metric，先省略 metrics 用默认 all，再根据返回字段收窄。完整指标列表见数据报表查询 API 综合报表 metric 参数说明。

示例 6：用户价值 LTV — 广告网络 API 与 TradPlus 统计

您要得到什么：按新增用户 cohort 查看第 1、7、30 天累积收益（ltv1/ltv7/ltv30）。ltv 与 tpltv 数据源不同，请与开发者后台「用户价值」页面对照选用。

# 广告网络 API 数据（§4）
tp report ltv --start 2026-05-01 --end 2026-05-07 \
  --args '{"app_uuids":"12E3E378A088B78EA80AAB035E244E06","metrics":"ltv1,ltv7,ltv30","group_by":"date,app","currency":"USD"}' \
  --format json

# TradPlus 统计数据（§5）
tp report tpltv --start 2026-05-01 --end 2026-05-07 \
  --args '{"app_uuids":"12E3E378A088B78EA80AAB035E244E06","metrics":"all","group_by":"date,app"}' \
  --format json

怎样算查对了：返回含 timezone 与 items；每行有 date、appId、newUserNum 及所请求的 ltv* 字段。测试环境 items 为空仍可能表示查询成功。

示例 7：用户留存 — cohort kp 指标（勿与 active-users 混用）

您要得到什么：新增用户在第 1、7、30 天的留存率（kp1/kp7/kp30），对应数据报表查询 API §6。

tp report retention --start 2026-05-01 --end 2026-05-07 \
  --args '{"app_uuids":"12E3E378A088B78EA80AAB035E244E06","metrics":"kp1,kp7,kp30","group_by":"date,app"}' \
  --format json

怎样算查对了：返回 items 中含 kp* 字段；与 tp report active-users 的 dau/deu 不是同一接口。

7.5 返回结果怎么读

综合报表（v3/v4 等） 成功时 JSON 常见结构（与数据报表查询 API §3.5 响应样例一致）：

{
  "code": 200,
  "total": 7,
  "timezone": "UTC+8",
  "items": [
    {
      "date": "2021-07-01",
      "appId": "6640E7E3BDAC951B8F28D4C8C50E50B5",
      "placementId": "B514A432CE5E96A44BD2E313AC3323AB",
      "placementName": "Banner_1",
      "requestApi": 19433,
      "fillApi": 150,
      "fillrateApi": 0.13,
      "impressionApi": 1989,
      "revenue": 6.59,
      "dau": 679,
      "deu": 223,
      "impression": 44106,
      "click": 20358,
      "ctr": 0.4616
    }
  ]
}

仅当 group_by 包含对应维度时，才返回 appId、placementName、network、area 等维度字段；未请求的 metrics 对应数值可能省略。

用户价值（ltv/tpltv） 响应通常仅含 timezone 与 items（无 code/total），见 API §5.5：

{
  "timezone": "UTC+0",
  "items": [
    {
      "date": "2021-07-01",
      "appId": "6640E7E3BDAC951B8F28D4C8C50E50B5",
      "appName": "Banner_1",
      "newUserNum": 2,
      "ltv1": 9.54,
      "ltv7": 0,
      "ltv30": 0
    }
  ]
}

用户留存（retention） 结构类似，指标为 kp1…kp90，见 API §6.5：

{
  "timezone": "UTC+0",
  "items": [
    {
      "date": "2021-07-01",
      "appId": "FDC48B1D9D9E1F5CBD0C327159C8191C",
      "appName": "Banner_1",
      "kp1": 2.31,
      "kp7": 0,
      "kp30": 0
    }
  ]
}

字段	说明
`code`	综合报表 / A/B测试中 `200` 表示请求成功；LTV/留存接口可能不返回此字段
`message`	失败时的提示；成功时可能省略
`items`	数据行；`group_by` 越多，每行维度字段越多
`total`	综合报表总条数，用于分页；LTV/留存接口可能不返回
`items` 为空	可能原因：该区间无数据、应用无流量、测试账号无填充、筛选过窄、未到数据更新时间；先用更大日期范围或不带 `app_uuids` 试查

状态码含义见数据报表查询 API「code 状态码定义」。结果与开发者后台不一致时，先统一 timezone、currency、start_date/end_date、group_by、metrics。

7.6 查询综合报表（推荐顺序）

tp auth summarize — 看账号下可见应用、广告位规模。
tp app list — 找到目标应用名称，记下应用编号。
tp adseat list --app-uuid <应用编号> — 找到广告位名称，记下广告位编号。
tp placement list --currency USD --adseat-uuid <广告位编号> — 核对广告源条数与开发者后台一致。
tp report v4 --start … --end … — 拉选定日期的广告网络API收入与 TradPlus统计展示；按广告网络拆分见 §7.7.2。

7.7 导出与综合报表查询示例

命令中的 <应用编号>、<广告位编号> 请替换为您开发者后台的实际值；练习时可使用 §1.1 示例编号。

哪些能直接导出、哪些要解析 JSON

导出类型	推荐命令写法	说明
应用/广告位/广告源清单	`--format table` 或 `--format csv --fields …`	列表类命令可直接对齐列导出或保存为 CSV
综合报表（`report v3`/`v4` 等）	先 `--format json` 或 `compact`，取 `items` 数组	数据在 `items` 里；可用 `--format csv --fields date,revenue,…`（有数据时）
LTV / 留存（`ltv`/`tpltv`/`retention`）	`--format json`，取 `items`	可用 `--format csv --fields date,appId,ltv7,…` 或 `kp7,…`（有数据时）

两类常见需求：

您要导出的内容	建议做法
广告源清单	见 7.7.1
综合报表	见 7.7.2

7.7.1 示范一：导出某广告位下的广告源清单

您要得到什么：和开发者后台「广告源列表」类似的一张表——每条源有名称、广告网络、用的哪个授权账号。

第一步：复制下面整段到终端执行（替换广告位编号）

tp placement list \
  --currency USD \
  --adseat-uuid "<广告位编号>" \
  --format table --fields placement_id,name,adsource_id,account_name

也可不加 --format，在 compact / JSON 输出中查看 placements 数组（格式见 §4.5 步骤 4）。

第二步：核对条数与字段

终端字段	对应后台
`placement_id`	广告源编号
`name`	广告源名称
`adsource_id`	广告网络 ID（如 57 表示 Bigo）
`account_name`	授权账号名称

怎样算成功了：placements 条数与开发者后台该广告位下一致；各字段与开发者后台列表可对上。

想先看清应用里总共有几个源、几个广告位：

tp summarize app --app-uuid "<应用编号>" --args '{"currency":"USD"}'

保存为 CSV 文件：

tp placement list --currency USD --adseat-uuid "<广告位编号>" \
  --format csv --fields placement_id,name,adsource_id,account_name \
  > ~/Desktop/placements.csv

7.7.2 示例：查询综合报表（按 date 聚合）

您要得到什么：例如 5 月 1 日～7 日，每天收入、展示、点击各多少；或按「日期 + 广告网络」拆成多行，对应 group_by":"date,adsourceId"（network 维度）。

第一步：复制命令（日期可按需改）

tp report v4 \
  --start 2026-05-01 \
  --end 2026-05-07 \
  --args '{"app_uuids":"12E3E378A088B78EA80AAB035E244E06","metrics":"revenue,impression,click","group_by":"date","currency":"USD"}'

与数据报表查询 API §3.5 请求样例等价的 CLI 写法（按日期 + 应用 + 广告位、metrics 为 all）：

tp report v4 --start 2021-07-01 --end 2021-07-07 \
  --args '{"timezone":"UTC+8","currency":"USD","group_by":"date,appId,placementId","metrics":"all","start":0,"limit":1000}' \
  --format json

第二步：看终端返回

无流量数据或测试账号时，常见：

"code": 200,
"total": 0,
"items": []

您看到的	含义
`"code": 200`	查询成功，密钥和日期没问题
`"total": 0` 且 `items` 是空的 `[]`	这个测试应用在所选日期没有统计行，不是命令写错
正式有流量的账号	`items` 里会出现多行数字，可做成下表

正式环境有数据时，Excel 里大致长这样（数字仅为示意）：

日期	收入（美元）	展示	点击
2026-05-01	12.50	3200	48
2026-05-02	15.10	4100	52

按 date + network 聚合（同一天里 AdMob、Bigo 各一行）：在 --args 中设置 "group_by":"date,adsourceId"（对应综合报表 network 维度），例如：

tp report v4 --start 2026-05-01 --end 2026-05-07 \
  --args '{"app_uuids":"<应用编号>","metrics":"revenue,impression","group_by":"date,adsourceId","currency":"USD"}' \
  --format csv --fields date,adsourceId,revenue,impression

广告网络 ID见 tp platform legacy（57=Bigo，2=AdMob，见场景 E）。

怎样算成功了：code 为 200；正式环境里 items 里行数和开发者后台报表天数、筛选条件大致相当。若和开发者后台对不上，先确认：美元还是人民币、时区是否和开发者后台一致、日期是否选对（报表常有 1～2 天延迟）。

7.7.3 示范三：导出「应用列表」做盘点

您要得到什么：账号下有哪些应用、叫什么名字。

tp app list --limit 5 --format table --fields app_uuid,app_name,os

怎样算成功了：total 大于 0，且能搜到您关心的应用名。

导出全部应用（自动翻页）：

tp app list --all --format csv --fields app_uuid,app_name,os > ~/Desktop/apps.csv

7.7.4 其他常用导出（一句话说明）

需求	您该执行的命令
只看账号下有多少应用、广告位	`tp auth summarize` → 看 `visible_apps_total`、`visible_adseats_total`
TradPlus统计用户指标（dau/deu 等，不是 `revenue`）	`tp report active-users --start 2026-05-01 --end 2026-05-07 --app-uuid "<应用编号>"`
用户价值 LTV（1–90 天）	`tp report ltv` 或 `tp report tpltv`（数据源不同，见 §7.3.1）
cohort 留存（kp 指标）	`tp report retention --start … --end … --args '{"metrics":"kp1,kp7","group_by":"date,app"}'`
某一天的各广告网络 API 数据	`tp report api`，开始日期和结束日期必须是同一天
旧版 V3 综合报表	`tp report v3`（新接入优先用 `v4`）
A/B测试报表	先 `tp abtest list` 查到 `abtest_id`，再 `tp report abtest`

7.7.5 导出与查询常见问题

情况	说明
综合报表 `items` 为空	测试环境很常见；换正式密钥和有流量的应用、日期再试
和开发者后台数字差一点点	核对是否同为美元、同一时区；等 1～2 天再对昨日数据
不知道广告网络 ID对应谁	执行 `tp platform legacy`，测试环境可看到如 `57 → Bigo`、`2 → AdMob`
想要 Excel 但不会转文件	列表类用 `--format csv`（见 7.7.1、7.7.3）；报表类在 `items` 有数据时用 `--format csv --fields …`（见 7.7.2）

说明：综合报表返回结构中，数字在 items 数组内。items 为空时 CSV 也只有表头；请先确认日期区间内有流量，或改用 json 查看 code 是否为 200。

7.7.6 常用命令组合示例

下列命令分别对应鉴权摘要、广告网络授权、配置列表与综合报表查询。

顺序	命令	看什么
1	`tp auth summarize`	应用总数、广告位总数
2	`tp summarize platform --kind health --args '{"currency":"USD"}'`	各广告网络授权是否正常
3	`tp token list`	授权账号是否齐全、有无明显重复
4	`tp summarize app --app-uuid "<重点应用编号>" --args '{"currency":"USD"}'`	抽查应用：几个广告位、几条源、接了哪些广告网络
5	`tp report v4 --start <开始日期> --end <结束日期> --args '{"metrics":"revenue,impression","group_by":"date","currency":"USD"}'`	综合报表 `items`（测试环境可能为空）

7.7.7 一张表导出「某应用下所有广告位」

命令

tp adseat list --app-uuid "<应用编号>" \
  --format table --fields adseat_uuid,seat_name,ad_type

保存为 CSV/表格的列建议：adseat_uuid（广告位编号）、seat_name（名称）、ad_type（类型，与后台对照）。

多个应用时：对每个应用编号各执行一次 tp adseat list。

7.7.8 广告网络 ID 速查

执行 tp platform legacy 可打印完整表；权威列表见数据报表查询 API「广告网络ID」附录。节选：

编号	名称
1	Facebook
2	Admob
5	Unity Ads
9	Applovin
10	IronSource
19	Pangle
57	Bigo

综合报表 group_by 含 network 时，返回字段为 network（广告网络 ID）与 networkName（广告网络名字）。

7.7.9 常见 `groupBy` 返回结构示意

正式环境有流量后，items 里每一行对应表格一行。测试环境多为空，可先熟悉「表头长什么样」。

表 A：group_by 为 date

日期	`revenue`	`impression`	`click`
2026-05-01	…	…	…

对应命令：group_by 为 date（见 7.7.2）。revenue 为广告网络API收入，impression/click 为 TradPlus统计指标。

表 B：group_by 为 date + network

日期	`network`	`networkName`	`revenue`	`impression`
2026-05-01	57	Bigo	…	…
2026-05-01	2	Admob	…	…

需在 --args 里把 group_by 设为 date,adsourceId（完整命令见 7.7.2）。

表 C：group_by 含 area

日期	`area`	`revenue`	`impression`
2026-05-01	US	…	…

group_by 使用 date,area（CLI 可写作 country）；area 为 ISO 3166-1 二位国家地区代码。

7.7.10 把结果保存成文件发给同事

不想在聊天里贴长输出时，可把结果写到文件（路径可自改）：

tp placement list --currency USD --adseat-uuid "<广告位编号>" > ~/Desktop/placement-list.txt
tp report v4 --start 2026-05-01 --end 2026-05-07 \
  --args '{"app_uuids":"<应用编号>","metrics":"revenue,impression,click","group_by":"date","currency":"USD"}' \
  > ~/Desktop/report-20260501-07.txt

把 ~/Desktop/*.txt 发给同事时，说明要对的是哪个应用、哪段日期即可。勿把含 API Key / 密钥的命令行写进群聊；凭证只放在本机配置里（§3）。

8. 输出格式与通用参数

怎么选输出格式

您要做什么	建议
在终端自己看一眼	不加 `--format`，或 `--format compact`
粘贴到 Excel	列表类用 `--format csv`（见 §7.7.1）；报表类见 §7.7.2
保存为文件再处理	使用 `> 文件路径` 重定向，或用 `--format csv` 直接生成表格文件
列很多、在终端对齐浏览	`--format table --fields col1,col2`

常用全局参数：

参数	说明
`--format compact`	简洁文本，适合人工查看
`--format table`	表格输出，适合终端查看
`--format json`	JSON 输出，适合脚本处理
`--format jsonl`	一行一个 JSON，适合流式处理
`--format csv`	CSV 输出，适合导入 Excel 或数据工具
`--fields`	逗号分隔字段名，用于控制列表输出字段
`--args`	JSON 对象字符串，用于传入复杂参数
`--yes`	确认执行写操作
`--print-request`	写操作执行前打印最终请求参数，便于核对
`--readonly`	只读模式：隐藏写子命令（与 `TP_READONLY=true` 等效，须显式开启）

示例：

tp app list --format table
tp app list --format json
tp app list --format csv --fields app_uuid,app_name,platform
tp adseat list --app-uuid "<app_uuid>" --format table --fields adseat_uuid,seat_name,ad_type

部分参数需要数字类型，例如 ad_type、os、adsource_id、api_token_id 等。使用 --args 传 JSON 时，应传数字而不是字符串：

tp platform list --args '{"ad_type":4,"os":1}'

不要写成：

tp platform list --args '{"ad_type":"4","os":"1"}'

8.1 参数传递规范（必读）

tp 不支持 在命令末尾用 参数名参数值 的 positional 方式传参。下列写法均无效：

# ❌ 错误：currency 不会被识别
tp placement list currency USD

# ❌ 错误：key value 顺序写法无效
tp adseat list app_uuid abc123

应使用 **--flag** 或 **--args JSON**：

# ✅ 使用子命令 flags
tp placement list --currency USD
tp adseat list --app-uuid "abc123"

# ✅ 使用 --args（字段名与 API 文档一致，snake_case）
tp placement list --args '{"currency":"USD","adseat_uuids":"<uuid>","is_on":-1}'

传递方式	字段命名	适用场景
子命令 flags	kebab-case，如 `--adseat-uuid`、`--app-uuids`	常用筛选；见各命令 `--help`
`--args` JSON	snake_case，如 `adseat_uuids`、`start_date`	子命令未暴露的字段、写操作复杂 body
全局 flags	`--format`、`--fields`、`--yes` 等	输出格式与写确认

合并规则：子命令先把 flags 写入参数 map，再合并 --args；同名字段以 --args 为准。

查找命令参数的两种方式：

tp <子命令> --help — 该子命令已注册的 flags 与示例
本文 §11 命令参数速查 — 子命令与 API 字段对照表

参数校验失败时，CLI 会输出与接口文档一致的参数说明（含必填项表格）；其中 currency: USD 表示 JSON 字段，不是 shell positional 写法。

8.2 flag 与 API 字段对照（常见）

CLI flag	`--args` / API 字段	说明
`--app-uuid`	`app_uuid` 或 `app_uuids`	单值查详情时常映射为 `app_uuids`
`--adseat-uuid`	`adseat_uuids`	列表接口多为复数字段
`--currency`	`currency`	取值 `USD` 或 `CNY`（大写）
`--start` / `--end`	`start_date` / `end_date`	报表日期，格式 `YYYY-MM-DD`
`--placement-id`	`placement_ids`	单 ID 查询
`metrics` / `group_by`（`--args`）	`metric` / `groupBy`（报表 API）	逗号分隔；详见 §7.2.1
`start` / `limit`（`--args` 分页）	`start` / `limit`	报表翻页偏移与条数；勿与 `--start` 日期 flag 混淆
`--abtest-id`	`abtestId`	A/B测试报表必填

8.3 Shell 与 `--args` 引号

--args 的值必须是 单个 JSON 对象字符串。不同 Shell 引号规则如下：

Shell	推荐写法	说明
bash / zsh	`--args '{"currency":"USD"}'`	外层单引号，JSON 内双引号
bash / zsh	`--args "{\"currency\":\"USD\"}"`	外层双引号时需转义内部 `"`
PowerShell	`--args '{\"currency\":\"USD\"}'` 或 `--args "{`"currency`":`"USD`"}"`	避免 PowerShell 解析 `{}`
cmd.exe	使用 `--args "{\"currency\":\"USD\"}"`	或改用 `@file.json` 思路：先写文件再 `type file`

数字字段在 JSON 中不要加引号："is_on":-1、"ad_type":4。
布尔 API 多用 0/1 整数，而非 JSON true/false。

合并 flags 与 --args 示例：

# flags 提供 currency，--args 补充 is_on（二者合并后发送）
tp placement list --currency USD --args '{"is_on":-1}' --format json

# 同名字段时 --args 覆盖 flags（不推荐混用，易混淆）
tp placement list --currency CNY --args '{"currency":"USD"}'   # 最终 currency=USD

9. 写操作确认机制

为了避免误改生产环境数据，写操作默认只做预演（dry-run），不会真正提交。需要确认执行时添加 --yes。

示例：

# 仅 dry-run，不真正删除
tp app delete --args '{"app_uuid":"<app_uuid>"}'

# 打印最终请求参数，核对后再决定是否执行
tp app delete --print-request --args '{"app_uuid":"<app_uuid>"}'

# 确认后真正执行
tp app delete --args '{"app_uuid":"<app_uuid>"}' --yes

建议生产环境写操作都按 “dry-run → 核对参数 → --yes” 的顺序执行。

10. 功能列表

以下为当前 CLI 已提供的主要命令。具体参数以 tp <命令> --help 为准。业务向场景说明见 §6、报表见 §7。

10.1 配置、鉴权与 CLI 辅助命令

下列 auth *、summarize * 为 CLI 辅助命令，用于本地快速查看权限与配置摘要，不在开发者后台管理 API 公开章节中；字段以命令返回为准。

命令	说明
`tp config set`	写入本地配置
`tp config get`	查看本地配置，敏感字段会脱敏
`tp version` / `tp --version`	查看 CLI 版本
`tp auth summarize`	查看当前凭证可见资源摘要（CLI 辅助）
`tp auth scope`	校验凭证对应用、广告源的访问范围（CLI 辅助）
`tp summarize app`	单应用配置摘要（CLI 辅助）
`tp summarize adseat`	单广告位摘要（CLI 辅助）
`tp summarize platform`	广告网络授权或使用摘要（CLI 辅助）

10.2 应用、广告位与广告场景

命令	说明
`tp app list`	查询应用列表
`tp app get`	查询单个应用详情
`tp app probe`	根据应用商店链接探测应用信息
`tp app create` / `update` / `delete`	创建、更新、删除应用
`tp adseat list`	查询应用下广告位
`tp adseat get`	查询广告位详情
`tp adseat create` / `update`	创建、更新广告位
`tp adscene list`	查询广告场景
`tp adscene upsert`	创建或更新广告场景

10.3 广告源、广告网络与授权

命令	说明
`tp placement list`	查询广告源列表
`tp placement get`	查询广告源详情
`tp placement list-by-app`	按应用查询广告源，便于复用配置
`tp placement upsert`	创建或更新广告源
`tp placement toggle`	启用或停用广告源
`tp platform legacy`	查询广告网络 ID 列表
`tp platform list`	按广告类型和系统查询可用广告网络列表
`tp token list` / `get` / `update`	查询或更新 API Token
`tp account-template get`	查询广告网络授权字段模板
`tp account-template save`	保存广告网络授权信息

查询广告网络 ID 示例：

tp platform legacy --format table --fields adsource_id,name
tp platform list --ad-type 4 --os 1 --format table

其中 tp platform legacy 对应开发者后台管理 API §9.3 广告网络查询；tp platform list 按广告位类型与系统过滤可用广告网络，创建前请对照附录2。

10.4 中介组与 A/B测试

命令	说明
`tp intermediary list`	查询广告位下中介组
`tp intermediary upsert`	创建或更新中介组
`tp intermediary reorder`	调整同一广告位 / AB 分组下自定义中介组优先级
`tp group-placement list`	查询中介组广告源列表
`tp group-placement update`	批量修改中介组广告源属性
`tp group-placement toggle`	开启或关闭中介组广告源
`tp abtest list`	查询 A/B测试列表
`tp abtest create` / `modify` / `start` / `close`	创建、修改、启动或关闭 A/B测试

10.5 报表

命令	说明
`tp report v2`	查询综合报表 V2（旧版；不支持中介组过滤）
`tp report v3`	查询综合报表 V3（跨天，旧版）
`tp report v4`	查询综合报表 V4（跨天）
`tp report api`	查询综合报表【三方API数据】（仅单日）
`tp report tp`	查询综合报表【TradPlus数据】（仅单日）
`tp report ltv`	查询用户价值 1-90 天（广告网络 API）
`tp report tpltv`	查询用户价值 1-90 天（TradPlus 统计）
`tp report retention`	查询用户留存 2-90 天
`tp report abtest`	查询 A/B测试报表（各实验组对比）
`tp report forecast`	查询应用维度预估数据
`tp report confidence`	查询置信度评估数据
`tp report active-users`	查询 TradPlus统计用户指标（dau/deu 等）
`tp report funnel`	广告漏斗（开发者网关）
`tp report sdk-event` / `sdk-event-detail`	SDK 事件汇总 / 下钻（开发者网关）

业务说明、指标与示例见 §7 综合报表查询与分析。网关路由见 §3.4。快速示例：

tp report v4 --start 2026-05-01 --end 2026-05-07 --format json
tp report ltv --start 2026-05-01 --end 2026-05-07 --app-uuid "<app_uuid>" --format json
tp report user-arpu --start 2026-05-01 --end 2026-05-07 --app-uuid "<app_uuid>" --format json
tp report device --date 2026-05-01 --app-uuid "<app_uuid>" --format json
tp report active-users --app-uuid "<app_uuid>" --start 2026-05-01 --end 2026-05-07 --format csv

用户价值、留存类报表支持通过 --args 传入 metrics、group_by、areas、channels 等筛选条件，完整字段见数据报表查询 API 文档。

7.6 字典数据

命令	说明
`tp meta categories`	查询应用分类
`tp geo regions`	查询国家或地区
`tp geo cities`	查询城市，可按地区过滤

11. 命令参数速查

本节面向需要核对 API 字段名 与 CLI 传参方式 的读者；日常业务优先看 §6、§7。
参数表格式与开发者后台管理 API 文档一致，列出各子命令的请求参数；写操作另需 --yes。

表列说明：

列	含义
字段	API 请求参数字段名（`--args` JSON 键）
类型	字符串 / 整数 / JSON 对象等
必传	Y=必填，N=可选
CLI flags	可直接使用的 `--xxx`；`-` 表示仅能通过 `--args`
说明	取值约束与备注

CLI 命令	MCP 工具	ssp_api 章节（概览）
`tp app list` / `get`	`list_apps`	应用管理
`tp app probe`	`get_app_info`	应用管理
`tp app create` / `update` / `delete`	`create_app` / `update_app` / `delete_app`	应用管理
`tp adseat list` / `get`	`list_adseats`	广告位
`tp adseat create` / `update`	`create_adseat` / `update_adseat`	广告位
`tp adscene list`	`list_adscenes`	广告场景
`tp adscene upsert`	`upsert_adscene`	广告场景
`tp placement list` / `get`	`list_placements`	广告源
`tp placement list-by-app`	`get_placement_list_by_app`	广告源
`tp placement upsert` / `toggle`	`upsert_placement` / `toggle_placement`	广告源
`tp platform legacy`	`list_adsources`	附录广告平台 ID
`tp platform list`	`new_get_adsource_list`	广告平台目录
`tp token list` / `get` / `update`	`list_api_tokens` / `get_api_token_list_detail` / `update_api_token`	授权管理
`tp account-template get` / `save`	`get_account_template` / `save_authorization_info`	授权管理
`tp intermediary list` / `upsert` / `reorder`	`list_intermediary_groups` / `upsert_intermediary_group` / `reorder_intermediary_groups`	中介组
`tp group-placement list` / `update` / `toggle`	`list_group_placements` / `update_group_placement` / `toggle_group_placement`	中介组广告源
`tp abtest list` / `create` / …	`list_abtests` / `create_abtest` / …	A/B 测试
`tp report v3`	`query_v3_report`	综合报表 V3
`tp report v4` / `api` / `tp`	`query_v4_report` / `query_v4_api_report` / `query_v4_tp_report`	V4 综合报表
`tp report ltv` / `tpltv` / `retention`	`query_ltv_report` / `query_tpltv_report` / `query_user_retention_report`	用户价值与留存
`tp report user-arpu` / `user-imp` / `user-ecpm`	`query_user_arpu_report` / `query_user_imp_report` / `query_user_ecpm_report`	新增用户价值
`tp report ltv-imp`	`query_ltv_imp_report`	用户 LTV 展示（TradPlus 统计）
`tp report user-type`	`query_user_type_report`	新老用户分析
`tp report deu-retention`	`query_deu_retention_report`	DEU 留存渗透率
`tp report device`	`query_device_report`	设备层级报表
`tp report abtest`	`query_v4_abtest_report`	A/B 测试报表
`tp report active-users`	`query_active_user_report`	活跃用户
`tp report funnel` / `sdk-event` / `sdk-event-detail`	`query_funnel_report` 等	开发者网关 §3
`tp meta categories`	`list_app_categories`	附录分类
`tp geo regions` / `cities`	`list_regions` / `list_cities`	附录地区
`tp auth scope`	`validate_access_scope`	—
`tp auth summarize`	`summarize_current_access`	—
`tp summarize app` / `adseat` / `platform`	`summarize_app_configuration` 等	—

便于检索：左列为终端命令，右列为开发者后台管理 API / 数据报表查询 API 对应章节。

CLI 命令	API 文档章节（概览）
`tp app list` / `get`	应用管理
`tp app probe`	应用管理
`tp app create` / `update` / `delete`	应用管理
`tp adseat list` / `get`	广告位
`tp adseat create` / `update`	广告位
`tp adscene list`	广告场景
`tp adscene upsert`	广告场景
`tp placement list` / `get`	广告源
`tp placement list-by-app`	广告源
`tp placement upsert` / `toggle`	广告源
`tp platform legacy`	附录广告网络 ID
`tp platform list`	广告网络查询
`tp token list` / `get` / `update`	广告网络授权信息
`tp account-template get` / `save`	广告网络授权信息
`tp intermediary list` / `upsert`	中介组
`tp group-placement list` / `update` / `toggle`	中介组广告源
`tp abtest list` / `create` / …	A/B测试
`tp report v3`	数据报表查询 API §2
`tp report v4` / `api` / `tp`	数据报表查询 API §3
`tp report ltv` / `tpltv` / `retention`	数据报表查询 API §4–§6
`tp report abtest` / `forecast` / `confidence`	数据报表查询 API §7
`tp report active-users`	CLI 封装；`dau`/`deu` 等亦见综合报表 `metric`（数据报表查询 API §2.3）
`tp meta categories`	附录分类
`tp geo regions` / `cities`	附录地区
`tp auth scope` / `auth summarize`	CLI 辅助（权限摘要）
`tp summarize app` / `adseat` / `platform`	CLI 辅助（配置摘要）

11.1 配置与鉴权

`tp config set`

字段	类型	必传	CLI flags	说明
bear	String	N	`--bear`	API Key
secret	String	N	`--secret`	密钥
base_url	String	N	`--base-url`	管理 API 根地址
report_base_url	String	N	`--report-base-url`	报表 OpenAPI 根地址；省略时按 `base_url` 推断

`tp auth scope`

字段	类型	必传	CLI flags	说明
app_uuid	String	N*	`--app-uuid`	与 adseat_uuid 至少传一个
adseat_uuid	String	N*	`--adseat-uuid`	与 app_uuid 至少传一个
currency	String	N	`-`	默认 USD

`tp auth summarize`

无业务参数。

`tp summarize app`

字段	类型	必传	CLI flags	说明
app_uuid	String	Y	`--app-uuid`	应用 UUID
currency	String	N	`-`	USD 或 CNY，默认 USD

`tp summarize adseat`

字段	类型	必传	CLI flags	说明
adseat_uuid	String	Y	`--adseat-uuid`	广告位 UUID
currency	String	Y	`-`	USD 或 CNY

`tp summarize platform`

字段	类型	必传	CLI flags	说明
kind	String	N	`--kind`	`health`（默认）或 `usage`
currency	String	Y*	`-`	usage 统计必填
adsource_id	String	N	`-`	按广告网络 ID 过滤
adsource_name	String	N	`-`	按广告网络名称过滤

11.2 应用与广告位

`tp app list`

字段	类型	必传	CLI flags	说明
app_uuids	String	N	`--app-uuids`	逗号分隔，最多 100；传入时忽略分页
page	Int	N	`--page`	默认 1
limit	Int	N	`--limit`	每页条数
—	—	N	`--all`	无 app_uuids 时自动翻页（CLI 扩展）

tp app list --format table
tp app list --app-uuids "uuid1,uuid2" --format json
tp app list --all --format json

`tp app get`

字段	类型	必传	CLI flags	说明
app_uuids	String	Y	`--app-uuid`	单个 UUID

`tp app probe`

字段	类型	必传	CLI flags	说明
app_url	String	Y	`--url`	商店链接；`--args` 中可用 `store_url` 别名

`tp app create` / `update` / `delete`（写操作）

参数通过 **--args JSON** 传入，字段与开发者后台管理 API 应用管理接口一致；须 **--yes**。
缺参时执行不带 --yes 的命令可查看参数说明表。

`tp adseat list`

字段	类型	必传	CLI flags	说明
app_uuid	String	N*	`--app-uuid`	与 adseat_uuids 二选一
adseat_uuids	String	N*	`--adseat-uuids`	逗号分隔
page	Int	N	`--page`	默认 1

tp adseat list --app-uuid "<app_uuid>" --format table

`tp adseat get`

字段	类型	必传	CLI flags	说明
adseat_uuids	String	Y	`--adseat-uuid`	单个或多个（逗号分隔）

`tp adseat create` / `update`（写操作）

见开发者后台管理 API 广告位接口；**--args + --yes**。

`tp adscene list`

字段	类型	必传	CLI flags	说明
app_uuid	String	N	`--app-uuid`	按应用过滤
adseat_uuid	String	N	`-`	按广告位过滤
page	Int	N	`-`	默认 1

11.3 广告源、广告网络与授权

`tp placement list`

字段	类型	必传	CLI flags	说明
currency	String	Y	`--currency`	USD 或 CNY；漏传报 1001
placement_ids	String	N	`-`	逗号分隔，最多 100
adsource_ids	String	N	`-`	逗号分隔
app_uuids	String	N	`-`	逗号分隔
adseat_uuids	String	N	`--adseat-uuid`	逗号分隔；flag 写入 `adseat_uuids`
page	Int	N	`--page`	默认 1，每页 100
is_on	Int	N	`-`	1=仅开启(默认), 0=仅关闭, -1=全部

tp placement list --currency USD
tp placement list --currency USD --adseat-uuid "<adseat_uuid>"
tp placement list --args '{"currency":"USD","is_on":-1}' --format json

`tp placement get`

字段	类型	必传	CLI flags	说明
placement_ids	String	Y	`--placement-id`	广告源 ID

`tp placement list-by-app`

字段	类型	必传	CLI flags	说明
app_uuid	String	Y	`--app-uuid`	应用 UUID
platform	String	N	`--platform`	如 `pangle`

`tp placement upsert` / `toggle`（写操作）

**--args + --yes**；字段见开发者后台管理 API 广告源接口。

`tp platform legacy`

无参数。

`tp platform list`

字段	类型	必传	CLI flags	说明
ad_type	Int	Y	`--ad-type`	1 原生 2 插屏 3 开屏 4 横幅 5 激励
os	Int	Y	`--os`	1=Android, 2=iOS

tp platform list --ad-type 4 --os 1 --format table

`tp token list`

无专用 flags；可用 --args 传筛选字段。

`tp token get`

字段	类型	必传	CLI flags	说明
api_token_id	String	Y	`--token-id`	授权 ID

`tp token update` / `tp account-template save`（写操作）

**--args + --yes**。

`tp account-template get`

字段	类型	必传	CLI flags	说明
adsource_id	String	Y	`--adsource-id`	广告网络 ID

11.4 中介组与 A/B测试

`tp intermediary list`

字段	类型	必传	CLI flags	说明
adseat_uuid	String	Y	`--adseat-uuid`	广告位 UUID
currency	String	Y	`-`	USD 或 CNY
page	Int	N	`--page`	默认 1

tp intermediary list --adseat-uuid "<uuid>" --args '{"currency":"USD"}'

`tp group-placement list`

字段	类型	必传	CLI flags	说明
adseat_uuid	String	Y	`-`	广告位 UUID
currency	String	Y	`-`	USD 或 CNY
group_id	Int	N	`--group-id`	中介组 ID
bucket_id	Int	N	`-`	A/B分组 ID
page	Int	N	`--page`	默认 1

`tp abtest list`

字段	类型	必传	CLI flags	说明
adseat_uuid	String	N	`--adseat-uuid`	按广告位过滤
abtest_id	Int	N	`-`	精确查询
page	Int	N	`--page`	默认 1

中介组 / A/B测试写操作：**--args + --yes**。

11.5 报表

报表 CLI flags 映射为 start_date / end_date（CLI 使用 --start / --end）。网关路由见 §3.4。

`tp report v2`（MCP: `query_v2_report`）

遗留综合报表，不支持按中介组过滤。若命令行传入 --group-id，CLI 会在 stderr 输出 warning：report v2 does not support intermediary group filtering; use report v4，且不会按组过滤结果。请改用 tp report v4。

`tp report v3`

与 v4 参数类似，对应数据报表查询 API §2 /v3/allreport；新接入优先用 v4。

字段	类型	必传	CLI flags	说明
start_date	String	Y	`--start`	YYYY-MM-DD
end_date	String	Y	`--end`	YYYY-MM-DD
app_uuid	String	N	`--app-uuid`	单应用
metrics	String	N	`-`	逗号分隔，默认 `all`
group_by	String	N	`-`	默认 `date`

tp report v3 --start 2026-05-01 --end 2026-05-07 --format json

`tp report v4` / `api` / `tp`

字段	类型	必传	CLI flags	说明
start_date	String	Y	`--start`	YYYY-MM-DD
end_date	String	Y	`--end`	YYYY-MM-DD
app_uuid	String	N	`--app-uuid`	单应用
adseat_uuid	String	N	`--adseat-uuid`	单广告位
metrics	String	N	`-`	逗号分隔；默认 `all`；可含 `fillTime`（填充时长）
preset	String	N	`-`	如 `dashboard-placement-source`
group_by	String	N	`-`	聚合维度
group_id	Int	N	`--group-id`	中介组 ID；可传 `0` 表示默认组
currency	String	N	`-`	USD 或 CNY
timezone	String	N	`-`	UTC+8 等
bid_type	Int	N	`-`	`1` 常规、`2` 竞价
start/limit	Int	N	`-`（`--args`）	分页偏移与条数，见 §7.2.2
fetch_all	Bool	N	`--all-pages`	自动拉全量（v4）
page	Int	N	`--page`	兼容旧参数，转换为 `start`

api / tp 子命令要求 start_date 与 end_date 为同一天。

tp report v4 --start 2026-05-01 --end 2026-05-07 --format json
tp report v4 --args '{"start_date":"2026-05-01","end_date":"2026-05-07","metrics":"request,fill,fillrate,fillTime,impression"}' --format json
tp report v4 --start 2026-05-01 --end 2026-05-07 --adseat-uuid "<adseat_uuid>" --group-id 0 --format json

说明：fillTime 是综合报表中的「填充时长」指标，不等于中介管理页面里「应用层面」请求/填充导出。

`tp report ltv` / `tpltv` / `retention`（MCP: `query_ltv_report` 等）

与数据报表 OpenAPI 中 LTV、留存类接口对应。常用 flags：--start、--end、--app-uuid；指标、维度、国家/渠道等筛选请用 --args 传入。

字段	类型	必传	CLI flags	说明
start_date	String	Y	`--start`	YYYY-MM-DD
end_date	String	Y	`--end`	YYYY-MM-DD
app_uuid	String	N	`--app-uuid`	应用 UUID
metrics	String	N	`-`	如 `ltv1,ltv7` 或 `all`（留存为 `kp1,kp7`）
group_by	String	N	`-`	须含 `date,app`；用户价值类可加 `area` 等；留存/DEU 不可含广告位维度
areas	String	N	`-`	国家代码，逗号分隔
channels	String	N	`-`	渠道，逗号分隔
app_versions	String	N	`-`	应用版本，逗号分隔
placement_ids	String	N	`-`	广告位 UUID，逗号分隔
currency	String	N	`-`	USD 或 CNY
timezone	String	N	`-`	UTC+0 / UTC+8 / UTC-8

tp report ltv --start 2026-05-01 --end 2026-05-07 --app-uuid "<app_uuid>" --format json
tp report retention --args '{"start_date":"2026-05-01","end_date":"2026-05-07","metrics":"all","group_by":"date,app"}' --format json

`tp report user-arpu` / `user-imp` / `user-ecpm` / `ltv-imp`（MCP: `query_user_arpu_report` 等）

参数规则与上表相同；metrics 分别为 arpu1…、uimp1…、ecpm1…、imp1… 或 all。group_by 规则见上表（留存、DEU 子命令不可按广告位聚合）。

`tp report user-type`（MCP: `query_user_type_report`）

字段	类型	必传	CLI flags	说明
start_date	String	Y	`--start`	YYYY-MM-DD
end_date	String	Y	`--end`	YYYY-MM-DD
app_uuid	String	N	`--app-uuid`	应用 UUID
user_types	String	N	`-`	`1` 新用户、`2` 老用户，逗号分隔
channels	String	N	`-`	渠道过滤
areas	String	N	`-`	国家代码
currency	String	N	`-`	USD 或 CNY，影响收入字段

`tp report deu-retention`（MCP: `query_deu_retention_report`）

参数规则同用户价值类报表；metrics 为 kpdeu1…kpdeu90 或 all；group_by 不可含广告位维度。

`tp report device`（MCP: `query_device_report`）

获取指定日期、指定应用的设备层级报表 CSV 下载地址（返回各区域下载链接）。

字段	类型	必传	CLI flags	说明
date	String	Y	`--date`	单日，YYYY-MM-DD
app_uuid	String	Y	`--app-uuid`	应用 UUID
api_version	String	N	`-`	`v3` 或 `v4`，默认 `v4`
timezone	String	N	`-`	UTC+0 / UTC+8 / UTC-8
currency	String	N	`-`	USD 或 CNY

tp report device --date 2026-05-01 --app-uuid "<app_uuid>" --format json

`tp report abtest`（MCP: `query_v4_abtest_report`）

字段	类型	必传	CLI flags	说明
start_date	String	Y	`--start`	YYYY-MM-DD
end_date	String	Y	`--end`	YYYY-MM-DD
abtest_id	String	Y	`--abtest-id`	A/B测试 ID

`tp report forecast`

字段	类型	必传	CLI flags	说明
app_uuid	String	Y	`--app-uuid`	应用 UUID

`tp report confidence`

字段	类型	必传	CLI flags	说明
abtest_id	String	Y	`--abtest-id`	A/B测试 ID

`tp report active-users`

字段	类型	必传	CLI flags	说明
start_date	String	Y	`--start`	YYYY-MM-DD
end_date	String	Y	`--end`	YYYY-MM-DD
app_uuid	String	N	`--app-uuid`	应用 UUID

走开发者网关；无 --metrics flag，指标默认 all。cohort 类指标请用 tp report retention 等，勿与 active-users 混用。

`tp report funnel`（MCP: `query_funnel_report`）

广告漏斗分析，常用 flags：--start、--end、--app-uuid；国家、渠道、广告位类型等筛选请用 --args 传入。

字段	类型	必传	CLI flags	说明
start_date / end_date	String	Y	`--start` / `--end`	日期段
app_uuid	String	N*	`--app-uuid`	与 `app_name` 二选一；仅单个应用
app_name	String	N*	`--app-name`	按应用名称模糊匹配
view	String	N	`-`	`daily`（默认）/ `summary` / `trend` / `detail`
avg_method	String	N	`-`	汇总方式，如 `dau`

tp report funnel --start 2026-05-01 --end 2026-05-07 --app-uuid "<app_uuid>" --format json

`tp report sdk-event` / `sdk-event-detail`（MCP: `query_sdk_event_log` 等）

SDK 事件汇总与明细，需指定日期范围、应用与广告位。常用 flags：--start、--end、--app-uuid、--placement-uuid、--group-id（可选，口径与 report v4 一致）、--include-closed（仅明细，与 group + 广告源联用）、--human-readable。

字段	类型	必传	CLI flags	说明
start_date / end_date	String	Y	`--start` / `--end`	汇总可跨天；明细须同一天
app_uuid	String	Y	`--app-uuid`	应用 UUID
placement_uuid	String	Y	`--placement-uuid`	广告位 UUID
group_id	Int	N	`--group-id`	按中介组过滤
include_closed	Bool	N	`--include-closed`	仅明细：与 `--group-id` + `--tradplus-placement-id` 联用时，包含组内已关闭源（`status=0`）以查历史事件；默认 false
event_ids / event_id	—	N/Y	`--event-ids` / `--event-id`	汇总用多事件；明细必填单事件
metric	String	Y*	`-`	仅明细：`error_code` / `adsource` / `load_time` / `error_msg` 等
tradplus_placement_id	String	N	`--tradplus-placement-id`	TradPlus 后台广告源 ID（非三方 networkPlacementId）
human_readable	String	N	`--human-readable`	传 `true`/`1` 增加可读字段

下钻约定：

metric=adsource / load_time：仅支持 event 800/801；其它事件请用 error_code，必要时加 --tradplus-placement-id
event 800 排障优先 error_code；error_msg 往往拿不到有效文案明细
include_closed：只影响「组 + 具体广告源」的准入；不改变「只传 --group-id」时的开启源汇总。源已从组关系表移除时仍为空

tp report sdk-event --start 2026-05-01 --end 2026-05-07 --app-uuid "<app_uuid>" --placement-uuid "<adseat_uuid>" --group-id 32146 --format json
tp report sdk-event-detail --start 2026-05-01 --end 2026-05-01 --app-uuid "<app_uuid>" --placement-uuid "<adseat_uuid>" --event-id 800 --args '{"metric":"error_code"}' --tradplus-placement-id 726070 --human-readable --format json
tp report sdk-event-detail --start 2026-07-14 --end 2026-07-14 --app-uuid "<app_uuid>" --placement-uuid "<adseat_uuid>" --group-id 59076 --tradplus-placement-id 626207 --include-closed --event-id 1300 --args '{"metric":"error_code"}' --format json

11.6 字典数据

`tp meta categories`

无参数。

`tp geo regions`

无参数。

`tp geo cities`

字段	类型	必传	CLI flags	说明
region	String	N	`--region`	国家/地区代码

11.7 写操作参数

下列子命令无专用 flags，完整请求体通过 **--args JSON** 传入，并须 **--yes**：

各写操作字段定义与校验规则见开发者后台管理 API 对应章节；缺参时先执行不带 --yes 的命令，CLI 会输出与接口文档一致的参数说明。

`tp placement toggle`

字段	类型	必传	说明
placement_ids	String	Y	逗号分隔，最多 100
is_on	Int	Y	0=关闭, 1=开启

tp placement toggle --args '{"placement_ids":"123,456","is_on":0}'
tp placement toggle --args '{"placement_ids":"123","is_on":1}' --yes

`tp placement upsert`

字段	类型	必传	说明
adseat_uuid	String	Y*	创建时必填
name	String	Y*	创建时必填
adsource_id	Int	Y*	广告网络 ID
api_token_id	Int	Y*	授权 ID
placement_config	JSON	Y*	含 `placementId`、`appId` 等；AdMob、Unity Ads 填写见开发者后台管理 API AdMob / Unity Ads 广告源配置说明
auto_app_id	String	N	Meta、Inmobi、Yandex 自动化创建（`is_auto_create=1`）时必填；AdMob 勿传，应用 ID 填写 `placement_config.appId`
currency	String	Y	USD 或 CNY
placement_id	Int	Y*	更新时必填；创建传 0 或不传
is_auto_create	Int	N	1=自动化创建（Meta、AdMob、Pangle、Mintegral、Vungle、Bigo、TaurusX、Inmobi、Yandex）
is_header_bidding	Int	N	0/1
rate / is_auto_price	—	N*	非 HB 时通常必填

# 创建（dry-run 先看参数说明）
tp placement upsert --args '{
  "adseat_uuid":"<adseat_uuid>",
  "name":"AdMob激励01",
  "adsource_id":2,
  "api_token_id":123,
  "placement_config":{"appId":"ca-app-pub-xxx~yyy","placementId":"ca-app-pub-xxx/yyy"},
  "currency":"USD",
  "rate":1.5,
  "is_auto_price":2
}'

# 确认后执行
tp placement upsert --args '{...}' --yes

自动化创建（is_auto_create=1）各广告网络参数差异较多；缺参时 CLI 会展开 自动化创建广告源 参数表。详见开发者后台管理 API 中广告源自动化相关说明。

`tp app create`

字段	类型	必传	说明
app_name	String	Y	最长 100 字符
os	Int	Y	1=Android, 2=iOS（创建后不可改）
package_name	String	N*	无 app_url 时必填
category_id	Int	N*	无 app_url 时必填；`tp meta categories` 查询
app_url	String	N	商店链接；iOS 可自动补全

tp app create --args '{"app_name":"Demo","os":1,"package_name":"com.example.app","category_id":101}' --yes

`tp adseat create`

字段	类型	必传	说明
app_uuid	String	Y	所属应用
seat_name	String	Y	广告位名称
ad_type	Int	Y	1 原生 2 插屏 3 开屏 4 横幅 5 激励
cache_num	Int	Y	并行请求数

开屏/原生开屏另需 skip_time、countdown_time、is_skip 等，见开发者后台管理 API 广告位接口。

`tp intermediary upsert`

字段	类型	必传	说明
adseat_uuid	String	Y	广告位 UUID
group_name	String	Y	最长 30 字符
bucket_id	Int	Y	无 A/B测试时填 0
currency	String	Y	USD 或 CNY
group_id	Int	N	更新时传已有组 ID
country	String	N	ISO 码逗号分隔

`tp intermediary reorder`（MCP: `reorder_intermediary_groups`）

调整同一广告位、同一 AB 分组内自定义中介组的优先级。对应 OpenAPI：/api/intermediary/update_group_sort。须 --yes。

字段	类型	必传	说明
adseat_uuid	String	Y	广告位 UUID
bucket_id	Int	Y	AB 分组 ID；无 AB 时填 `0`
group_list	Array / 逗号分隔	Y	按优先级从高到低排列的中介组 ID；必须包含该 bucket 下全部自定义组；不含默认组 `0`；不可重复
currency	String	Y	USD 或 CNY

tp intermediary list --adseat-uuid "<adseat_uuid>" --args '{"currency":"USD"}' --format json
tp intermediary reorder --args '{"adseat_uuid":"<adseat_uuid>","bucket_id":0,"group_list":[11,33,22],"currency":"USD"}' --yes

智能托管广告位不可手动排序；缺参或不完整的 group_list 会被拒绝。

11.8 典型工作流（可复制命令）

下列流程展示 从查 ID 到改配置 的完整传参方式（将 <...> 替换为实际值）。

流程 A：查某广告位下全部广告源（含已关闭）

tp adseat list --app-uuid "<app_uuid>" --format table --fields adseat_uuid,seat_name,ad_type
tp placement list --currency USD --adseat-uuid "<adseat_uuid>" --args '{"is_on":-1}' --format json

流程 B：创建 AdMob 广告源（手动填写，非 Header Bidding）

须同时提供 AdMob 应用 ID（placement_config.appId）与 广告单元 ID（placement_config.placementId），均从 AdMob 控制台复制；AdMob 勿传 auto_app_id。Android / iOS 要求相同，见开发者后台管理 API AdMob 广告源配置说明。

tp platform legacy --format table --fields adsource_id,name
tp token list --format json
tp account-template get --adsource-id 2
tp placement upsert --args '{
  "adseat_uuid":"<adseat_uuid>",
  "name":"AdMob Banner",
  "adsource_id":2,
  "api_token_id":<token_id>,
  "placement_config":{"appId":"<admob_app_id>","placementId":"<admob_unit_id>"},
  "currency":"USD",
  "rate":0.5,
  "is_auto_price":2
}' --print-request
# 核对 stderr 后：
tp placement upsert --args '{...}' --yes

流程 B2：AdMob 自动化创建广告源（Header Bidding）

AdMob 勿传 auto_app_id
**placement_config.appId**：必填、非空（Android / iOS 相同）
**placement_config.placementId**：可传 ""，成功后系统回填
另须 is_auto_create=1、is_header_bidding=1，且 api_token_id 已开启自动化
完整填写规则见开发者后台管理 API AdMob 广告源配置说明

tp placement upsert --args '{
  "adseat_uuid":"<adseat_uuid>",
  "name":"AdMob Banner Auto",
  "adsource_id":2,
  "api_token_id":<token_id>,
  "is_auto_create":1,
  "is_header_bidding":1,
  "placement_config":{"appId":"<admob_app_id>","placementId":""},
  "currency":"USD"
}' --print-request
# 核对 stderr 后：
tp placement upsert --args '{...}' --yes

流程 B3：Unity Ads 插屏开屏创建

placement_config.appId：必填、非空，填写 Unity Game ID
placement_config.placementId：必填、非空，填写已有 Unity Placement ID
插屏开屏传 is_native=0、placement_config.placement_ad_type=2
完整填写规则见开发者后台管理 API Unity Ads 广告源配置说明

tp placement upsert --args '{
  "adseat_uuid":"<splash_adseat_uuid>",
  "name":"Unity 插屏开屏",
  "adsource_id":5,
  "api_token_id":<token_id>,
  "is_native":0,
  "placement_config":{
    "appId":"<unity_game_id>",
    "placementId":"<unity_placement_id>",
    "placement_ad_type":2
  },
  "currency":"USD",
  "rate":0.5,
  "is_auto_price":2
}' --print-request
# 核对 stderr 后：
tp placement upsert --args '{...}' --yes

流程 C：综合报表导出 CSV

tp report v4 \
  --start 2026-05-01 --end 2026-05-07 \
  --args '{"app_uuids":"<app_uuid>","metrics":"revenue,impression,click","group_by":"date,adsourceId"}' \
  --format csv --fields date,revenue,impression

流程 C2：用户价值 / 留存导出 CSV

tp report ltv --start 2026-05-01 --end 2026-05-07 \
  --args '{"app_uuids":"<app_uuid>","metrics":"ltv1,ltv7,ltv30","group_by":"date,app"}' \
  --format csv --fields date,appId,newUserNum,ltv1,ltv7,ltv30

tp report retention --start 2026-05-01 --end 2026-05-07 \
  --args '{"app_uuids":"<app_uuid>","metrics":"kp1,kp7,kp30","group_by":"date,app"}' \
  --format csv --fields date,appId,newUserNum,kp1,kp7,kp30

11.9 常用枚举速查

字段	取值	含义
`os`	1 / 2	Android / iOS
`ad_type`	1–5	原生 / 插屏 / 开屏 / 横幅 / 激励
`currency`	USD / CNY	货币（大写）
`is_on`	0 / 1 / -1	关闭 / 开启 / 全部（列表过滤）
`is_header_bidding`	0 / 1	否 / 是
`is_auto_price`	1 / 2	自动定价开 / 关
`status`（场景）	1 / 2	启用 / 停用

12. 常见问题

12.1 安装脚本下载失败

请依次检查：

本机网络、VPN、公司代理是否能访问安装服务域名。
安装脚本是否可访问：

 curl -sS -o /dev/null -w "%{http_code}\n" "https://mcp.tradplusad.com/cli/tp/install-tp.sh?version=latest"

预期返回 200。 3. macOS / Linux 是否有 curl、tar、chmod 等基础命令。 4. Windows 是否允许执行 PowerShell 脚本。

12.2 安装成功但找不到 `tp`

通常是安装目录不在 PATH 中。可以先直接执行安装目录下的二进制确认：

/path/to/install/dir/tp version

再根据安装脚本提示把安装目录加入 PATH。

12.3 鉴权失败

请检查：

bear 和 secret 是否来自同一个账号。
TRADPLUS_BASE_URL / --base-url 是否指向正确的管理 API 环境。
报表类命令若报 404 或解析错误，检查 TRADPLUS_REPORT_BASE_URL / --report-base-url 是否与报表 OpenAPI 环境一致（见 §3.4）。
当前 API Key 是否有目标应用、广告位或报表权限。
本地配置、环境变量、命令行参数是否存在混用；命令行参数优先级最高。

12.4 提示「参数不完整」或缺少 currency

常见原因是使用了 **tp xxx list currency USD** 这类 positional 写法。请改为 **--currency USD** 或 **--args '{"currency":"USD"}'**。详见 §8.1 参数传递规范与 §11.3 tp placement list。

12.5 报表无数据或指标报错

CLI 版本是否为 v0.21.0-release 或更高（tp version）。
日期范围、应用 UUID 是否正确，账号是否有该应用报表权限。
若仅报表失败而配置查询正常，检查 §3.4 中的报表地址是否与环境一致。

现象	可能原因	建议
`items` 为空、`total: 0`	日期无流量、筛选过窄、测试账号无填充、报表延迟	扩大日期；去掉 `app_uuids` 试查；与后台统一时区
`[10007] Invalid Metric`	`metrics` 拼写错误或该报表不支持该指标	先省略 `metrics`；对照 §7.3、§7.3.1 或数据报表查询 API
`report api` / `report tp` 报错	跨天查询	将 `--start` 与 `--end` 设为同一天
`ltv`/`retention` 无 `code` 字段	接口正常；cohort 类报表响应格式与综合报表不同	以 `items` 是否返回、`timezone` 是否正确为准
`ltv` 与 `tpltv` 数字不一致	两套数据源本就不相同	确认与开发者后台所选「API / TradPlus」一致
`report v4` 返回 404（测试环境）	报表 OpenAPI 未部署该路径	确认 `report_base_url`；或联系技术改用开发者网关

12.6 安全注意事项

不要把 API Key（bear）、密钥（secret）写入工单、群聊、邮件、截图或代码仓库。
不要提交包含密钥的 .env、config.yaml 或脚本文件。
生产环境写操作必须先 dry-run，再确认后加 --yes。
不同环境的 base_url / report_base_url 必须明确区分，避免把测试凭证或测试参数用于生产环境。
只读巡检推荐 TP_READONLY=true 或 --readonly，避免误触写子命令。

12.7 查询结果与开发者后台不一致时怎么查

您遇到的情况	先做这一步	再确认
广告源条数和开发者后台不一致	`tp placement list --currency USD --adseat-uuid "<广告位编号>"`	广告位编号是否抄错；货币是否同为 USD
应用搜不到	`tp auth scope --app-uuid "<应用编号>"`	是否不可见；需换有权限的 API Key
收入全是 0 或空表	看返回里 `code` 是否为 200	测试环境常为空；正式环境核对日期、时区、货币
广告网络 ID看不懂	`tp platform legacy`	57=Bigo、2=AdMob 等，见 §7.7.8
不确定命令会不会改生产环境	不要加 `--yes`	先执行一次，看 dry-run / `request:` 提示，见 §9

需要把结果发给同事：用 §7.7.10 重定向到桌面文本文件即可。

13. 获取帮助

查看全局帮助：

tp --help

查看某个子命令帮助：

tp app list --help
tp placement upsert --help
tp report v4 --help
tp report ltv --help
tp report retention --help

修订历史​

1. 简介​

1.1 按角色怎么读本文（导读）​

关于文档中的示例​

2. 安装​

2.1 macOS / Linux​

2.2 Windows PowerShell​

2.3 安装后验证​

3. 配置凭证​

3.1 写入本地配置​

3.2 使用环境变量​

3.3 使用命令行参数​

3.4 管理 API 与报表 API 路由​

4. 快速开始（按步骤操作）​

4.5 终端输出示例（长什么样）​

步骤 1：确认连上的是自己的测试账号​

步骤 2：打开某个应用​

步骤 3：列出该应用下的广告位​

步骤 4：列出广告位下的广告源（本示例为 3 条 Bigo 广告源）​

步骤 5：权限自检（客户 UUID 能不能看见）​

步骤 6：一眼汇总（几条源、接了哪些广告网络）​

步骤 7：查询综合报表（测试环境 items 常为空）​

步骤 8：改配置前的「预演」（不会真正执行）​

5. 适用角色与第一次上手​

5.1 谁适合用 CLI​

5.2 建议的首次流程（约 5 分钟）​

5.3 第一次在测试环境试跑​

5.4 我想做什么？该复制哪条命令​

6. 业务场景与工作流​

示例编号（测试环境，可选）​

6.0 十分钟走读​

场景 A：新项目接入（应用 → 广告位 → 广告源）​

场景 B：日常巡检（只读，不改数据）​

场景 C：导出清单与查询综合报表​

场景 D：中介组与 A/B测试​

场景 E：查广告网络 ID（对照开发者后台枚举）​

场景 F：改配置前先「预演」（不会真改）​

7. 综合报表查询与分析​

7.1 选哪个报表子命令​

7.2 通用参数​

7.2.1 CLI 与 API 字段对照（报表）​

7.2.2 分页拉取大量数据​

7.3 常用指标与分组（V4）​

7.3.1 用户价值与留存（ltv / tpltv / retention）​

7.4 业务示例命令（测试环境）​

7.5 返回结果怎么读​

7.6 查询综合报表（推荐顺序）​

7.7 导出与综合报表查询示例​

7.7.1 示范一：导出某广告位下的广告源清单​

7.7.2 示例：查询综合报表（按 date 聚合）​

7.7.3 示范三：导出「应用列表」做盘点​

7.7.4 其他常用导出（一句话说明）​

7.7.5 导出与查询常见问题​

7.7.6 常用命令组合示例​

7.7.7 一张表导出「某应用下所有广告位」​

7.7.8 广告网络 ID 速查​

7.7.9 常见 groupBy 返回结构示意​

7.7.10 把结果保存成文件发给同事​

8. 输出格式与通用参数​

8.1 参数传递规范（必读）​

8.2 flag 与 API 字段对照（常见）​

8.3 Shell 与 --args 引号​

9. 写操作确认机制​

10. 功能列表​

10.1 配置、鉴权与 CLI 辅助命令​

10.2 应用、广告位与广告场景​

10.3 广告源、广告网络与授权​

10.4 中介组与 A/B测试​

10.5 报表​

7.6 字典数据​

11. 命令参数速查​

11.1 配置与鉴权​

tp config set​

tp auth scope​

tp auth summarize​

tp summarize app​

tp summarize adseat​

tp summarize platform​

11.2 应用与广告位​

tp app list​

修订历史

1. 简介

1.1 按角色怎么读本文（导读）

关于文档中的示例

2. 安装

2.1 macOS / Linux

2.2 Windows PowerShell

2.3 安装后验证

3. 配置凭证

3.1 写入本地配置

3.2 使用环境变量

3.3 使用命令行参数

3.4 管理 API 与报表 API 路由

4. 快速开始（按步骤操作）

4.5 终端输出示例（长什么样）

步骤 1：确认连上的是自己的测试账号

步骤 2：打开某个应用

步骤 3：列出该应用下的广告位

步骤 4：列出广告位下的广告源（本示例为 3 条 Bigo 广告源）

步骤 5：权限自检（客户 UUID 能不能看见）

步骤 6：一眼汇总（几条源、接了哪些广告网络）

步骤 7：查询综合报表（测试环境 `items` 常为空）

步骤 8：改配置前的「预演」（不会真正执行）

5. 适用角色与第一次上手

5.1 谁适合用 CLI

5.2 建议的首次流程（约 5 分钟）

5.3 第一次在测试环境试跑

5.4 我想做什么？该复制哪条命令

6. 业务场景与工作流

示例编号（测试环境，可选）

6.0 十分钟走读

场景 A：新项目接入（应用 → 广告位 → 广告源）

场景 B：日常巡检（只读，不改数据）

场景 C：导出清单与查询综合报表

场景 D：中介组与 A/B测试

场景 E：查广告网络 ID（对照开发者后台枚举）

场景 F：改配置前先「预演」（不会真改）

7. 综合报表查询与分析

7.1 选哪个报表子命令

7.2 通用参数

7.2.1 CLI 与 API 字段对照（报表）

7.2.2 分页拉取大量数据

7.3 常用指标与分组（V4）

7.3.1 用户价值与留存（`ltv` / `tpltv` / `retention`）

7.4 业务示例命令（测试环境）

7.5 返回结果怎么读

7.6 查询综合报表（推荐顺序）

7.7 导出与综合报表查询示例

7.7.1 示范一：导出某广告位下的广告源清单

7.7.2 示例：查询综合报表（按 date 聚合）

7.7.3 示范三：导出「应用列表」做盘点

7.7.4 其他常用导出（一句话说明）

7.7.5 导出与查询常见问题

7.7.6 常用命令组合示例

7.7.7 一张表导出「某应用下所有广告位」

7.7.8 广告网络 ID 速查

7.7.9 常见 `groupBy` 返回结构示意

7.7.10 把结果保存成文件发给同事

8. 输出格式与通用参数

8.1 参数传递规范（必读）

8.2 flag 与 API 字段对照（常见）

8.3 Shell 与 `--args` 引号

9. 写操作确认机制

10. 功能列表

10.1 配置、鉴权与 CLI 辅助命令

10.2 应用、广告位与广告场景

10.3 广告源、广告网络与授权

10.4 中介组与 A/B测试

10.5 报表

7.6 字典数据

11. 命令参数速查

11.1 配置与鉴权

`tp config set`

`tp auth scope`

`tp auth summarize`

`tp summarize app`

`tp summarize adseat`

`tp summarize platform`

11.2 应用与广告位

`tp app list`