LLM 코딩 에이전트용 퍼블리셔 공용 API 마이그레이션 레퍼런스

잠재 고객: 이 파일은 LLM 코딩 에이전트(Claude Code 또는 similar)는 레거시 Unity "Monetize"에서 클라이언트 통합을 마이그레이션합니다. 새로운 Unity Ads 퍼블리셔 공용 API 관리(

/monetize/v1/...

) (

/ads/publisher/public/v1/...

). 그것은 독립적인 엔티티 블록으로 분할됩니다. 각 차단 상태 변화 및 정확히 어떻게 해야 하는. 개념 모델 변경 및 먼저 전역 변경 섹션 - 모든 차단에 적용됩니다.

이 파일을 사용하는 방법(에이전트 지침)

1. 이 프로시가 아니라 두 계약을 진실의 근원으로 취급합니다. 레거시 =

   ads-selfserve/src/servers/http-internal/openapi/public-v1.yaml

   . New =

   ads-unified-platform/openapi/publisher/platform-public-v1-routes.yaml

   .
2. 지정된 순서로 한 번에 한 엔티티 차단을 마이그레이션합니다(애플리케이션 → 플레이스먼트 → org 레벨 목록). 의존 중인 블록이 컴파일/패스하기 전에는 차단 시작하지 않습니다.
3. 레거시 기능이 ± No equivalent 아래에 나열되면**** 엔드포인트 중지하고 인간에게 열린 질문으로 표면. 가장 중요 예제 는 새로운 API에 존재하지 않는 eCPM 타겟입니다.
4. 각 차단 후 필드 테이블별로 필드 이름을 다시 매핑합니다. 필드가 이동된 것으로 간주하지 마십시오. 표에 "unchanged"라고 표시되지 않는 한 변경되지 않습니다.

개념 모델 변경(첫 번째 읽기)

레거시 모델(중첩, 프로젝트 중심)

조직└── 프로젝트(두 스토어 모두 포함, coppa + adsProvider 포함)    └── 스토어 (apple | google) (URL 경로)        └── Ad-Unit(adFormat, 건너뛰기/음소거/배너 설정 라이브)            └── 플레이스먼트                └── eCPM 타겟(기하 기반 단가)

새로운 모델(플랫, 애플리케이션 중심)

조직└── 애플리케이션(플랫폼 하나 + 각각 하나의 스토어, 개인정보 보호 기능 + testMode 포함)    └── 플레이스먼트(adFormat + adFormatConfigurations는 여기에 라이브, 타겟 없음)조직└── 테스트 기기(새로운, 조직 범위)

모든 변환, 변형 유도하는 4가지 쉬프트

apple

google

projectId

projectName

adFormatConfigurations

adFormat

POST

PUT

DELETE

전역 변경 사항(모든 엔드포인트에 적용)

https://services.api.unity.com

https://services.api.unity.com/ads/publisher

https://staging.services.api.unity.com/ads/publisher

/monetize/v1

/public/v1

…/monetize/v1/organizations/{orgId}/projects

…/ads/publisher/public/v1/organizations/{organizationId}/applications

unity

ads

organizationId

organizationId

projectId

applicationId

dryrun

showarchived

isArchived

archive: true/false

DELETE

PATCH …/restore

속도 제한이 변경됨(클라이언트 측 백오프 가정 업데이트)

GET

POST

PATCH

PUT

DELETE

마스터 엔드포인트 맵

getProjects

GET /monetize/v1/organizations/{orgId}/projects

publicOrganizationApplications

GET /public/v1/organizations/{orgId}/applications

postProjects

POST /monetize/v1/organizations/{orgId}/projects

publicCreateApplication

POST /public/v1/organizations/{orgId}/applications

getProjectDetails

GET /monetize/v1/projects/{projectId}

publicGetApplicationById

GET /public/v1/organizations/{orgId}/applications/{applicationId}

updateProjectDetails

PATCH /monetize/v1/projects/{projectId}

publicUpdateApplication

PATCH /public/v1/organizations/{orgId}/applications/{applicationId}

getAdUnitsByProject

