Google Ads API v25: що змінилося для реклами інтернет-магазинів

22 липня 2026 року Google випустив Google Ads API v25 — нову велику версію програмного інтерфейсу для керування рекламою. Реліз додає нові цілі для залучення й утримання клієнтів, метрики взаємодії з рекламою у YouTube Shorts, контроль декларацій AI-контенту та автоматичне створення анімованих матеріалів для Demand Gen. Водночас у v25 є несумісні зміни, через які старий код може перестати працювати після звичайного оновлення бібліотеки.

Головне за одну хвилину

• Google Ads API v25 потрібен не кожному магазину, а передусім системам із власною рекламною автоматизацією, CRM, офлайн-конверсіями або дашбордами.

• Google видалив старі ресурси для цілей життєвого циклу клієнтів і перевів інтеграції на нову об’єднану схему.

• З’явилася окрема Loyalty Retention Goal для роботи з учасниками програм лояльності.

• Для реклами у YouTube Shorts можна отримувати кількість коментарів, уподобань і поширень.

• Нові Demand Gen multi-asset оголошення через v25 за замовчуванням можуть використовувати автоматичне створення анімованих зображень.

• Поля декларацій синтетичного й AI-контенту стали доступними для змін у v25, v24 та v23.

• Офіційна PHP-бібліотека для v25 потребує сучасної версії пакета та PHP 8.1 або новішої.

• Старий OpenCart на PHP 5.6 або 7.4 краще з’єднувати з Google Ads через окремий інтеграційний сервіс.

Що саме випустив Google

Google Ads API — це програмний інтерфейс для систем, які керують рекламними акаунтами безпосередньо з коду. Через нього можна створювати кампанії, змінювати бюджети, завантажувати аудиторії, передавати конверсії, отримувати звіти та керувати великою кількістю рекламних акаунтів.

Версія v25 є major release. Це означає, що вона містить не лише додаткові поля та нові можливості, але й несумісні зміни: видалені ресурси, нові структури даних, змінені типи полів і нові правила валідації.

Важливе уточнення

Поява v25 не означає, що кожному власнику магазину потрібно терміново щось оновлювати. Спочатку необхідно з’ясувати, чи використовує сайт Google Ads API взагалі.

Кого стосується Google Ads API v25

Оновлення стосується магазину, якщо його модуль, CRM, серверний скрипт або окрема панель програмно звертається до Google Ads.

Типові сценарії використання API:

• автоматичне створення кампаній для нових категорій і товарів;

• зупинення реклами товарів, яких немає в наявності;

• зміна бюджетів залежно від обороту, маржі, ROAS або залишків;

• передача замовлень із CRM як офлайн-конверсій;

• передача скоригованої цінності після повернення або скасування замовлення;

• завантаження аудиторій Customer Match;

• поділ покупців на нових, постійних, B2B та роздрібних;

• побудова власного рекламного дашборду;

• керування кількома акаунтами з однієї адміністративної панелі;

• автоматичне виявлення кампаній із перевитратою або падінням ефективності.

Що не є Google Ads API

Оновлення API не слід плутати з іншими продуктами Google.

Якщо магазин використовує лише рекламний кабінет, GA4, Merchant Center і стандартний тег покупки, термінової міграції через появу v25 немає.

Нові та постійні клієнти переходять на нову схему цілей

Одна з головних змін v25 стосується життєвого циклу клієнта. Google видалив старі ресурси CustomerLifecycleGoal і CampaignLifecycleGoal та запропонував нову об’єднану схему через ресурси Goal і CampaignGoalConfig.

Для старої інтеграції це критично. Якщо код читає, створює або змінює видалені ресурси, проста заміна номера версії API не допоможе. Потрібно переписати логіку формування запитів і мапінг відповідей.

New Customer Acquisition Goal

Оновлена ціль залучення нових клієнтів дозволяє задавати окрему логіку для першої покупки та враховувати додаткову цінність нового покупця.

Практичний приклад: магазин готовий витратити більше на перше замовлення, тому що знає середню кількість повторних покупок протягом року. У такому випадку перше замовлення може мати для рекламної системи більшу цінність, ніж його фактична сума.

