TradPlus CLI 使用说明

修订历史

发布时间	修订说明
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` 到跳板机执行

技术特点（了解即可）

支持 compact / table / json / jsonl / csv 等输出，便于人看或导入表格。
写操作默认不执行，必须加 --yes；可先 dry-run 或 --print-request 核对。
复杂筛选、报表维度等可通过 --args '{"字段":值}' 补充（字段名与 API 文档一致）。

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: command not found，说明安装目录不在 PATH 中。请根据安装脚本输出，把安装目录加入当前 shell 或系统环境变量。

3. 配置凭证

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

名称	CLI 字段	说明
API Key	`bear`	即开发者后台「API Key」；CLI 参数名为 `bear`（历史命名，与后台字段对应）
密钥	`secret`	用于请求签名
API 地址	`base_url`	生产：`https://api-developer.tradplusad.com`；测试环境须使用贵司或 TradPlus 提供的网关（示例：`https://test-api-developer.tradplusad.com`），且须使用配套的测试 API Key

3.1 写入本地配置

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

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

查看本地配置：

tp config get

配置文件默认保存到：

~/.tradplus/config.yaml

3.2 使用环境变量

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

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

其中 TRADPLUS_BASE_URL 建议使用 https://api-developer.tradplusad.com。环境变量只在当前终端会话中生效，新的终端窗口需要重新设置，或写入自己的 shell 配置文件。

3.3 使用命令行参数

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

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

通常无需在单次命令中设置 API 地址。如需显式指定，建议值为 https://api-developer.tradplusad.com：

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

鉴权优先级从高到低为：

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

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`	写操作执行前打印最终请求参数，便于核对

示例：

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 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 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 等）

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

tp report v4 --start 2026-05-01 --end 2026-05-07 --format json
tp report ltv --start 2026-05-01 --end 2026-05-07 \
  --args '{"metrics":"ltv1,ltv7,ltv30","group_by":"date,app"}' --format json
tp report retention --start 2026-05-01 --end 2026-05-07 \
  --args '{"metrics":"kp1,kp7","group_by":"date,app"}' --format json
tp report active-users --app-uuid "<app_uuid>" --start 2026-05-01 --end 2026-05-07 --format csv

10.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`
说明	取值约束与备注

11.0 命令索引（CLI ↔ API）

便于检索：左列为终端命令，右列为开发者后台管理 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 根地址

`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（非 start/end 作为 API 字段）。

`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 ltv` / `tpltv` / `retention`

字段	类型	必传	CLI flags	说明
start_date	String	Y	`--start`	YYYY-MM-DD
end_date	String	Y	`--end`	YYYY-MM-DD
app_uuid	String	N	`--app-uuid`	单应用；多应用用 `--args` 中 `app_uuids`
metrics	String	N	`-`	`ltv`/`tpltv`：`ltv1`…`ltv90` 或 `all`；`retention`：`kp1`…`kp90` 或 `all`
group_by	String	N	`-`	默认 `date,app`；可选 `area`、`placementId` 等
areas	String	N	`-`	国家地区 ISO 代码；也可用 `country`

tp report ltv --start 2026-05-01 --end 2026-05-07 --args '{"metrics":"ltv1,ltv7,ltv30","group_by":"date,app"}' --format json
tp report retention --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	`-`	逗号分隔指标
group_by	String	N	`-`	聚合维度
currency	String	N	`-`	USD 或 CNY
timezone	String	N	`-`	UTC+8 等
bid_type	Int	N	`-`	`1` 常规、`2` 竞价
start/limit	Int	N	`-`（`--args`）	分页偏移与条数，见 §7.2.2

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":"revenue,impression"}' --format json

`tp report abtest`

字段	类型	必传	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	String	N	`-`	如 dau,deu
group_by	String	N	`-`	如 date,appId

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 填写见开发者后台管理 API AdMob 广告源配置说明
auto_app_id	String	N	仅 Meta 自动化创建（`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=自动化创建（部分广告网络支持）
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 码逗号分隔

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

流程 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 Key 是否有目标应用、广告位或报表权限。
本地配置、环境变量、命令行参数是否存在混用；命令行参数优先级最高。

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

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

12.5 报表无数据或指标报错

现象	可能原因	建议
`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」一致

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 重定向到桌面文本文件即可。

12.6 安全注意事项

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

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 使用命令行参数​

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 报表​

10.6 字典数据​

11. 命令参数速查​

11.0 命令索引（CLI ↔ API）​

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 使用命令行参数

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 报表

10.6 字典数据

11. 命令参数速查

11.0 命令索引（CLI ↔ API）

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`