广告

广告 API 允许您以编程方式在 Roblox 上创建和管理广告。它涵盖两种类型的广告：

• 体验广告 — 通过 Ads API 驱动玩家访问您的体验的参与活动。
• 物品广告 — 赞助市场物品以增加其可发现性。

在使用 Ads API 之前，请生成 API 密钥并授予其访问 ad.campaign:read、ad.campaign:write 和 ad.billing:read 范围的权限。在每个请求的 x-api-key 请求头中包含该密钥。所有 Ads API 端点均从 https://apis.roblox.com/ads-management/v1.` 提供。

关键概念

• 状态与投放状态 — 每个活动都有一个您控制的生命周期 status（ACTIVE、PAUSED 或 CANCELLED，后者是永久的）和一个派生的只读 deliveryStatus（IN_REVIEW、SERVING、NOT_SERVING 或 REJECTED）。新活动的 status 为 ACTIVE，deliveryStatus 为 IN_REVIEW，直到广告政策审核完成。当活动未投放时，请查看 deliveryStatusReasons 以了解原因。
• 货币是微美元字符串 — 预算金额是微美元的十进制字符串（"5000000" = $5.00），以字符串形式发送和返回以保持精度。除以 1,000,000 可转换为美元。
• 目标 — 在 v1 中仅支持 ENGAGEMENT（驱动访问您的体验）。
• 创意 — 活动使用 Open Cloud 图像资产 作为创意。通过 资产 API 上传图像，然后在 creativeAssetIds 中引用其资产 ID。
• 预算变更 — 预算增加立即生效；在运行中的活动上减少预算将在计费账户的时区下一个午夜生效。
• 版本控制 — 主要版本在路径中（/ads-management/v1）。增量的向后兼容更改作为次要版本提供，通过 X-Roblox-Api-Version 头选择；冻结的 1.0 基线是默认值。

体验广告

体验广告活动的第一步是选择要广告的体验。列出账户可以广告的体验，然后获取您选择的体验的活动选项（目标、支付类型和定位维度）和资格。

1. 将 API 密钥复制到 x-api-key 请求头中。
2. 发送请求到 advertisable-universes 列出您可以广告的体验。
3. 发送请求到 campaign-options，将 ${UniverseId} 替换为目标体验的宇宙 ID，以确认资格并读取有效值。

curl --location 'https://apis.roblox.com/ads-management/v1/advertisable-universes' \
--header 'x-api-key: ${ApiKey}'

curl --location 'https://apis.roblox.com/ads-management/v1/campaign-options?universeId=${UniverseId}' \
--header 'x-api-key: ${ApiKey}'

如果体验不符合资格，campaign-options 将返回资格原因，例如 NO_PERMISSION（账户无法广告该体验）或 BLOCKED（该体验不符合广告资格）。

创建活动

向 campaigns 发送 POST 请求，包含体验、创意资产 ID、预算和时间表。

1. 通过 资产 API 上传您的创意图像并记下其资产 ID。
2. 将 x-idempotency-key 请求头设置为 UUID。在 24 小时内重放相同的密钥和相同的主体将返回原始活动，而不是创建重复项。
3. 在请求主体中设置 targetUniverseId、creativeAssetIds、budget 和 schedule。
4. 发送请求。

curl --location 'https://apis.roblox.com/ads-management/v1/campaigns' \
--header 'x-api-key: ${ApiKey}' \
--header 'x-idempotency-key: ${UUID}' \
--header 'Content-Type: application/json' \
--data '{
    "name": "夏季促销",
    "objective": "ENGAGEMENT",
    "paymentType": "CREDIT_CARD",
    "targetUniverseId": "${UniverseId}",
    "creativeAssetIds": ["${AssetId}"],
    "budget": { "type": "DAILY", "amountMicros": "5000000" },
    "schedule": { "startTime": "2026-08-01T00:00:00Z", "durationInDays": 7 }
}'

成功时，活动将返回 status 为 ACTIVE 和 deliveryStatus 为 IN_REVIEW。此时，它已排队等待广告政策审核，尚未投放：

{
  "id": "1122334455",
  "name": "夏季促销",
  "objective": "ENGAGEMENT",
  "paymentType": "CREDIT_CARD",
  "targetUniverseId": "1234567890",
  "creativeAssetIds": ["9876543210"],
  "budget": { "type": "DAILY", "amountMicros": "5000000" },
  "schedule": { "startTime": "2026-08-01T00:00:00Z", "durationInDays": 7 },
  "status": "ACTIVE",
  "deliveryStatus": "IN_REVIEW",
  "createTime": "2026-07-27T00:00:00Z",
  "updateTime": "2026-07-27T00:00:00Z"
}

请求主体字段

定位

targeting 是可选的；省略它或发送一个空对象以覆盖所有受众。每个维度都是一个数组。空数组表示该维度的“所有”。

检查活动是否正在投放

创建活动后，轮询其投放状态，直到其稳定在 SERVING、NOT_SERVING 或 REJECTED。使用 campaigns:batchGetStatus 每次调用检查最多 100 个活动的状态。

curl --location 'https://apis.roblox.com/ads-management/v1/campaigns:batchGetStatus' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{ "campaignIds": ["1122334455"] }'

{
  "statuses": [
    { "id": "1122334455", "status": "ACTIVE", "deliveryStatus": "SERVING" }
  ]
}

任何未找到或不属于调用者的 ID 将在 failures 数组中返回，原因是 NOT_FOUND。

管理活动

使用 PATCH /campaigns/{id} 暂停、恢复、重命名或更改预算。仅发送您要更改的字段。

curl --location --request PATCH 'https://apis.roblox.com/ads-management/v1/campaigns/1122334455' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{ "status": "PAUSED" }'

• 恢复： 发送 { "status": "ACTIVE" }。
• 取消： 发送 { "status": "CANCELLED" }。取消是永久的。
• 更改预算： 发送新的 budget.amountMicros。增加立即生效；在运行中的活动上减少预算将在计费账户的时区下一个午夜生效，直到那时显示为 budget.scheduledAmountMicros 和 budget.scheduledEffectiveTime。

性能报告

活动性能指标——支出、展示次数、播放次数等——通过 分析 API 报告，这是广告和体验指标的主页。

常见错误

错误返回一个信封，包含 HTTP status、简短的 title、可读的 detail 和一个 errors 数组，其中每个条目都有一个稳定的、机器可读的 code 和一个 message。

物品广告

赞助市场物品，如头像物品、捆绑包和通行证，以增加它们在 Roblox 上的可发现性。您可以在 赞助物品管理器 中创建和管理物品赞助，或通过 adconfiguration.roblox.com 上的赞助活动端点以编程方式进行管理，这些端点在 API 参考中的 广告 下列出。有关更多信息，请参见 赞助物品。