Однак це працює лише тоді, коли магазин правильно визначає нового покупця. Проблеми виникають, якщо:

• одна людина оформлює замовлення з різними email;

• гостьові замовлення не об’єднуються з обліковим записом;

• телефон зберігається в різних форматах;

• повернені або тестові замовлення враховуються як покупки;

• B2B-клієнти змішуються з роздрібними;

• CRM і магазин мають різні ідентифікатори клієнта.

Loyalty Retention Goal

У v25 з’явилася окрема Loyalty Retention Goal. Вона призначена для кампаній, які працюють з учасниками програми лояльності та повторними покупцями.

Через нові налаштування можна:

• задавати коригування ставок для учасників програми;

• працювати з утриманням постійних клієнтів як з окремою метою;

• показувати переваги програми лояльності в товарних оголошеннях;

• розділяти залучення нових покупців і повторні продажі;

• будувати звітність за типом клієнта.

Ціль не створює програму лояльності автоматично. Магазин повинен мати власні правила, ідентифікатори учасників, історію замовлень і коректну передачу даних.

YouTube Shorts отримав окремі соціальні метрики

Google Ads API v25 додає три відеоспецифічні показники для реклами у YouTube Shorts:

• Metrics.youtube_comments — коментарі;

• Metrics.youtube_likes — уподобання;

• Metrics.youtube_shares — поширення.

Метрики доступні для кампаній, груп оголошень, оголошень, рекламних ресурсів, клієнтів і відео. Це дозволяє побудувати звіт, у якому видно не лише покази та кліки, але й реальну реакцію аудиторії на конкретний ролик.

Як правильно оцінювати Shorts

Коментар або вподобання не дорівнює покупці. Для чесної аналітики показники потрібно розділити на три рівні:

1. Увага: покази, перегляди, частота, тривалість перегляду.

2. Взаємодія: уподобання, коментарі, поширення.

3. Бізнес-результат: переходи, додавання в кошик, покупки, дохід і маржа.

Відео може зібрати багато реакцій через гумор або провокаційну подачу, але не продати жодного товару. Тому дашборд не повинен змішувати engagement і ROAS в один умовний показник ефективності.

Декларації AI-контенту та автоматична анімація

Дані про синтетичний контент можна передавати програмно

Поля Asset.synthetic_content_info та Ad.synthetic_content_info містять інформацію про синтетичний або створений за допомогою AI контент.

У release notes v25 Google уточнив, що відповідні поля стали повністю доступними для змін у версіях v25, v24 і v23. Це важлива деталь: оновлення логіки декларацій не обов’язково потребує повної міграції саме на v25, якщо інтеграція вже працює на підтримуваній v23 або v24.

Для власної рекламної системи варто зберігати походження креативу ще до його завантаження в Google Ads.

Рекомендовані поля в базі:

• тип походження: фото, дизайн, AI або змішаний матеріал;

• сервіс або модель, що створила контент;

• дата генерації;

• автор або відповідальний менеджер;

• статус ручного погодження;

• версія вихідного файлу;

• статус декларації, переданої в рекламну систему.

Не варто визначати AI-контент лише за назвою файлу на кшталт generated-banner-final-2.jpg. Назву можна змінити, а інформація про походження буде втрачена.

Demand Gen може створювати анімовані зображення

У v25 з’явився новий тип автоматизації GENERATE_ANIMATED_IMAGES_FROM_OTHER_ASSETS. Він дозволяє Google створювати анімовані матеріали зі звичайних статичних зображень для Demand Gen multi-asset ads.

Для нових оголошень цього типу, створених через v25, автоматизація увімкнена за замовчуванням.

Це може прискорити виробництво креативів, але створює ризики:

• логотип рухається або масштабується неприродно;

• частина товару обрізається;

• дрібний текст стає нечитабельним;

• композиція не відповідає брендбуку;

• анімація виглядає дешевше за статичний дизайн;

• система створює варіації, які ніхто не погоджував.

Після міграції потрібно окремо перевірити налаштування автоматизації, список вихідних ресурсів і попередній перегляд оголошень у мобільних та десктопних форматах.

Які breaking changes можуть зламати інтеграцію

