文档

Unity 变现服务

Advertiser LLM 编码代理的 public API 迁移参考

将客户端集成从用户获取管理 API (legacy)迁移到 Ads 统一平台 public API 的 LLM 编码代理的参考。
阅读时间50 分钟最后更新于 2 天前

受众:此文件将被写入 LLM 编码Agent(Claude 代码 或 similar)负责从 Legacy Unity“Advertise API”迁移客户端集成 (
/advertise/v1/...
,
mz-advertiser-public-api
服务)到
新建
Unity Ads 广告主 public API (
/ads/advertiser/public/v1/...
)。它被拆分为独立的 实体。每个代码块说明_更改的内容_以及_具体操作_。阅读 概念模型 Change 和 全局 changes 部分先出现,然后应用于每个代码块。

如何使用该文件(Agent 的说明)

  1. 将两个合同视为真相的音频源,而不是此散文。Legacy =
    mz-advertiser-public-api/openapi/specs/advertise-v1.yml
    .新建 =
    ads-unified-platform/openapi/advertiser/platform-public-v1-routes.yaml
    .本指南涵盖 仅限Legacy v1;如果客户端调用
    /advertise/v2alpha1/...
    ,则不同规格 (
    advertise-v2-alpha.yml
    )单独使用,并向人类表面任何仅限 v2 的用途。
  2. 按给定的 Order(Apps → Attribution → Creatives →)迁移一个实体代码块 Creative Packs → Campaign Management → Campaigns → Bids → Budget → Targeting → Assignment)。执行 在代码块依赖 ON 编译/通过之前,不启动代码块。应用程序优先:所有内容都以 新建
    applicationId
    。立即归因(即应用关卡),而 Campaign 管理查找 (
    sdk-event-names
    /
    eligibility
    ) 位于广告系列之前,因为它们提供 广告系列设置。
  3. 当 Legacy 功能列在 🚫 No equivalent 下时,不要发明或猜测 终端。停止并将其作为 Open 问题向人类表面。最重要的例子是
    DELETE app
    (应用程序生命周期现在归 USF 所有)和已弃用 Retention 商品区域(留存率出价/资格)--请参阅代码块。
  4. 在每个代码块之后,根据 Field 表重新映射 Field 名称;永远不要假设 Field 已结转 未更改,除非表显示“未更改”。
  5. 货币更改单位(美元 → 微美元)和应用标识符更改类型 (24 个字符十六进制 → UUID)。这两个变换几乎触及每个代码块。先找到他们

概念模型 Change(先阅读此内容)

该 API 已重新托管到统一平台上,并从“广告系列设置”(app)重新居中 作为平台
Application
(UUID) 的 24 个字符的 Mongo id
,将子 Resource 读取折叠到 广告系列对象,五个单独的广告终端合并为一个。

Legacy 模型

Organization└─ App (campaignSetId, 24-char hex) ← 路径中的“apps” ├──广告素材 ├─广告素材包 └──广告系列(目标:安装量|留存率|ROAS|creativeTesting|eventOptimization) ├── cpi-bids | source-bids | roas-bids | retention-bids | event-optimization-bids │(5 个单独的子资源,每个子资源为 GET/PUT/PATCH,美元字符串) ├── 定向投放 (GET + PATCH) ├─预算(GET + PATCH,美元;每日或每日每个国家/地区映射) └── assigned-creative-packs(POST/删除 一时间一个)

新模型