getAdUnitsByProjectStore

createAdUnits

updateAdUnits

getAdUnits

patchAdUnits

…/projects/{projectId}/[stores/{storeName}/]adunits[/{adUnitId}]

createPlacements

POST …/adunits/{adUnitId}/placements

publicCreatePlacement

POST /public/v1/organizations/{orgId}/applications/{applicationId}/placements

GetPlacements

GET …/adunits/{adUnitId}/placements

publicApplicationPlacements

GET …/applications/{applicationId}/placements

getPlacement

GET …/placements/{placementId}

publicGetPlacementDetails

GET …/applications/{applicationId}/placements/{placementId}

updatePlacements

updatePlacement

PATCH …/placements[/{placementId}]

publicUpdatePlacement

PUT …/applications/{applicationId}/placements/{placementId}

archive:true

PATCH …/placements/{placementId}

publicArchivePlacement

DELETE …/applications/{applicationId}/placements/{placementId}

archive:false

PATCH …/placements/{placementId}

publicUnArchivePlacement

PATCH …/applications/{applicationId}/placements/{placementId}/restore

GetPlacements

GET /monetize/v1/organizations/{orgId}/placements

publicOrganizationPlacements

GET /public/v1/organizations/{orgId}/placements

getTargets

createTargets

getTargetDetail

patchTarget

deleteTarget

…/placements/{placementId}/targets[/{targetId}]

publicGetApplicationTestMode

publicUpdateApplicationTestMode

GET

PATCH …/applications/{applicationId}/test-mode

…/organizations/{orgId}/test-devices[/{testDeviceId}]

차단 A - 프로젝트 → 응용 프로그램

변경한 사항

• 나열/생성/읽기/업데이트하는 리소스는 이제 프로젝트가 아니라 애플리케이션입니다.
• 읽기/업데이트는 이제 org(

  /organizations/{orgId}/applications/{applicationId}

  ) 아래에 중첩됩니다. 스탠드얼론

  /projects/{projectId}

  가 아닌

  applicationId

  (Unity App ID)가 키를 입력합니다.
• 레거시 프로젝트는 둘 다 저장소를 가져왔습니다. 새로운 애플리케이션은 단일 플랫폼입니다. 분할 변환하다(동사), 트랜스폼(명사) 규칙을 참조하십시오.

• adsProvider

  가 사라졌습니다. 열거형 문자열에서 부울로 변경된

  coppa

  는 새로운

  mixedAudience

  부울 옆의

  privacy

  오브젝트

엔드포인트 매핑

GET …/organizations/{orgId}/projects

GET …/organizations/{orgId}/applications

POST …/organizations/{orgId}/projects

POST …/organizations/{orgId}/applications

GET …/projects/{projectId}

GET …/organizations/{orgId}/applications/{applicationId}

PATCH …/projects/{projectId}

PATCH …/organizations/{orgId}/applications/{applicationId}

필드 매핑 — 생성 (createProject → CreateApplicationPublicDto)

name

name

adsProvider

coppa

"compliant"

"non_compliant"

privacy.coppa

"compliant"

true

"non_compliant"

false

privacy.mixedAudience

privacy

false

stores.apple

stores.google

{storeId, storeUrl}

store

storeId

platform

platform

iOS

Android

iconUrl

projectId

projectName

필드 매핑 — 업데이트(updateProject → UpdateApplicationPublicDto)

adsProvider

coppa

privacy.coppa

privacy.*

stores

store

storeId

name

kidsSettings

true

필드 매핑 — 응답 (project/projectDetail → ApplicationPublicResponseDto)

id

id

projectId

id

projectId

name

name

coppa

coppa

mixedAudience

adsProvider

stores

store

storeId

platform

archivedAt

maxCaps

iconUrl

testMode

kidsSettings

변환하다(동사), 트랜스폼(명사): 하나의 레거시 프로젝트 → N 응용 프로그램

stores.apple

stores.google

POST /applications

platform: iOS

store: AppleAppStore

storeId: <apple.storeId>

platform: Android

store: GooglePlay