v25 містить структурні зміни, видалення та нові правила обов’язкових полів. Найбільший ризик виникає в інтеграціях, які давно не оновлювалися і не мають автоматичних тестів.

Найгірша стратегія — змінити v24 на v25 у конфігурації та одразу викотити зміни на production.

Окрема проблема: офіційна бібліотека потребує PHP 8.1+

За офіційною таблицею сумісності, для Google Ads API v25 потрібна PHP client library версії 34.0.0 або новішої. Актуальна бібліотека вимагає PHP 8.1 або новішої версії.

Це створює проблему для старих магазинів, наприклад OpenCart 2.3, які продовжують працювати на PHP 5.6 або 7.4.

Встановлення сучасної бібліотеки безпосередньо в такий магазин може призвести до:

• помилки Composer через несумісну версію PHP;

• конфлікту версій google/protobuf, grpc або google/auth;

• збільшення розміру vendor;

• несумісності з іншими старими пакетами;

• фатальних помилок під час завантаження класів;

• неможливості безпечно оновлювати інтеграцію надалі.

Рекомендована архітектура

OpenCart / PrestaShop │ │ замовлення, товари, статуси, маржа ▼ Integration Gateway на PHP 8.2+ │ ├── черга операцій ├── журнал запитів ├── повторні спроби ├── захист від дублів └── OAuth2 та Google Ads client library │ ▼ Google Ads API

Магазин не повинен знати внутрішню структуру актуального Google Ads API. Він передає стабільний набір власних даних окремому сервісу, а сервіс відповідає за перетворення цих даних у потрібну версію API.

Така схема дозволяє:

• не оновлювати ядро старого магазину заради однієї інтеграції;

• використовувати сучасний PHP, Composer і бібліотеки;

• оновлювати Google Ads API незалежно від OpenCart;

• повторювати невдалі запити без участі покупця;

• не сповільнювати оформлення замовлення;

• централізовано обслуговувати кілька магазинів;

• зберігати детальний журнал передачі конверсій.

Коли перестануть працювати старі версії

Поява v25 не вимикає попередні версії в той самий день. Google публікує окремий графік sunset — дату, після якої запити до конкретної версії перестають працювати.

Дати можуть уточнюватися Google. Особливо небезпечно відкладати міграцію до останнього тижня: після sunset запити почнуть повертати помилки, а передача конверсій, оновлення аудиторій або формування звітів може зупинитися.

Як знайти поточну версію

Версію потрібно шукати не лише в налаштуваннях модуля. Вона може бути прописана:

• у Composer-залежностях;

• у назві namespace;

• у REST endpoint;

• у конфігураційному файлі;

• у Docker-образі інтеграційного сервісу;

• у старому cron-скрипті;

• у зовнішній CRM або агентській панелі.

Google також дозволяє подивитися нещодавні API-виклики у Google Cloud Console. Назва методу містить версію, сервіс і операцію, наприклад google.ads.googleads.v25.services.GoogleAdsService.Mutate.

Детальний план безпечного оновлення на v25

Етап 1. Інвентаризація

1. Знайти всі модулі, CRM, cron-скрипти та сервіси, що працюють із Google Ads.

2. Визначити версію API для кожного компонента.

3. Зафіксувати версію клієнтської бібліотеки.

4. Перевірити версію PHP, Composer, gRPC і Protobuf.

5. Скласти список акаунтів і кампаній, якими керує інтеграція.

Етап 2. Карта функціоналу

Для кожного виклику потрібно зафіксувати його призначення:

• читання статистики;

• створення або редагування кампаній;

• зміна бюджетів;

• завантаження конверсій;

• коригування конверсій;

• Customer Match;

• робота з креативами;

• отримання рекомендацій;

• керування цілями клієнтів;

• побудова прогнозів.

Етап 3. Базові контрольні дані

До оновлення необхідно зберегти контрольний набір результатів:

• витрати за останні 7 і 30 днів;

• кількість кліків і показів;

• конверсії та їхню цінність;

• кількість активних кампаній;

• кількість завантажених аудиторій;

• останні успішні й невдалі API-операції;

• приклади відповідей для ключових GAQL-запитів.

