Міграція на Unity Advertiser Public API: що змінилося

У вересні 2026 року Advertiser Public API замінив Advertising Management API (/advertise/v1). Якщо ваші скрипти чи сервіси ходять у старий API, їх доведеться переписувати: у нового інша база й префікс шляху, id апок стали UUID, гроші передаються в мікродоларах, частину полів перейменовано, частину прибрано. Дати вимкнення старого API в документації Unity немає.

Що Unity написала про заміну

Запис за вересень 2026 на сторінці What’s new in User Acquisition каже прямо: Advertiser Public API замінює Advertising Management API (/advertise/v1), а кому є інтеграція зі старим API, тому потрібно перейти на новий. Сторінка про керування кампаніями через API називає /advertise/v1 попередньою версією advertiser API. Через новий можна програмно керувати апками, кампаніями, ставками, ставками за сорсами й ROAS-цілями, бюджетами, креативами та креативними паками. У дашборді він лежить у Settings > API management.

Докладну мапу перенесення Unity винесла на окрему сторінку, Advertiser API migration reference. Усе нижче про маршрути, поля й порядок узято звідти. Сторінка сама каже, що написана для LLM-агентів, які пишуть код, а з дати на ній лише позначка «Last updated 2 months ago». Читається як довідник, а не як інструкція для людей.

Нова база й префікс шляху

Хост лишається колишнім, services.api.unity.com. Змінюються база й шлях:

prod:    https://services.api.unity.com/ads/advertiser
staging: https://staging.services.api.unity.com/ads/advertiser

Що	Старий API	Новий API
Префікс шляху	/advertise/v1	/public/v1
Апка в шляху	apps/{campaignSetId}	applications/{applicationId}
Авторизація	HTTP Basic (ключ service account)	HTTP Basic працює, додатково приймається Bearer JWT

Приклад нового маршруту зі сторінки Unity:

…/ads/advertiser/public/v1/organizations/{orgId}/applications/{applicationId}/campaigns

Ключ service account лишається тим самим, але потрібні ролі й дозволи інші. Тому 403 із тим самим ключем, за довідником Unity, означає невидану роль, а не помилку в запиті. Як це шукати й лагодити, розібрано в статті про помилку 403 Invalid Credentials. Якщо у вас кілька організацій, ролі перевіряйте в кожній: про підключення кількох організацій є сторінка про кабінети.

Id апок: із campaignSetId в UUID

Раніше апку визначали через campaignSetId, 24 символи hex. Тепер це applicationId у форматі UUID. Unity радить зберегти таблицю відповідності «старий id → новий»: без неї старі дані з новими маршрутами не звʼяжете.

Id кампаній, креативів і creative packs не змінюються, це, як і раніше, 24 символи hex. Чи переживає id креатива повторне завантаження, сторінка не каже й пропонує перевірити самому.

Гроші в мікродоларах

Раніше суми були десятковими рядками в доларах. Тепер це цілі числа в мікродоларах, 1 USD дорівнює 1 000 000. Приклади зі сторінки Unity: "2500.20" перетворюється на "2500200000", а ставка "0.201" на 201000. Зверніть увагу: у прикладах Unity сума подана в лапках, ставка без. Точний тип поля звіряйте зі схемою, а не з цією статтею.

Ціль за ROAS теж змінилася. Було goal із відсотком рядком ("12.34"), стало target із часткою числом (0.1234).

Переводити множенням на 1e6 не варто: дробове число біля межі округлення може дати хвіст. Надійніше різати рядок:

// "2500.20" -> 2500200000n, "0.201" -> 201000n
// знаки після шостого відкидаються, відʼємні суми не перевірялися
function usdToMicros(usd) {
  const [whole, frac = ""] = String(usd).split(".");
  return BigInt(whole + frac.padEnd(6, "0").slice(0, 6));
}

Перейменовані поля

Вибірка з довідника Unity:

Було	Стало	Примітка
store	store + обовʼязковий platform	платформу тепер треба вказувати
goal	optimizationType	installs став cpi, eventOptimization став appEventConversion
scheduleStart / scheduleEnd	start / end
enabled	paused	сенс перевернуто
biddingStrategy	bidConfigurationMethod	automated став auto
cpiBids[]	manualBids[]
sourceBids[]	manualSourceBids[]
eventOptimizationBids[]	appEventBids[]

Найдорожча помилка тут — enabled → paused. Булеве значення переноситься механічно, а сенс у нього зворотний: якщо пересадити enabled: true у paused: true, жива кампанія стане на паузу, а вимкнена запуститься.

Маршрути: що злилося

З обраних Unity прикладів:

• GET …/apps став GET …/applications.
• Список кампаній за апкою замінено спільним по організації: GET …/organizations/{orgId}/campaigns?appIds={applicationId}.
• Чотири маршрути ставок (cpi-bids, source-bids, roas-bids, event-optimization-bids) злилися в один PATCH …/campaigns/{campaignId}/bids.
• Бюджет і таргетинг правляться через PATCH …/campaigns/{campaignId}/budget-cap і PATCH …/campaigns/{campaignId}/targeting.
• Призначення й зняття creative packs стало списковим: PATCH …/assign-creative-pack і DELETE …/unassign-creative-pack.
• Читання ставок, бюджету, таргетингу та паків переїхало в GET campaign?includeFields=….

Про новий PATCH …/bids Unity пише, що він замінює весь набір ставок цього типу: треба слати повний масив, а [] очищає набір. Звідси практичний висновок: якщо раніше ви додавали одну ставку за сорсом окремим запитом, то тепер надсилання одного елемента зітре всі інші ставки за сорсами. Спершу прочитайте поточний набір, потім змінюйте й надсилайте цілком.

Що прибрали

У новому API немає:

• Видалення апки. Unity пише, що видалення апок наразі вимкнено на всій платформі.
• Ставок за ретеншном та eligibility: їх оголошено застарілими. Для ROAS eligibility більше не потрібна.
• Частини полів таргетингу: limitedAdTracking, connectionType, screenSize, screenDensity, allowedDevices, osMax.
• Поля апки adomain.
• Типу креатива squareVideo: він не підтримується.

Якщо ваша звʼязка спиралася на щось із цього списку, переписувати треба логіку, а не лише назви полів.

Порядок міграції

Порядок, який пропонує сама сторінка Unity:

1. Конфіг: хост і префікс.
2. Апки та таблиця відповідності id.
3. Атрибуція.
4. Креативи.
5. Creative packs.
6. Довідкові запити для керування кампаніями.
7. Кампанії: спершу створити лише з optimizationType і start, решту дозаповнити через PATCH.
8. Ставки, уже в мікродоларах.
9. Бюджет, теж у мікродоларах.
10. Таргетинг.
11. Призначення паків.
12. Читання.

Логіка зрозуміла: спершу те, на що посилається решта (апки та їхні id), потім самі кампанії, потім усе, що до них кріпиться.

Чого немає в доках

Сторінки, які ми прочитали, мовчать про кілька речей, про які ви спитаєте першими:

• Дати вимкнення. Ні дати вимкнення /advertise/v1, ні строку, поки старий API ще працює, ніде не вказано. Вважати, що час є, не можна. Вважати, що його немає, теж: просто невідомо.
• Ліміти запитів і формат заголовка авторизації. Сторінка про API-керування відсилає до посібника get started, а він значень лімітів і заголовка не дає. Жодних цифр лімітів у цій статті немає, бо їх немає в джерелі.
• Доля id креативів при повторному завантаженні. Unity просить перевірити.

Як це виглядає в DarkCore Ramet

DarkCore Ramet працює з Unity Ads через офіційний Unity API: організацію підключають ключем service account або своїм Unity ID. Пари «апка — гео» перетворюються на кампанії пачкою з превʼю до надсилання, а ставки, денний бюджет і паузи можна редагувати одразу в багатьох кампаній і кабінетів. Кожна зміна читається назад із Unity, перш ніж вважатися виконаною.