Organization└─ 应用程序 (applicationId, UUID ← 路径中的“Applications” ├──广告素材(现在还包括补丁 + 删除) ├─广告素材包 ├──归因(GET + PATCH,应用关卡) ← 新建归因广告位 └── Campaign (optimizationType: cpi|legacyRetention|roas|appEventConversion; isCreativeTesting) ├──出价(ONE PATCH .../bids; ROAS|用户手册|manualSource|appEvent) ├──定向投放(仅限 PATCH) ├──预算上限(仅限补丁,微美元;countryGroupDailyLimits) ├── assign-creative-pack/unassign-creative-pack(基于列表的 PATCH/DELETE) └─(出价/预算/定向投放/资源包的读取来自 GET 广告系列?includeFields=…)Organization└─广告系列(新建的宽组织广告系列列表,按 appId 过滤器)
驱动以下每个变换的变化:

#

Shift

迁移的后果

1
apps
→
applications
Resource 路径细分段已重命名。id 从
campaignSetId
(24 个字符十六进制)变为
applicationId
(UUID)。版本
legacy campaignSetId → new applicationId
查找。
2金钱 → 微美元所有出价/预算都是美元字符串(
"0.201"
、
"2500.20"
)。新建 API 为整数微美元(1 USD = 1_000_000)。乘以 1e6。
35 个出价终端 → 1
cpi/source/roas/retention/event-optimization-bids
折叠成具有键入主体的单一
PATCH …/bids
。无 GET 出价 — 通过
GET campaign?includeFields=bids
读取。
4Sub-Resource 内容折叠在中Legacy
GET …/budget
、
GET …/targeting
、
GET …/*-bids
、
GET …/assigned-creative-packs
都消失了。从
GET campaign?includeFields=bids,budget,creativePacks
读取它们。
5
goal
→
optimizationType
广告系列类型 enum 发生更改和拆分(
creativeTesting
变为
isCreativeTesting
布尔值;
eventOptimization
变为
appEventConversion
+
appEventType
)。
6已重新定位归因Legacy 在 campaign 创建主体和 app 上设置归因 URL。新建 API:广告系列更新需要
attributionLinks
,并有专门的应用关卡
GET/PATCH …/attribution
。广告系列创建不再接受归因 URL。
7分配基于列表Legacy 为每个请求分配/取消分配一个打包。新建 API 在一次调用中用 array
creativePackIds
替换/删除。

全局更改(Apply to All终端)

路径中的 路径中的
ON

方面

Legacy

新建

Host
https://services.api.unity.com
https://services.api.unity.com/ads/advertiser
(prod) ·
https://staging.services.api.unity.com/ads/advertiser
(staging)
路径前缀
/advertise/v1
/public/v1
应用路径细分段
…/organizations/{orgId}/apps/{campaignSetId}
…/organizations/{organizationId}/applications/{applicationId}
完整示例
…/advertise/v1/organizations/{orgId}/apps/{campaignSetId}/campaigns
…/ads/advertiser/public/v1/organizations/{orgId}/applications/{applicationId}/campaigns
身份验证HTTP Basic(service-帐户 Key)HTTP Basic 仍然有效;也接受 Bearer JWT(
unity
/
ads
颁发者)。凭据不变,但必需角色/权限不同,请参阅下面的“授权”。
Org id
organizationId
(int64)
organizationId
(Genesis id,数字)——未更改
App ID(类型更改)
campaignSetId
— 24-char hex (
^[0-9a-fA-F]{24}$
)
applicationId
— UUID
金钱美元小数字符串(
"2500.20"
、出价
"0.201"
)
微美元作为整数字符串/数字 (
"2500200000"
); 1 USD = 1_000_000
广告系列/广告素材/打包 ID24 个字符十六进制数 — 未更改(仍然
^[a-f0-9]{24}$
)
24 个字符十六进制 — 未更改
列表信封
{ total, offset, limit, results[] }
无处不在
⚠️ **不一致:**广告系列和广告素材使用
{ items[], meta:{ total, limit, offset } }
;广告素材包使用
{ total, offset, limit, results[] }
;Applications 返回裸 json Array(无信封,无分页)。每个终端的解析。
分页参数
offset
(0)、
limit
(最大 1000,默认 1000)—每个列表
offset
(0)、
limit
(默认 100)ON 分页列表(广告系列、广告素材、广告素材包);
GET …/applications
既不接受
,也不接受**,将参数放在其中(代码块 A)

授权(角色/权限) — 在假设 403 为错误之前阅读

Authentication 没有变化(相同的 Basic 凭据),但授权没有变化:每次新建 终端由在网关处检查的权限字符串进行门禁(在新建的 在
x-unity-gateway.authorization.rules
下指定)。广告主路由需要
advertise.*
权限(
advertise.campaigns.*
、
advertise.creatives.*
、
advertise.creative_packs.*
、
advertise.bids.update
、
advertise.targeting.update
、
advertise.apps.*
等),通过 Unity Cloud Dashboard 中的组织范围服务帐户角色(例如“Advertise API Apps”)。 Editor" grant
advertise.apps.get/list/create/update/delete
)。共享
…/applications
终端接受
advertise.apps.*
或发布者端的
monetize.projects.*
。
Agent 说明:
  1. 在迁移之前,请让人Confirm客户端的服务帐户包含所需的 新建 API 的广告主角色 - 不假定 Legacy API 授权会延续。
  2. 如果 ON Legacy API 有效的请求在新建的请求上返回 403 且具有相同 凭据,将其视为缺失角色授权,而不是请求错误。停止并表面处理; 请勿尝试“修复”请求。

Rate限制(更更新客户端回退)

操作类

Legacy

新建

读取(
GET
)
429 个已定义;每个Resource每个资源限制器20/s + 8000/小时
创建 (
POST
)
(批处理)1/s + 60/hour(
advertiseCreate
)
更新(
PATCH
/
DELETE
)
(批处理)1/s + 200/小时(
advertiseModify
)
出价更新(批处理数组)20/s + 12000/hour(
advertiseBids
)+ 修改层
广告系列管理—6/s + 8000/小时(
advertiseCampaignManagement
)

Master 终端映射

)
)
)
上的字段)
保留

Legacy 操作

Legacy route

New operationId

新建路由

代码块

advertise-listApps
GET …/apps
publicOrganizationApplications
GET …/applications
A
advertise-createApp
POST …/apps
publicCreateApplication
POST …/applications
A
advertise-getApp
GET …/apps/{campaignSetId}
publicGetApplicationById
GET …/applications/{applicationId}
A
advertise-updateApp
PATCH …/apps/{campaignSetId}
publicUpdateApplication
PATCH …/applications/{applicationId}
A
advertise-deleteApp
DELETE …/apps/{campaignSetId}
—🚫 无删除应用程序终端A
advertise-listCreatives
GET …/apps/{id}/creatives
publicGetCreatives
GET …/applications/{id}/creatives
B
advertise-createCreative
POST …/apps/{id}/creatives
(multipart)
publicCreateCreative
POST …/applications/{id}/creatives
(multipart)
B
advertise-getCreative
GET …/creatives/{creativeId}
publicGetCreativeById
GET …/applications/{id}/creatives/{creativeId}
B
— —
publicUpdateCreativeById
PATCH …/creatives/{creativeId}
(新增:重命名
B
— —
publicDeleteCreativeById
DELETE …/creatives/{creativeId}
(新
B
advertise-listCreativePacks
GET …/creative-packs
publicGetCreativePacks
GET …/applications/{id}/creative-packs
C
advertise-createCreativePack
POST …/creative-packs
publicCreateCreativePack
POST …/applications/{id}/creative-packs
C
advertise-getCreativePack
GET …/creative-packs/{packId}
publicGetCreativePackById
GET …/applications/{id}/creative-packs/{creativePackId}
C
advertise-updateCreativePack
PATCH …/creative-packs/{packId}
publicUpdateCreativePack
PATCH …/creative-packs/{creativePackId}
C
advertise-deleteCreativePack
DELETE …/creative-packs/{packId}
publicDeleteCreativePack
DELETE …/creative-packs/{creativePackId}
C
advertise-listCampaigns
(每个应用
GET …/apps/{id}/campaigns
publicGetCampaigns
(组织宽)
GET …/organizations/{orgId}/campaigns?appIds={applicationId}
D
advertise-createCampaign
POST …/apps/{id}/campaigns
publicCreateCampaign
POST …/applications/{id}/campaigns
D
advertise-getCampaign
GET …/campaigns/{campaignId}
publicGetCampaignById
GET …/applications/{id}/campaigns/{campaignId}?includeFields=…
D
advertise-updateCampaign
PATCH …/campaigns/{campaignId}
publicUpdateCampaign
PATCH …/applications/{id}/campaigns/{campaignId}
D
advertise-deleteCampaign
DELETE …/campaigns/{campaignId}
publicDeleteCampaignById
DELETE …/applications/{id}/campaigns/{campaignId}
D
advertise-list/replace/patchCpiBids
GET/PUT/PATCH …/campaigns/{id}/cpi-bids
publicUpdateBids
(
manualBids
)
PATCH …/campaigns/{campaignId}/bids
E
…SourceBids
…/source-bids
publicUpdateBids
(
manualSourceBids
)
PATCH …/campaigns/{campaignId}/bids
E
…RoasBids
…/roas-bids
publicUpdateBids
(
roasBids
)
PATCH …/campaigns/{campaignId}/bids
E
…EventOptimizationBids
…/event-optimization-bids
publicUpdateBids
(
appEventBids
)
PATCH …/campaigns/{campaignId}/bids
E
…RetentionBids
…/retention-bids
—🚫 保留出价已弃用 — 不再支持E
advertise-getBudget
GET …/campaigns/{id}/budget
—(通过广告系列阅读)
GET campaign?includeFields=budget
F
advertise-updateBudget
PATCH …/campaigns/{id}/budget
publicPatchCampaignBudgetCap
PATCH …/campaigns/{campaignId}/budget-cap
F
advertise-getTargeting
GET …/campaigns/{id}/targeting
—(通过广告系列阅读)
GET campaign
(针对响应
G
advertise-updateTargeting
PATCH …/campaigns/{id}/targeting
publicPatchCampaignTargeting
PATCH …/campaigns/{campaignId}/targeting
G
advertise-listAssignedCreativePacks
GET …/campaigns/{id}/assigned-creative-packs
—(通过广告系列阅读)
GET campaign?includeFields=creativePacks
H
advertise-assignCreativePack
(one)
POST …/assigned-creative-packs
publicAssignCreativePacks
(list)
PATCH …/campaigns/{campaignId}/assign-creative-pack
H
advertise-unassignCreativePack
(one)
DELETE …/assigned-creative-packs/{id}
publicUnassignCreativePacks
(list)
DELETE …/campaigns/{campaignId}/unassign-creative-pack
H
advertise-listSdkEventNames
GET …/audience-pinpointer/sdk-event-names
publicGetSdkEventNames
GET …/applications/{id}/sdk-event-names
I
advertise-listEventOptInfo
GET …/audience-pinpointer/event-optimization-info
publicGetCampaignManagementEligibility
GET …/applications/{id}/eligibility
I
advertise-listRoasInfo
/
…RetentionInfo
GET …/audience-pinpointer/roas-info
/
…/retention-info
— 🚫 ROAS 不再需要资格;已弃用I
—(归因为 ON campaign/app)(
attributionClickUrl
/
attributionStartUrl
)
publicGetApplicationAttribution
/
publicUpdateApplicationAttribution
GET/PATCH …/applications/{id}/attribution
J

代码块 A — Apps → Applications

更改的内容

  • 路径细分段
    apps
    →
    applications
    ;id
    campaignSetId
    (24 个字符十六进制) →
    applicationId
    (UUID)。这是高风险重新映射 — 每个广告系列/广告素材/打包调用都是嵌套的 下。版本并在迁移期间保留
    legacy campaignSetId → new applicationId
    映射。
  • platform
    现在是 ON 创建的必需显式 Field(由
    store
    隐式表示)。
  • 应用关卡归因 URL(
    appAttributionClickUrl
    /
    appAttributionStartUrl
    )已移至 专用归因终端 — 请参阅代码块 J。
  • DELETE app
    没有等效
    项(已确认为故意)。应用程序程序Lifecycle已移出 广告作用域 Unity Services Foundation (USF),而应用程序程序删除当前为 Disabled 平台宽。新建Applications程序Resource仅显示 列表创建更新。如果 客户端通过 API 删除应用程序,停止并表面。
  • **列表更改了形状并丢失了分页/过滤器。**返回的 Legacy
    GET …/apps
    带有
    offset
    /
    limit
    和
    filter[store]
    /
    filter[storeId]
    的
    { total, offset, limit, results[] }
    查询参数。新建
    GET …/applications
    返回所有 org 的 Bare json Array Applications — 无信封、无分页、无过滤器。删除参数并过滤器/分页 客户端。

Field Mapping — 创建 (advertise-createApp → CreateApplicationPublicDto)

Legacy Field

新建 Field

注意

name
(必填)
name
(必填)
不变
store
(
apple
/
google
/
standalone_android
)
store
+
platform
重新映射枚举 →
AppleAppStore
/
GooglePlay
/…和设置
platform
(
iOS
/
Android
/…)。
storeId
(必填)
storeId
(可选)
不变值
—
platform
(必需,enum)
**新建,必填。**派生自 Legacy
store
。
adomain
—🚫 应用程序响应没有 Field。如果客户端依赖于表面,则为表面。
gameId
(integer)
gameId
(整数,可 null)
呈现在响应上;不是创建输入 — 设置服务器端。
appAttributionClickUrl
归因
clickUrl
**已移动。**创建后通过
PATCH …/attribution
设置(代码块 J)。
appAttributionStartUrl
归因
startUrl
**已移动。**通过
PATCH …/attribution
设置(代码块 J)。
—
privacy.coppa
,
privacy.mixedAudience
新建可选隐私对象
—
projectId
/
projectName
新建可选分组(共享发布者/广告主应用模型)
新建
store
enum:
GooglePlay
、
AppleAppStore
、
SamsungGalaxy
、
AmazonAppStore
、
MacAppStore
、
UDP
,
MicrosoftStore
,
HuaweiAppGallery
,
APK
.新建
platform
enum:
Android
、
iOS
、
OSX
、
Windows
,
Linux
,
WebGL
,
Windows_Store
,
PS4
,
PS5
,
XboxOne
,
tvOS
,
Switch
,
VisionOS
.
Legacy
store
→ 新建
{store, platform}
(已确认):
apple
→
{AppleAppStore, iOS}
;
google
→
{GooglePlay, Android}
;
standalone_android
→ 取决于实际存储 — Samsung →
{SamsungGalaxy, Android}
、华为 →
{HuaweiAppGallery, Android}
;当无法识别存储时 平台将其贴图到
{APK, Android}
。

Field Mapping — 响应 (app → ApplicationPublicResponseDto)

Legacy Field

新建 Field

注意

id
(24 个字符十六进制,
campaignSetId
)
id
(UUID)
**类型 Change。**持久化 Mapping。
name
name
unchanged
store
/
storeId
store
/
storeId
enum 重新映射(上图)
gameId
gameId
未更改(整数,可 null)
appAttributionClickUrl
/
StartUrl
—(请参阅
…/attribution
)
移至归因资源
adomain
—🚫 消失
createdAt
/
updatedAt
—(不在 DTO 上)未在应用响应上公开
—
platform
,
iconUrl
,
projectId
,
testMode
,
kidsSettings
,
coppa
,
mixedAudience
new
⚠️ id 重新映射是风险最高的步骤持久
legacy campaignSetId → new {applicationId}
并重写使用
campaignSetId
的每个下游路径。

代码块 B — 广告素材

更改的内容

  • 嵌套在
    applications/{applicationId}
    而不是
    apps/{campaignSetId}
    下。
  • 仍然为
    multipart/form-data
    ,首先
    creativeInfo
    json,然后是 Binary 文件 Field。
  • 新建操作:
    PATCH …/creatives/{creativeId}
    (重命名)和
    DELETE …/creatives/{creativeId}
    。
  • type
    enum 值已重命名
    (snake_case)。重新映射。
  • 图像 Upload Limit 提高到 20 MB(为 5 MB);可播放项 10 MB。
  • 视频上传(
    videoFile
    )的工作方式与 Legacy
    完全相同(经 API 所有者确认)。OpenAPI 记录视频创建变体的架构于 2026 年 7 月下旬登陆 — 如果您复制了新建的 规范缺少视频
    oneOf
    变体,请刷新规范,而不是假设不支持视频。

type enum 重新映射

Legacy
type

新建
type

squareEndCard
end_card_square
endCardPair
end_card_pair
portraitVideo
video_portrait
landscapeVideo
video_landscape
responsivePlayable
playable_responsive
portraitPlayable
playable_portrait
landscapePlayable
playable_landscape
squareVideo
🚫 不支持 — 仅存在纵向/横向视频。表面。
—
banner
(新建)

status enum

未更改的设置:
uploaded
、
processing
、
processingFailed
、
pendingModeration
、
approved
、
rejected
.

多部分字Field名称

creativeInfo
(json, first) +
squareEndCardFile
、
portraitEndCardFile
+ 之一
landscapeEndCardFile
或
playableFile
。
creativeInfo
子对象引用文件的方式为
fileName
;可播放项也带有
orientation
(
landscape
/
portrait
/
both
)。响应为
CreativePublicResponseDto
(
id
,
name
,
language
,
type
,
status
,
files[]{name,url}
,
createdAt
,
updatedAt
).

代码块 C — 广告素材包

更改的内容

  • 在
    applications/{applicationId}
    下嵌套。CRUD 动词相同(GET/POST/GET/PATCH/删除)。
  • type
    获得
    banner
    值:
    video
    、
    playable
    、
    video+playable
    、
    banner
    。
  • 列表信封是 Legacy 样式
    { total, offset, limit, results[] }
    (与广告系列/广告素材不同)。
  • 响应更丰富:添加
    applicationId
    、
    moderationStatus
    (
    pending
    /
    approved
    /
    rejected
    、 nullable)、
    ageRating
    (nullable)、
    assignedCampaignIds[]
    、
    createdAt
    /
    updatedAt
    。

Field Mapping — 创建 (createCreativePack → CreateCreativePackPublicDto)

Legacy Field

新建 Field

注意

name
(必填)
name
(必填)
不变
creativeIds[]
(1–3)
creativeIds[]
未更改(24 个字符的十六进制广告素材 ID)
type
type
相同值 + 新建
banner
androidStoreListing
androidStoreListing
未更改(可为空)
appleProductPageId
appleProductPageId
未更改(UUID,可 null)

FieldMapping — 响应

Legacy Field

新建 Field

注意

id
id
24 个字符十六进制 — 未更改
name
,
type
,
creativeIds
相同不变
campaignIds
assignedCampaignIds
已重命名
—
applicationId
,
moderationStatus
,
ageRating
,
createdAt
,
updatedAt
新

代码块 D — 广告系列

更改的内容

  • 在
    applications/{applicationId}
    下嵌套。Get/Update/Delete 是每个应用;现在 列出 org 宽(
    GET …/organizations/{orgId}/campaigns
    、过滤器
    appIds
    )—没有每个应用的列表。
  • goal
    →
    optimizationType
    (+
    isCreativeTesting
    布尔值 +
    appEventType
    )。
  • **归因 URL 不再是广告系列创建的一部分。**通过广告系列创建后设置它们
    PATCH
    (
    attributionLinks
    )或应用归因终端(代码块 J)。
  • scheduleEnd
    不是创建 Field
    ,创建只需要
    start
    ;通过
    PATCH
    设置
    end
    。
  • GET campaign
    支持
    includeFields
    (
    bids
    、
    budget
    、
    creativePacks
    、
    application
    )—此 就是您现在读取出价/预算/分配的包的方式。
  • postInstallWindow
    值采用大写并已展开:
    D0
    、
    D1
    、
    D3
    、
    D7
    、
    D14
    、
    D28
    。

goal → optimizationType 重新映射

Legacy
goal

新建

installs
optimizationType: cpi
retention
optimizationType: legacyRetention
— ⚠️ Retention 已弃用**:不支持出价/资格。不要新建 Retention 广告系列;而是表面激活的广告系列。
roas
optimizationType: roas
(+
roasType
)
eventOptimization
optimizationType: appEventConversion
(+
appEventType
)
creativeTesting
isCreativeTesting: true
+ 底部用户手册优化(每个 API 所有者是目前唯一支持的底部,即用户手册 CPI:
optimizationType: cpi
、
cpiType: manual
)

Field Mapping — 创建 (createCampaign → CreateCampaignDto)

Legacy
goal

新建

installs
optimizationType: cpi
retention
optimizationType: legacyRetention
— ⚠️ Retention 已弃用**:不支持出价/资格。不要新建 Retention 广告系列;而是表面激活的广告系列。
roas
optimizationType: roas
(+
roasType
)
eventOptimization
optimizationType: appEventConversion
(+
appEventType
)
creativeTesting
isCreativeTesting: true
+ 底部用户手册优化(每个 API 所有者是目前唯一支持的底部,即用户手册 CPI:
optimizationType: cpi
、
cpiType: manual
)

Field Mapping — 更新(updateCampaign → UpdateCampaignPublicDto)

Legacy Field

新建 Field

注意

name
name
不变
scheduleStart
/
scheduleEnd
start
/
end
date → datetime;
end
nullable
enabled
(布尔值)
paused
(布尔值)
反转意义 —
enabled:true
≈
paused:false
autoStart
autoStart
(
ENABLED
/
DISABLED
)
uppercased
attributionClickUrl
/
StartUrl
attributionLinks.{clickUrl,startUrl,viewUrl}
现在是一个嵌套对象;
viewUrl
是新建的
⚠️ 更新响应是更瘦的对象(
CampaignPublicDetailsResponseDto
:
id
、
name
、
start
、
end
、
autoStart
、
paused
、
attributionLinks
),而不是完整的广告系列。 如果客户端关闭 PATCH 响应读取 Other Campaign 字段,请通过
GET campaign
重新获取。

Field Mapping — 响应(Legacy campaign → CampaignPublicResponseDto)

Legacy Field

新建 Field

注意

id
id
24 个字符十六进制 — 未更改
name
,
billingType
name
,
billingType
不变
goal
optimizationType
(+
isCreativeTesting
,
appEventType
,
roasType
)
上面的重新映射表(反向)
enabled
(布尔值)
paused
(布尔值)
⚠️ Inverted sense ON read too —
enabled:true
≈
paused:false
status
(
live
/
learning
/
paused
、ROAS)
—🚫 未 ON 新建响应。表面,如果客户端在其上分支。
scheduleStart
/
scheduleEnd
start
/
end
date → datetime;
end
nullable
biddingStrategy
(
manual
/
automated
)
bidConfigurationMethod
(
manual
/
auto
)
renamed + value Change (
automated
→
auto
)
cpiBids[]
/
sourceBids[]
/
roasBids[]
/
eventOptimizationBids[]
manualBids[]
/
manualSourceBids[]
/
roasBids[]
/
appEventBids[]
已重命名;仅与
includeFields=bids
一起存在;值以微美元为单位
retentionBids[]
—🚫 Retention bids 已弃用 — 无写入支持;将 Any 读取值视为仅Legacy
budget
budget
仅使用
includeFields=budget
;微美元 +
campaignLimitType
/
dailyLimitType
eventOptimizationType
/
sdkEventName
appEventType
/
sdkEventNames[]
enum 重命名;单一 → Array
autoStart
(
enabled
/
disabled
/
canceled
)
autoStart
(
ENABLED
/
DISABLED
/
CANCELED_REJECTED
/
CANCELED_LESS_THAN_TWO_PACK
)
大写;
canceled
拆分为两个原因
createdAt
/
updatedAt
createdAt
/
updatedAt
不变
—
applicationId
,
attribution
,
deviceTargeting
,
budgetPacingType
,
forcePausedEnabled
,
isAutoEligible
, …
new — 请参阅新规范

通过 includeFields 读取

Legacy 读取广告系列的出价/预算/分配的包使用单独的 GET。现在:
GET …/campaigns/{campaignId}?includeFields=bids,budget,creativePacks,application
.Bid 数组、
budget
、
creativePackIds[]
和完整
application
会返回到广告系列对象。

代码块 E — 出价(五个终端 → 一个)

更改的内容

五个 Legacy 子资源(
cpi-bids
、
source-bids
、
roas-bids
、
retention-bids
、
event-optimization-bids
),每个
GET
/
PUT
/
PATCH
超过美元字符串,折叠成一个 键入主体上的单一**
PATCH …/campaigns/{campaignId}/bids
(以微美元**为单位)。有 no GET - 通过
GET campaign?includeFields=bids
读取当前出价。

端点 + 身体重新映射

Legacy 子资源

在
UpdateCampaignPublicBidDto
中新建 body Field

每个入口形状(新建)

cpi-bids
manualBids[]
{ country, bid }
(以微秒为单位的
bid
)
source-bids
manualSourceBids[]
{ country, sourceAppId, bid }
(micros)
roas-bids
roasBids[]
{ country, target, maxBid? }
(
maxBid
micros)
event-optimization-bids
appEventBids[]
{ country, bid }
(micros)
retention-bids
🚫 已弃用 — 不支持Legacy
{country, baseBid, maxBid}
没有后继者(已确认)。不迁移;将 Any Client Retention-bid usage 表面提供给人类。

资金变换(关键)

Legacy dollar 字符串 → 新建微美元:乘以 1_000_000。
"0.201"
→
201000
。ROAS
goal
/
target
(已确认):Legacy ROAS
goal
是一个百分比字符串(
"12.34"
= 12.34%); 新建
target
是小数比率 - 除以 100(
"12.34"
→
0.1234
; 10% →
0.10
)。 语义(由 API 所有者确认):

Legacy PUT/PATCH 模型

新建模型

PUT
替换整个设置;
PATCH
合并
单一
PATCH
取代给定类型的完整出价设置,不存在 MERGE。始终发送完整的所需设置。
清除出价(已确认):为
PATCH
中的该出价类型发送空 Array
[]
- 相同 作为 Legacy
PUT []
的特效。
⚠️ 由于新建
PATCH
取代了而不是合并了 Legacy
PATCH
的纯粹端口(MERGE) Calls 将悄悄丢弃请求中未包含的每个出价。转换旧版合并样式 对完全设置的写入的更新:通过
GET campaign?includeFields=bids
读取当前出价,Apply delta 本地,并发送完整的 Array。

F 代码块 — Budget → Budget Cap

更改的内容

  • GET …/budget
    已消失 → 通过
    GET campaign?includeFields=budget
    读取。
  • PATCH …/budget
    →
    PATCH …/campaigns/{campaignId}/budget-cap
    .
  • 美元 → 微美元(字符串)。
  • 每个国家映射(
    dailyPerCountry: { "US": "123.45", … }
    )替换为 指定国家组(
    countryGroupDailyLimits: [{ name, countries[], limit }]
    )。
  • ON 响应新建显式类型鉴别器:
    campaignLimitType
    (
    unlimited
    /
    total
    )、
    dailyLimitType
    (
    daily
    /
    countryDaily
    /
    unlimited
    ).

Field Mapping(budget → PatchBudgetCapDto)

Legacy Field

新建 Field

注意

total
(美元字符串)
total
(微字符串)
×1e6。Cap 表示语义继承自 Legacy(每个 API 所有者):
"0"
仍然意味着“无上限”。
daily
(美元字符串)
daily
(微字符串)
×1e6
dailyPerCountry
(映射)
countryGroupDailyLimits[]
**重组:**每个
{country: amount}
成为组
{ name, countries:[country], limit: amount×1e6 }
。按客户端偏好进行组;需要
name
。
dailySpent
/
spent
(只读)
—(通过广告系列预算读取)显示 ON 广告系列预算已读,而不是 PATCH 响应

代码块 G — 定向投放

更改的内容

  • GET …/targeting
    消失→ 关闭
    GET campaign
    读取定向字段。
  • PATCH …/targeting
    仍然存在,但主体已重组,大多数 Legacy 设备字段 已丢弃(它们已经是 Legacy 规范中的
    deprecated
    )。

Field Mapping(targetingOptions → UpdateCampaignPublicTargetingDto)

Legacy Field

新建 Field

注意

appTargeting.allowList
/
blockList
allowlistSources[]
/
blocklistSources[]
已重命名(音频源应用程序 ID)
categoryTargeting.allowList
/
blockList
apptopiaSourceCategoriesAllowlist/Blocklist[]
(+
sensorTower…
)
现在提供程序指定的 Category 列表
deviceTargeting
iOS
blockedDevices
/
osMin
appleDevice.deviceBlocklist[]
/
appleDevice.osMinVersion
重组
deviceTargeting
Android
osMin
+ 制造商/模型
androidDevice.{manufacturerAllowlist,manufacturerBlocklist,modelBlocklist,osMinVersion}
重组
regionalTargeting
allowlistCountrySubdivisions[] {country, subdivisions[]}
现在基于 Subdivision-id
limitedAdTracking
,
connectionType
,
screenSize
,
screenDensity
,
allowedDevices
,
osMax
—🚫已移除(已确认 — 无法统一配置 ON)。删除设置它们的客户端代码;向人类提及放置。

代码块 H — 已分配的广告素材包(现在基于列表)

更改的内容

  • Legacy 已分配/未分配每个请求打包(
    POST
    /
    DELETE …/assigned-creative-packs
    )。
  • 新建 API 在列表上运行:
    • 与
      { creativePackIds: [...] }
      PATCH …/campaigns/{campaignId}/assign-creative-pack
      — 将分配的设置替换为提供的 ID。
    • 与
      { creativePackIds: [...] }
      DELETE …/campaigns/{campaignId}/unassign-creative-pack
      — 删除列出的 ID。
  • 当前分配的包列表:
    GET campaign?includeFields=creativePacks
    (
    creativePackIds[]
    )。

迁移方法

收集客户端分配给广告系列的所有包,然后 make one
PATCH assign-creative-pack
使用完整 Array(而不是 N
POST
)。语义已确认:终端取代了 使用提供的
creativePackIds
完成分配
- 始终发送所需的完整设置,或 Array 中省略的包未分配。

代码块 I — 推广受众智能定位 → 广告系列管理

更改的内容

Legacy

新建

GET …/audience-pinpointer/sdk-event-names
GET …/applications/{id}/sdk-event-names
GET …/audience-pinpointer/event-optimization-info
GET …/applications/{id}/eligibility
GET …/audience-pinpointer/roas-info
🚫 已移除 — ROAS 广告系列不再需要资格;删除任何门控逻辑
GET …/audience-pinpointer/retention-info
🚫 已移除 — 留存已完全弃用;表面 Active 留存用途
sdk-event-names
response:
{ total, results[]{ eventOptimizationType, sdkEventNames[] } }
。
eligibility
response:
{ total, results[]{ eventOptimizationType, countries[] } }
。

代码块 J — 归因(已重新分配)

更改的内容

以前在应用程序上设置过归因 URL(
appAttributionClickUrl
/
StartUrl
)并通过 进入广告系列创建。新建 API 有一个专用应用关卡归因资源 Plus ON 广告系列更新的每个广告系列
attributionLinks
。
  • GET …/applications/{applicationId}/attribution
    →
    { id, startUrl, clickUrl, viewUrl?, partner, type?, createdAt, updatedAt }
    .
  • 与
    { startUrl?, clickUrl?, viewUrl? }
    PATCH …/applications/{applicationId}/attribution
    。
partner
enum:
other
、
adjust
、
airbridge
、
appsflyer
、
branch
、
bytebrew
、
kochava
、
mailru
、
singular
、
tenjin
、
yandex
。
type
enum:
userLevel
、
nonUserLevel
、
mixed
。

迁移方法

  1. Move 应用关卡
    appAttributionClickUrl
    /
    appAttributionStartUrl
    →
    PATCH …/attribution
    (
    clickUrl
    /
    startUrl
    ).
  2. Move campaign-创建
    attributionClickUrl
    /
    attributionStartUrl
    → ON 广告系列的
    PATCH
    (
    attributionLinks.{clickUrl,startUrl,viewUrl}
    )创建广告系列后。
  3. viewUrl
    是新建的(可选)。
    {ifa}
    和其他网址宏:验证规则来自共享的 Legacy 和新建 API(已确认)都使用的归因验证库,因此宏 行为不变 — 保持 Legacy URL 原样。

建议的迁移算法(Agent的确定性Order)

  1. **配置:**将主机交换为
    …/ads/advertiser
    、路径前缀
    /advertise/v1
    →
    /public/v1
    以及
    apps
    细分段 →
    applications
    。保持 Basic 身份验证。
  2. **应用程序(代码块 A):**对于每个 Legacy 应用程序,
    POST …/applications
    (重新映射
    store
    →
    {store, platform}
    )。持久
    legacy campaignSetId → new applicationId
    。不发送归因 此处的 URL。
  3. **归因(代码块 J):**与旧的应用关卡 URL
    PATCH …/applications/{id}/attribution
    。
  4. **创作者(代码块 B):**重新 Upload/重新映射,转换
    type
    enum。持久
    legacy creativeId → new creativeId
    是否重新铸造了 ID(验证是否保留了 ID)。
  5. **广告素材包(代码块 C):**创建引用新建广告素材 ID 的包。
  6. **广告系列管理(代码块 I):**重新点受众定位查找 —
    …/audience-pinpointer/sdk-event-names
    →
    …/applications/{id}/sdk-event-names
    ,然后
    …/audience-pinpointer/event-optimization-info
    →
    …/applications/{id}/eligibility
    .只读; 使用结果向广告系列
    appEventType
    /
    sdkEventNames
    和符合条件的国家/地区提供信息。 可以直接删除 ROAS 信息门控逻辑(不再需要资格);Retention 信息是 与已已弃用的Retention商品一起消失(请参阅步骤 13)。
  7. **广告系列(代码块 D):**使用
    optimizationType
    创建 (+
    isCreativeTesting
    /
    appEventType
    /
    roasType
    ),仅限
    start
    。然后
    PATCH
    设置
    end
    、
    attributionLinks
    、
    autoStart
    、
    paused
    。
  8. 出价(代码块 E):兑换美元 → 微美元(ROAS 目标:百分比 → 小数比率, ÷100); 发送一个
    PATCH …/bids
    ,其中包含每个出价类型的
    完整
    所需设置(PATCH) 替换,从不合并;
    []
    清除)。留存出价已弃用,请勿迁移它们; 表面 Any 用法。
  9. **Budget(代码块 F):**以微美元为单位的
    PATCH …/budget-cap
    ;转换
    dailyPerCountry
    映射 →
    countryGroupDailyLimits[]
    .
  10. **定向投放(代码块 G):**重组为
    appleDevice
    /
    androidDevice
    /音频源+ Category 列表; 放置已移除的设备字段(将它们表面)。
  11. **分配(代码块 H):**每个广告系列一个基于列表的
    PATCH assign-creative-pack
    。
  12. **阅读:**将所有
    GET …/{bids,budget,targeting,assigned-creative-packs}
    替换为
    GET campaign?includeFields=…
    .
  13. 已移除功能(表面对人类):
    DELETE app
    (USF 拥有的应用程序生命周期;删除 当前已Disabled)、已已弃用的Retention商品(出价 + 资格)、ROAS 资格 门禁(不再需要 - 将其删除)、Legacy 已弃用的目标字段、
    adomain
    和
    squareVideo
    广告素材。

验证核对表(迁移后运行)

  • 请求路径不包含
    /advertise/v1
    、
    /apps/
    、
    /cpi-bids
    、
    /source-bids
    、
    /roas-bids
    ,
    /retention-bids
    ,
    /event-optimization-bids
    ,
    /audience-pinpointer
    ,
    /assigned-creative-packs
    或
    …/budget
    (现为
    budget-cap
    )。
  • 每个应用程序路径都使用新建的 UUID
    applicationId
    ,而不是 24 个字符的十六进制
    campaignSetId
    。
  • All money values are micro dollars(整数), never dollars decimals like
    "2500.20"
    .
  • 出价转到单一
    PATCH …/bids
    ;读取使用
    GET campaign?includeFields=bids
    。
  • 每个广告
    PATCH
    都会发送其广告类型的完整设置(替换语义 - 部分 send 会丢弃省略的出价)LegacyMERGE样式的更新已转换为 read-Modify-write。
  • ROAS 目标已从百分比字符串转换为小数比(
    "12.34"
    →
    0.1234
    )。
  • Budget 使用
    budget-cap
    +
    countryGroupDailyLimits[]
    (无
    dailyPerCountry
    映射)。
  • 广告系列
    goal
    已重新映射到
    optimizationType
    (+
    isCreativeTesting
    ) 和归因 URL 是通过
    attributionLinks
    /
    …/attribution
    设置的,而不是广告系列创建。
  • Creative
    type
    使用新建的 snake_case 值(
    end_card_square
    、
    video_portrait
    等)。
  • Legacy
    enabled
    的每次读取都重新映射到
    paused
    ,意义反转 (
    enabled:true
    ⇒
    paused:false
    ) — ON 列表、获取和更新响应。
  • 关闭广告系列
    PATCH
    响应时,没有任何内容会解析完整的广告系列字段(它会返回瘦身 细节对象);通过
    GET campaign?includeFields=…
    重新获取完整状态。
  • 应用程序列表解析需要裸数组(没有
    {total, results}
    包络)并且不再 发送
    offset
    /
    limit
    /
    filter[store]
    /
    filter[storeId]
    。
  • 分配使用每个广告系列一个基于列表的调用,而不是 N 个单一个分配。
  • DELETE app
    、已弃用 Retention 用途(出价/资格)、
    squareVideo
    广告素材以及 Any 已移除的目标字段作为空白显示给人类(如果客户端使用了它们);ROAS 删除了资格审查。

快速参考:已移除 / 无等效内容(请勿迁移或制作 - All confirmed by API owner)

  • DELETE app
    — 没有删除应用程序终端;应用程序生命周期归 USF 所有,删除 当前在平台宽内Disabled。
  • ROAS 信息 — 已移除;ROAS 广告系列不再需要资格。删除门控逻辑。
  • ** Retention(整个商品区域)** - 已弃用:
    retention-info
    和 Retention 出价没有 继承者。表面 Active Retention 广告系列/出价。
  • 获取出价/预算/定向投放/分配资源包 — 替换为
    GET campaign?includeFields=…
    。
  • Legacy 已弃用的目标字段(
    limitedAdTracking
    、
    connectionType
    、
    screenSize
    、
    screenDensity
    、
    allowedDevices
    、
    osMax
    )和应用**
    adomain
    ** — 无法 ON Configured unified;删除客户端代码。
  • squareVideo
    广告素材类型
    — 不支持;仅支持
    video_portrait
    /
    video_landscape
    。