Після переходу ці дані використовуються для порівняння. Без baseline можна не помітити, що нова версія повертає іншу кількість рядків або не враховує частину конверсій.

Етап 4. Оновлення коду

1. Оновити клієнтську бібліотеку в окремій гілці або контейнері.

2. Замінити видалені lifecycle goal ресурси.

3. Перевірити всі GAQL-запити.

4. Оновити DTO, типи даних і серіалізацію.

5. Перевірити required-поля.

6. Оновити обробку нових кодів помилок.

7. Перевірити налаштування AI-контенту та Demand Gen automation.

Етап 5. Тестування

Окремо потрібно протестувати:

• авторизацію OAuth2;

• оновлення access token;

• читання звітів;

• створення й редагування кампанії;

• завантаження тестової конверсії;

• повторну передачу тієї самої операції;

• часткову помилку в пакетному запиті;

• rate limit і повторну спробу;

• недоступність Google API;

• помилковий customer ID;

• недостатні права користувача;

• відновлення черги після перезапуску сервісу.

Етап 6. Поступовий запуск

Найбезпечніший варіант — спочатку увімкнути нову версію для одного тестового або менш критичного акаунта. Після перевірки звітів і мутацій можна поступово перемикати інші акаунти.

Для критичних звітів корисно тимчасово виконувати старий і новий запит паралельно та порівнювати:

• кількість рядків;

• витрати;

• конверсії;

• дохід;

• сегментацію;

• типи значень;

• час виконання.

Що варто додати в інтеграцію під час міграції

Оновлення API — хороший момент не лише переписати старі класи, але й усунути архітектурні проблеми.

Черга операцій

Передача конверсії не повинна відбуватися безпосередньо під час оформлення замовлення. Магазин має записати задачу в чергу й одразу завершити checkout. Окремий worker передасть дані в Google.

Захист від дублів

Кожна операція повинна мати стабільний зовнішній ідентифікатор. Повторний запуск cron або worker не повинен створювати ще одну конверсію для того самого замовлення.

Журнал змін

Для кожної передачі потрібно зберігати:

• номер замовлення;

• тип події;

• дату й час;

• суму та валюту;

• версію API;

• customer ID;

• статус операції;

• код помилки;

• кількість повторних спроб;

• ідентифікатор відповіді Google.

Коригування після повернення

Якщо замовлення скасовано або частково повернуто, рекламна система не повинна продовжувати вважати його повноцінним доходом. Інтеграція має отримувати фінальний статус замовлення та передавати відповідне коригування.

Маржа замість обороту

Два товари з однаковою ціною можуть мати різну прибутковість. Для власної аналітики доцільно зберігати не лише дохід, але й:

• закупівельну ціну;

• знижку;

• вартість доставки;

• комісію платіжної системи;

• комісію маркетплейсу;

• валовий прибуток;

• фактичну маржу після повернень.

Тоді рекламний дашборд може показувати не лише ROAS, а й реальний прибуток кампанії.

Що робити власнику інтернет-магазину зараз

Сценарій 1. Ви використовуєте лише рекламний кабінет

Термінових дій немає. Поява v25 не вимагає оновлення сайту, Google Analytics або стандартного Google tag.

Сценарій 2. У вас є модуль передачі конверсій

Потрібно перевірити документацію модуля й код. Деякі модулі передають дані через браузерний тег, а інші звертаються безпосередньо до Google Ads API.

Сценарій 3. CRM передає офлайн-конверсії

Необхідно визначити поточну версію API, дату її sunset і бібліотеку, яку використовує CRM. Особливу увагу потрібно приділити інтеграціям на v21 і v22.

Сценарій 4. Магазин працює на PHP 5.6 або 7.4

Не слід встановлювати актуальну PHP-бібліотеку безпосередньо в старий проєкт. Краще винести Google Ads у невеликий окремий сервіс на PHP 8.2 або новішій підтримуваній версії.

Сценарій 5. Ви використовуєте нових і постійних клієнтів у ставках

Потрібно перевірити міграцію зі старих lifecycle goal ресурсів на нову схему. Також необхідно перевірити якість ідентифікації клієнтів, гостьові замовлення, дублікати та повернення.

Сценарій 6. Ви запускаєте Demand Gen

