广告 CLI 命令

买家：列出此项目被邀请加入的网络，并检查某个网络允许的库存和时段。

ads networks list
ads networks show <seller-project-id>

screenrig ads networks list

卖方：检查或创建本项目自有网络并设置默认费率。

ads network show
ads network create --name NAME
ads network rate --rate-mcr-per-15s MCR --expect-rev REVISION

screenrig ads network rate --rate-mcr-per-15s 1000 --expect-rev 3

--name 最多 120 个字符。--rate-mcr-per-15s 是每完成播放 15 秒的 mcr 正整数，--expect-rev 是 ads network show 中显示的网络 revision。有效费率变更会暂停受影响的广告活动，直到每位买家接受新报价。

卖方：选择是否允许广告投放到自有屏幕，并向受邀买方描述该屏幕。

ads inventory list
ads inventory update <screen-id> [--enabled | --disabled] [--site-name NAME]
    [--city CITY] [--region REGION] [--venue-type TYPE] [--audience-tags TOKENS]
    [--placement TEXT] [--public-description TEXT]
    [--rate-mcr-per-15s MCR | --clear-rate]
    [--impressions-per-hour N | --clear-impressions-per-hour] [--expect-rev REVISION]

screenrig ads inventory update scr_LOBBY --enabled --venue-type cafe

省略的标志保持当前值。新库存行需要 --enabled 或 --disabled。--impressions-per-hour 记录您对屏幕每小时所产生展示次数的估算：每次完成的播放随后会将该估算值乘以播放秒数再除以 3600，计为 ads reports spend、ads reports delivery 和 ads direct report 中的 estimated_impressions。

update 至少需要一个标志。--audience-tags 最多接受 20 个以逗号分隔的标签，每个标签最多 32 个字母、数字或下划线。--clear-rate 使屏幕恢复为项目默认费率，--clear-impressions-per-hour 删除估算值。--expect-rev 以已存储行的版本作为前置条件替换，对尚无行的屏幕会被拒绝。

卖方：定义可重用广告位。广告位本身不会改变屏幕内容，直到其广告位页面被放入播放列表。

ads slots list
ads slots create --name NAME --accepted-media image,video
    [--max-image-duration-ms MS] [--max-video-duration-ms MS]
    [--rate-mcr-per-15s MCR | --clear-rate] [--enabled | --disabled] [--vast-tag-url URL]
ads slots update <slot-id> --expect-rev REVISION [--name NAME]
    [--accepted-media image,video] [--max-image-duration-ms MS] [--max-video-duration-ms MS]
    [--rate-mcr-per-15s MCR | --clear-rate] [--enabled | --disabled]
    [--vast-tag-url URL | --clear-vast-tag-url]

screenrig ads slots create --name "Lobby break" --accepted-media image,video
screenrig ads slots create --name "Lobby video" --accepted-media video --vast-tag-url https://ads.example.com/vast.xml
screenrig ads slots update ads_LOBBY --clear-vast-tag-url --expect-rev 2

除非指定 --disabled，否则新广告位处于启用状态。--accepted-media 为 image、video 或两者，以逗号分隔。省略的时长上限为 30000 毫秒；图像上限为 5000 到 30000 毫秒，视频上限为 5000 到 120000 毫秒。--rate-mcr-per-15s 是正整数，为此广告位覆盖屏幕或项目的费率，--clear-rate 删除该覆盖。update 保留您省略的每个字段，有效费率变更会暂停受影响的广告活动，直到每位买家接受新报价。--vast-tag-url 是不超过 2048 个字符的 HTTPS URL。

--vast-tag-url 设置卖方自己的 VAST 2-4 广告标签，当无邀请广告活动填充你自己的屏幕插槽时尝试；插槽必须支持视频。URL 是端口 443 或 8443 上的 HTTPS 公共主机。后端获取它，跟踪最多五个包装器，摄取选定的渐进式 MP4 或 WebM 到项目媒体，并在接受开始时触发 Impression、creativeView 和 start，接受完成时触发 complete，失败时触发 Error；无四分之一追踪器。宏 [CACHEBUSTING]、[TIMESTAMP]、[SCREENRIG_SCREEN_ID]、[SCREENRIG_SLOT_ID] 和 [SCREENRIG_PAGE_ID] 会被展开，买方永远看不到标签。update 时，--vast-tag-url 替换标签，--clear-vast-tag-url 移除标签；两者不可同时使用，省略两者则保留存储标签。ads slots list 向拥有卖方显示 vast_tag_url。无法在某个屏幕上填充的插槽（没有 VAST 标签，且在已加入广告投放的屏幕上，没有未结束的直接广告活动，也没有指名它的进行中、待定或暂停的邀请广告活动）会从该屏幕的清单中省去，screen show 在 ad_quiet_slots 中列出它，因此播放器不再请求。能够填充它的广告活动、标签或加入投放会使它重新出现。