storeId: <google.storeId>

projectName: <project.name>

projectId

projectId

예제

POST /monetize/v1/organizations/3573617062594/projects{  "name": "내 게임",  "adsProvider": "unity",  "coppa": "non_compliant",  "stores": {    "apple":  { "storeId": "1479198816", "storeUrl": "https://apps.apple.com/..." },    "google": { "storeId": "com.unity.trashdash", "storeUrl": "https://play.google.com/..." }  }}

POST /ads/publisher/public/v1/organizations/3573617062594/applications{  "name": "내 게임",  "platform": "iOS",  "store": "AppleAppStore",  "storeId": "1479198816",  "privacy": { "coppa": false, "mixedAudience": false },  "projectName": "내 게임"}// → response.projectId = "5a8591dd-..."; reuse it for the second app:POST /ads/publisher/public/v1/organizations/3573617062594/applications{  "name": "내 게임",  "platform": "Android",  "store": "GooglePlay",  "storeId": "com.unity.trashdash",  "privacy": { "coppa": false, "mixedAudience": false },  "projectId": "5a8591dd-..."}

차단 B — Ad-Units → 제거(애플리케이션 + 플레이스먼트로 접히기)

□ 동등한 리소스 없음

…/projects/{projectId}/[stores/{storeName}/]adunits…

getAdUnitsByProject

getAdUnitsByProjectStore

createAdUnits

updateAdUnits

getAdUnits

patchAdUnits

광고 유닛 데이터가 이동한 위치

adFormat

rewarded

interstitial

banner

adFormat

allowSkipInSeconds

muteVideo

adFormatConfigurations.adminSettings.{allowSkipInSeconds, muteVideo}

bannerRefreshRate

adFormatConfigurations.bannerRefreshRate

adTypes

display

playable

video

placements

adFormat

adFormatConfigurations

차단 C — 플레이스먼트(애플리케이션별)

변경한 사항

• 경로가 이제

  …/applications/{applicationId}/placements[/{placementId}]

  — 스토어/다음 단위 없음 세그먼트。
• 개별 작업은 배치 맵/배열을 대체합니다.
• 각 플레이스먼트에 대한

  adFormat

  가 필요(유닛 프로퍼티였음).
• 새

  adFormatConfigurations

  오브젝트는 플레이어/관리자 설정을 포함합니다. 모양은

  adFormat

  (보상형 광고/인터스티셜 광고/배너).
• 배치 바디에서 eCPM

  targets

  가 사라집니다(차단 E 참조).
• 식별자: 레거시

  placementId

  는 슬러그(

  ^[\da-zA-Z_-]+$

  ); 새로운 배치

  id

  는 UUID, 인간이 읽을 수 있는 슬러그는 별도로

  key

  (

  name

  에서 생성)로 반환됩니다.
• 복원그 아닌 전용 작업입니다.
• 플레이스먼트별 업데이트는 (전체 대체)이며

  PUT

  , 아닙니다

  PATCH

  .

엔드포인트 매핑

POST …/adunits/{adUnitId}/placements

POST …/applications/{applicationId}/placements

GET …/adunits/{adUnitId}/placements

GET …/applications/{applicationId}/placements

isArchived

adFormat[]

GET …/placements/{placementId}

GET …/applications/{applicationId}/placements/{placementId}

PATCH …/placements/{placementId}

PUT …/applications/{applicationId}/placements/{placementId}

PATCH …

{"archive": true}

DELETE …/placements/{placementId}

PATCH …

{"archive": false}

PATCH …/placements/{placementId}/restore

필드 매핑 — 요청 (addPlacements[] / patchPlacementObject → PlacementPublicRequestDto)

name

name

id

id

key

adFormat

rewarded

interstitial

banner

adFormat

addTargets

targets

placementType

archive

DELETE

restore

adFormatConfigurations

adFormatConfigurations 모양(adFormat 기준)

• 보상형 광고(

  RewardedConfigurations

  ):

  name

  (보상 이름, 필수),

  value

  (보상형 광고, required),

  adminSettings

  (

  AdminConfigurations

  ).