Потрібно перевірити, чи дозволене автоматичне створення анімованих зображень, які матеріали використовуються як джерело та хто погоджує створені Google варіації.

П’ятихвилинна перевірка

1. Пошукайте в коді GoogleAdsClient, google.ads.googleads і googleads/google-ads-php.

2. Перевірте composer.json і composer.lock.

3. Знайдіть номер версії: v21, v22, v23, v24 або v25.

4. Подивіться останні виклики у Google Cloud Console.

5. Перевірте, чи є невдалі конверсії або cron-помилки.

6. Порівняйте версію зі строком sunset.

7. Не оновлюйте production без контрольного звіту й резервної копії.

Поширені запитання

Чи потрібно оновлювати звичайний модуль Google Analytics?

Не обов’язково. Google Analytics, Google tag і Google Ads API виконують різні завдання. Спочатку потрібно перевірити, чи модуль справді надсилає серверні запити до Ads API.

Чи перестали v23 і v24 працювати після виходу v25?

Ні. Вони залишаються доступними до відповідних sunset-дат. За поточним графіком v23 працюватиме до лютого 2027 року, а v24 — до травня 2027 року.

Кому потрібно оновлюватися терміново?

Насамперед інтеграціям на v21, sunset якої запланований на серпень 2026 року. Користувачам v22 також потрібно планувати міграцію, оскільки її вимкнення попередньо заплановане на жовтень 2026 року.

Чи можна встановити нову PHP-бібліотеку в OpenCart 2.3?

Лише якщо середовище й усі залежності відповідають вимогам бібліотеки. Для магазину на PHP 5.6 або 7.4 актуальну бібліотеку встановити штатно не вийде, оскільки вона потребує PHP 8.1+. Безпечніше використовувати окремий інтеграційний сервіс.

Чи можна звертатися до API без офіційної PHP-бібліотеки?

Технічно можна створити власний REST-клієнт, але тоді розробник сам відповідає за OAuth2, структури запитів, типи даних, повторні спроби, обробку помилок і оновлення версій. Для більшості проєктів окремий сервіс з офіційною бібліотекою буде надійнішим.

Чи створюватиме Google анімацію для всіх оголошень?

Ні. Описана зміна стосується нових Demand Gen multi-asset ads, створених через v25, для яких відповідний тип автоматизації увімкнений за замовчуванням.

Чи потрібно обов’язково мігрувати з v24 на v25 зараз?

Ні, якщо інтеграція стабільна і нові функції не потрібні. Але варто заздалегідь перевірити breaking changes, підготувати тести та не відкладати роботу до завершення строку підтримки v24.

Чи покращить Loyalty Retention Goal повторні продажі автоматично?

Ні. Результат залежить від якості списків клієнтів, історії замовлень, правильного визначення учасників програми й коректної передачі конверсій.

Чи потрібно зберігати інформацію про AI-креатив у власній базі?

Це рекомендовано для системної автоматизації. Так магазин зможе відстежити походження файлу, ручне погодження, версію матеріалу та декларацію, передану рекламній платформі.

Як зрозуміти, що міграція пройшла правильно?

Потрібно порівняти звіти до й після оновлення, перевірити передачу тестових конверсій, журнали помилок, кількість рядків у звітах, витрати, дохід і всі автоматичні операції з кампаніями.

Технічний аудит

Не знаєте, яка версія Google Ads API працює у вашому магазині?

SiteZilla може перевірити модулі, CRM, cron-скрипти та зовнішні сервіси, знайти застарілі API-виклики, оцінити ризики sunset і скласти план міграції.

Для старих OpenCart і PrestaShop ми можемо винести рекламну інтеграцію в окремий сучасний сервіс, налаштувати чергу передачі конверсій, захист від дублів, журнал помилок і звітність за маржею, новими та постійними клієнтами.

Замовити аудит рекламної інтеграції

Офіційні джерела

• Google Ads Developer Blog — Announcing v25 of the Google Ads API

• Google Ads API — Release notes

• Google Ads API — Upgrade your API version

• Google Ads API — Deprecation and sunset

• Google Ads API — Client libraries and supported versions

• Google Ads PHP Client — composer.json