使用上面的共享 invitations 命令：

screenrig invitations create --kind ad-buyer --email owner@bakery.example --screen-id scr_LOBBY --policy review_required
screenrig invitations list --kind ad-buyer
screenrig invitations revoke ID

广告买家邀请只通过电子邮件发送，不能用链接，并且至少需要一个 --screen-id 或 --slot-id（以逗号分隔）。--policy 为 trusted（默认）或 review_required。

被邀请者在控制台接受。已登录者选择其购买项目，并通过新的通行密钥证明确认。无登录者在接受时创建登录和仅限广告主项目。

卖方：更改或撤销已承认买方的审核策略和库存范围。

ads memberships list
ads memberships update <membership-id> --expect-rev REVISION
    [--policy trusted|review_required] [--screen-id IDS] [--slot-id IDS]
ads memberships revoke <membership-id>

screenrig ads memberships list

update 对省略的标志保留已存储的策略和范围。trusted 不经审核即播放买家的创意；review_required 会将每个创意版本留待您决定。--screen-id 和 --slot-id 接受逗号分隔的 ID 并替换整个列表，空值表示不允许任何项。

撤销停止新的广告播放并保留财务记录。

买家：将已准备好的自有媒体绑定到带有批准文案的不可变创意。

ads creatives list
ads creatives create --media-id ID --copy TEXT
ads creatives show <creative-id>

screenrig ads creatives create --media-id med_123 --copy "Fresh bread daily"

绑定创意不收费，也不会再次上传媒体。已批准的创意永不原地更改：请编辑源媒体并绑定新的创意。--copy 最多 500 个字符。show 列出每个卖方网络对该创意的审核（pending、approved、rejected 或 changes_requested）及卖方给出的理由。

买家：起草广告活动，定价，并通过接受报价激活。

ads campaigns list
ads campaigns show <campaign-id>
ads campaigns create <file>
ads campaigns update <campaign-id> <file> --expect-rev REVISION
ads campaigns preview <campaign-id> [--expect-rev REVISION]
ads campaigns activate <campaign-id> --quote-id ID --expect-rev REVISION
ads campaigns pause <campaign-id> --expect-rev REVISION
ads campaigns resume <campaign-id> --expect-rev REVISION
ads campaigns accept-rates <campaign-id> --quote-id ID --expect-rev REVISION

screenrig ads campaigns preview cmp_123

草稿不保留任何内容。preview 返回限时报价且不消耗额度；activate 需要该报价。卖方费率变更后，只有带新报价的 accept-rates 可恢复广告活动。

<file> 是 JSON 文件，- 表示标准输入，update 用整个文档替换草稿。草稿包含 name、daily_cap_mcr、lifetime_cap_mcr（不低于每日上限）、flight_start 和 flight_end（RFC 3339）以及 networks，项目已加入的每个卖方网络对应一个条目，每个条目含 seller_project_id、screen_ids、slot_ids、creative_ids，以及可选的 venue_types、cities、tags、dayparts 和 network_cap_mcr。金额字段是十进制 mcr 字符串，不是数字。image_duration_ms（5000 到 30000，省略时为十秒）设置图像的显示时长，max_play_price_mcr 限制单次播放的价格；省略则不设上限。

广告活动草稿可从广告主类别列表中选择一个可选的 category。同一类别的两条广告绝不会在同一屏幕的同一广告时段中播放。

preview 读取广告活动的当前修订版，除非 --expect-rev 指定了一个。pause 停止新的预留；已开始的播放会播完并按预留价格结算。resume 恢复手动暂停的广告活动，但不能解除因价格变更造成的暂停。

卖方：在您自己的屏幕上为 screenRIG 之外的广告主预订您自己的交易。

ads direct list
ads direct show <campaign-id>
ads direct create <file>
ads direct update <campaign-id> <file> --expect-rev REVISION
ads direct pause <campaign-id> --expect-rev REVISION
ads direct resume <campaign-id> --expect-rev REVISION
ads direct end <campaign-id> --expect-rev REVISION
ads direct availability <file>
ads direct report <campaign-id> [--from TIME] [--to TIME]
    [--format json|csv|xlsx|pdf] [--output FILE|-]

screenrig ads direct create campaign.json

草稿指定 name、advertiser、可选的 category、flight_start 和 flight_end、media_ids（您自己已就绪的图片或视频，1 到 20 个）、可选的 goal_plays、可选的 price（按每千次播放计的 model cpm 或 flat，含 amount 和 ISO 4217 currency）、可选的 image_duration_ms（5000 到 30000，省略时为十秒）以及定向：screen_ids、slot_ids、venue_types、cities、tags 和 dayparts（例如 {"days": ["mon"], "start": "11:00", "end": "14:00"}），空列表表示所有已加入的屏幕或广告位。直接广告活动先于受邀买家填充广告时段。目标在投放期内均匀分配，落后时优先播放；没有目标的广告活动会在投放期内占用每个符合条件的广告位。不会通过 screenRIG 转移任何资金：由您向广告主收费，价格用于计算报告的价值。