• 인터스티셜 광고 (

  InterstitialConfigurations

  ):

  adminSettings

  .
• 배너 (

  BannerConfigurations

  ):

  adminSettings

  ,

  bannerRefreshRate

  (필수).

• AdminConfigurations

  :

  allowSkip

  ,

  allowSkipInSeconds

  ,

  videoPlayableSkipInSeconds

  ,

  closeTimerDuration

  ,

  tapsToClose

  ,

  muteVideo

  ,

  disableVideoControlsFade

  ,

  useCloseIconInsteadOfSkipIcon

  .

필드 매핑 — 응답 (placement → PlacementPublicResponseDto)

id

key

key

id

name

name

archivedAt

archivedAt

null

placementType

targets

adFormat

status

active

paused

adFormatConfigurations

applicationId

createdAt

updatedAt

⚡️ ID 다시 매핑은 가장 높은 위험 단계입니다. 클라이언트 레거시 플레이스먼트를 유지한 위치 슬러그는 이제 경로 작업을 위해 새 UUID

id

를 저장해야 하며, 슬러그는

key

로 살아남는다. 빌드하고 유지하는 동안의

legacy placement slug → new {id, key}

룩업 마이그레이션。

예제

POST /monetize/v1/projects/{projectId}/stores/apple/adunits/{adUnitId}/placements[ { "name": "Rewarded Placement", "id": "rewarded_01",    "addTargets": [ { "value": 18.5, "type": "global" } ] } ]

POST /ads/publisher/public/v1/organizations/{orgId}/applications/{applicationId}/placements{  "name": "보상형 광고 배치",  "adFormat": "rewarded",  "adFormatConfigurations": {    "name": "coins",    "value": 100,    "adminSettings": { "allowSkip": true, "allowSkipInSeconds": 5, "muteVideo": false }  }}

차단 D — 조직 배치 목록

변경한 사항

targets

adFormat

platform

storeId

id

placementId

엔드포인트 매핑

GET /monetize/v1/organizations/{orgId}/placements

GET /public/v1/organizations/{orgId}/placements

필드 매핑(placementWithGameId → OrganizationPlacementPublicResponseDto)

id

placementId

Banner_Android

name

name

placementType

placementType

bidding

gameId

gameId

targets

adFormat

rewarded

interstitial

banner

native

platform

ios

android

""

""

storeId

차단 E - eCPM 타겟 제거

± 새로운 공용 API 해당하는 항목이 없습니다.

getTargets

createTargets

getTargetDetail

patchTarget

deleteTarget

targets

addTargets

1. 이를 새 엔드포인트에 매핑 하지 마십시오.

   …/targets

   경로를 생성하지 마십시오.
2. 모든 플레이스먼트 생성/업데이트 페이로드에서

   targets

   /

   addTargets

   를 제거합니다.
3. 이 API를 통해 클라이언트의 통합이 eCPM 기본 가격을 관리하는 경우 이 값을 중지하고 인간의 차단점 — eCPM 대상 관리가 새로운 퍼블리셔에 포함되지 않음 공용 API 및 대역에서 처리해야 합니다(예: 다른 Unity 표면 또는 제품을 통해 처리) decision). 명시적으로 플래그를 플래그. 가격 로직을 표시하지 않고는 자동으로 내보내지 마십시오.

차단 F — 애플리케이션 테스트 모드(신규)

• GET …/applications/{applicationId}/test-mode

  →

  { id, testMode }

• PATCH …/applications/{applicationId}/test-mode

  와

  { "testMode": "forceAll" | "forceOff" }

testMode

차단 G — 테스트 장치(새로운 장치)

• POST …/organizations/{orgId}/test-devices

  —

  CreateTestDevicePublicDto

  { name*, advertisingId*, platform? }

• GET …/organizations/{orgId}/test-devices

  — 목록(옵션

  platform

  필터)

• GET …/organizations/{orgId}/test-devices/{testDeviceId}

  — get one

• PATCH …/organizations/{orgId}/test-devices/{testDeviceId}

  —

  UpdateTestDevicePublicDto

• DELETE …/organizations/{orgId}/test-devices/{testDeviceId}

  — 204

testDeviceId

platform

Android

iOS

OSX

Windows

Linux

WebGL

Windows_Store

PS4

PS5

XboxOne

tvOS

Switch

VisionOS

권장 마이그레이션 알고리즘(에이전트 결정적 순서)

1. 설정: 지지대 호스트를

   …/ads/publisher

   와 경로 접두사

   /monetize/v1

   →

   /public/v1

   로 변경합니다. 기본 인증을 유지합니다. 모든

   dryrun

   파라미터를 제거합니다.
2. 애플리케이션(차단 A): 각 레거시 프로젝트에 대해 스토어당 하나의 애플리케이션을 생성합니다. 변환하다(동사), 트랜스폼(명사)

   coppa

   열거형→부울, 드롭

   adsProvider

   , 설정

   platform

   /

   store

   /

   storeId

   . 을 통한 그룹화

   projectName

   /

   projectId

   .

   legacy projectId+store → new {applicationId, projectId}

   맵을 유지합니다.
3. 플레이스먼트(차단 C): 각 레거시 배치에 대해 맵에서 소유 애플리케이션을 결정합니다.

   adFormat

   (레거시 ad-unit에서) +

   adFormatConfigurations

   로 개별적으로 생성 (ad-unit/admin 설정에서) 드롭

   targets

   /

   addTargets

   . 지속

   legacy placement slug → new {id, key}

   .
4. 포인트 변경 식별자: 저장된 레거시 배치 슬러그를 경로에 대한 새 UUID

   id

   로 대체 ops(표시할

   key

   유지). 저장된

   projectId

   기반 앱 리프를

   applicationId

   로 교체합니다.
5. 아카이브 시맨틱:

   archive:true/false

   PATCH 호출을

   DELETE

   /

   PATCH …/restore

   로 대체한다.
6. 리스트/읽기 모양: 필드 테이블별로 응답 파싱 업데이트(esp. org list - 차단 D).
7. eCPM 타겟(차단 E): 타겟 코드를 제거하고, 인간에게 공백을 보고한다.
8. 선택적인 새로운 기능: 요청 시에만 테스트 모드(F) 및 테스트 장치(G)를 연결합니다.
9. 속도 제한: 캡은 ≤1/s 및 ≤60/hour에서 생성되고, 값은 ≤20/s입니다.

확인 체크리스트(마이그레이션 후 실행)

• 요청 경로에는

  /monetize/v1

  ,

  /projects/{

  ,

  /adunits

  ,

  /stores/

  또는

  /targets

  가 포함되어 있지 않습니다.
• 요청 바디에는

  adsProvider

  ,

  addTargets

  ,

  targets

  또는

  archive

  가 포함되어 있지 않습니다.

• coppa

  는 모든 곳에서 부울(아무

  "compliant"

  /

  "non_compliant"

  없음).
• 모든 플레이스먼트 생성/업데이트는 유효한

  adFormat

  및

  adFormatConfigurations

  를 전송합니다. 형식과 일치합니다.
• 플레이스먼트 경로 파라미터는 레거시 슬러그(

  key

  )가 아니라 새 UUID

  id

  를 사용합니다.
• 두 개의 상점이 있는 레거시 프로젝트는 하나의

  projectId

  를 공유하는 두 개의 애플리케이션을 생성했습니다.
• eCPM 타겟 관리는 클라이언트 지원하지 않는 공백으로 나타났습니다.

빠른 레퍼런스: 제거됨/동등하지 않음(마이그레이션 또는 제조하지 않음)

• 모든 Ad-Unit 엔드포인트와 ad-unit 리소스
• 모든 eCPM 타겟 엔드포인트 및

  targets

  /

  addTargets

  필드
• 프로젝트

  adsProvider

  및

  maxCaps

  .

• dryrun

  및

  showarchived

  쿼리 파라미터
• 클라이언트가 선택한 플레이스먼트 ID(서버가 UUID를 할당하고 슬러그를

  key

  로 유지).