<file> 是 JSON 文件，- 表示标准输入。category 在这里和广告活动草稿中都是 alcohol、apparel、automotive、beauty、cannabis、consumer_electronics、education、entertainment、financial_services、food_and_beverage、gambling、government、grocery、health_and_pharma、home_and_garden、insurance、jobs、legal、media、political、quick_service_restaurants、real_estate、restaurants、retail、sports_and_fitness、technology、telecom、tobacco_and_vaping、travel 或 utilities 之一。update 会替换所有可写字段，因此请发送整个文档。pause 使广告活动停止占用广告位，resume 使其恢复；在暂停期间落后于进度的目标型广告活动会优先播放，直到追上进度。end 不可撤销：已结束的广告活动不再播放，不能恢复，并保留其报告。

availability 读取具有相同定向和投放期的查询，并估算您仍可预订的播放次数：所选屏幕最近的广告位出现次数，减去您其他直接目标仍需的播放次数。它返回 estimated_plays、booked_plays 和 available_plays，而 exclude_campaign_id 会将您正在编辑的广告活动从 booked_plays 中排除。高于估算值的目标会返回 goal_overbooked，除非草稿设置了 "overbook": true。

report 列出相对于目标的播放次数、进度、价值、未播放的次数，以及按 UTC 日期、屏幕、广告位和媒体划分的行。--from 和 --to 接受 RFC 3339 时刻、now 或 7d、12h、30m 这样的时间跨度，默认覆盖整个投放期。--format csv、xlsx 或 pdf 会将各行写入 --output（默认 ./direct-report-CAMPAIGN_ID.FORMAT），并返回其路径、字节数和 SHA-256；配合 --format csv 时，--output - 会改为将 CSV 写到标准输出。CSV 的列为 day、screen_id、slot_id、media_id、plays、played_ms 和 estimated_impressions。JSON 或 CSV 报告最多列出 5000 行，超过时带有警告 direct_report_truncated：缩小 --from 和 --to 以获取其余部分。

创建、替换和恢复直接广告活动，以及 availability 和 report，都需要包含直接广告活动的套餐；其他套餐会被以 feature_not_in_plan 拒绝。screenrig project capabilities 会列出套餐的功能。

卖方：在 review_required 上批准、拒绝或请求买方对确切提交的创意版本进行更改。

ads reviews list
ads reviews show <review-id>
ads reviews approve <review-id>
ads reviews reject <review-id> --reason TEXT
ads reviews request-changes <review-id> --note TEXT

screenrig ads reviews request-changes arv_123 --note "Use the new logo"

request-changes 会将您的备注发送给买方。要提交修订版本，请将修订后的媒体绑定为新创意素材，添加到新广告活动中，并使用新报价运行 preview 和 activate。替代广告活动拥有独立的预算和审核记录。激活替代广告活动前，请暂停原广告活动，以避免重复投放。用户在仪表板的“审核”页面决定广告创意素材的审核结果，该页面也处理播放列表和屏幕变更。

list 显示等待您决定的创意版本，show 显示一次提交及其确切的创意。--reason 和 --note 为必填，最多 500 个字符；买家会在创意上看到它们（ads creatives show）。做出决定需要管理访问。

读取作为买方的支出或作为卖方的交付。

ads reports spend --campaign-id ID [--format json|csv|xlsx|pdf] [--output FILE]
ads reports delivery --from TIMESTAMP --to TIMESTAMP
    [--format json|csv|xlsx|pdf] [--output FILE]
ads reports fill [--from TIME] [--to TIME] [--format json|csv|xlsx|pdf] [--output FILE]

screenrig ads reports delivery --from 2026-09-01T00:00:00Z --to 2026-10-01T00:00:00Z

投递报告显示期间的总额、服务费和净额。买方报告永远不会显示卖方的其他收入。fill 显示最多 35 天内您的屏幕请求的广告位出现次数、其中由直接广告活动、受邀买家和您的 VAST 标签填充的次数，以及其余为何保持空白：no_demand、ineligible、separated 或 capped。

--format csv、xlsx 或 pdf 会将报告作为文件写入 --output（默认 ./ad-spend.FORMAT、./ad-delivery.FORMAT 或 ./ad-fill.FORMAT），并返回其路径、字节数和 SHA-256；json 为默认值，输出信封。delivery 需要以 RFC 3339 时刻给出 --from 和 --to，每个已完成的出现一行，最多 5000 行，超过时设置 truncated；合计涵盖每一笔结算。fill 接受 RFC 3339 时刻、now 或 7d、12h、30m 这样的时间跨度：--from 默认为 --to 之前 7 天，--to 默认为现在，两者最多相隔 35 天，并扩展为完整的 UTC 小时。