Skip to main content
This page is also available in English.

Огляд

Цей реліз додає дві основні групи ендпоінтів:
  1. Google Ads Management CRUD — створення, оновлення та видалення груп оголошень, оголошень (RSA), ключових слів, розкладу показів та таргетингу за локацією
  2. Редагування активних кампаній — читання та оновлення налаштувань вже опублікованих кампаній Google Ads
Також є кілька змін в існуючих GET ендпоінтах, на які варто звернути увагу.

Зміни в існуючих ендпоінтах

Параметр login_customer_id більше не потрібний

Параметр login_customer_id більше не використовується жодним ендпоінтом Google Ads. Бекенд тепер автоматично визначає його з бази даних на основі customer_id. Якщо ви зараз передаєте login_customer_id — нічого не зламається, він просто ігнорується. Проте рекомендуємо видалити його з API-викликів для чистоти коду, оскільки він більше не має жодного ефекту.

Новий фільтр campaign_id на /ads

Ендпоінт GET /ads тепер приймає необов’язковий параметр campaign_id для фільтрації оголошень за кампанією. Це на додаток до існуючого фільтра ad_group_id.

Послаблення фільтрів за статусом

Ендпоінти таблиць даних, які раніше повертали лише ENABLED ресурси, тепер також повертають PAUSED ресурси. Це стосується кампаній, груп оголошень, оголошень та ключових слів. Фронтенд має бути готовий відображати обидва статуси.

Серверний пошук (?search=)

Усі GET ендпоінти таблиць даних тепер підтримують параметр search. Див. окремий гайд Пошук по таблицях для повної специфікації API (поля пошуку по кожній таблиці, правила параметрів тощо). Цей розділ фокусується на реалізації пошуку на фронтенді, базуючись на тому, як це вже працює в admin.cattix.com.

Два рівні пошуку

Адмін-панель реалізує пошук на двох рівнях:
  1. Пошуковий рядок у кожній таблиці — текстове поле над таблицею, яке фільтрує конкретну таблицю через ?search=<term>
  2. Глобальний пошуковий діалог (Cmd+K) — відправляє той самий ?search= запит до всіх 7 таблиць паралельно, показуючи результати згруповані за категоріями
Можна реалізувати один або обидва варіанти.

Рекомендований паттерн реалізації

1. Debounce вводу (300мс)

Не робіть API-виклик на кожне натискання клавіші. В адмінці використовується debounce 300мс:

2. Захист від застарілих результатів (race condition)

Якщо користувач набирає “sho”, а потім швидко змінює на “brand”, відповідь на “sho” може прийти після “brand”. Використовуйте search-ID ref для відкидання застарілих відповідей:

3. Для глобального пошуку — паралельні запити

В адмінці всі 7 запитів категорій відправляються незалежно (не через Promise.all), тому результати з’являються поступово:
Це дає приємний ефект поступового завантаження з індикатором прогресу (“Пошук… 3/7 завантажено”).

4. Стани UI для обробки

5. Навігація з глобального пошуку до таблиці

Коли користувач обирає результат у діалозі, перенаправте на сторінку з таблицею з передзаповненим пошуком:
На сторінці даних зчитайте search з URL-параметрів і автоматично зробіть запит при завантаженні.

Референсна реалізація

Повна робоча реалізація знаходиться в admin.cattix.com:
Усі ендпоінти управління знаходяться під префіксом /api/v1/google-ads/ і потребують параметра customer_id. Базовий шаблон URL:
Усі ендпоінти потребують заголовок Authorization: Bearer <token>.

Групи оголошень

Створити групу оголошень (Swagger)

Відповідь: AdGroupMutationResult

Оновити статус групи оголошень (Swagger)

Тіло: { "status": "ENABLED" | "PAUSED" }

Видалити групу оголошень (Swagger)


Оголошення (RSA)

Створити RSA (Swagger)

Оновити RSA (Swagger)

Усі поля необов’язкові. Коли headlines або descriptions надані, вони замінюють усі існуючі.

Видалити оголошення (Swagger)


Ключові слова

Створити ключові слова (Swagger)

Оновити ключове слово (Swagger)

Видалити ключові слова (пакетно) (Swagger)


Розклад показів

Додати записи розкладу (Swagger)

Замінити весь розклад (Swagger)

Те саме тіло. Замінює всі існуючі записи розкладу.

Видалити записи розкладу (Swagger)

Тіло: { "campaign_id": ..., "resource_names": [...] }

Таргетинг за локацією

Додати локації (Swagger)

Замінити всі локації (Swagger)

Видалити таргетинг локацій (Swagger)


Редагування активних кампаній

Ці ендпоінти дозволяють читати та оновлювати налаштування вже опублікованих кампаній, під префіксом /api/v1/campaigns/live/.

Отримати налаштування кампанії (Swagger)

Повертає повні налаштування кампанії для UI редагування:

Оновити налаштування кампанії (Swagger)

Усі поля необов’язкові — оновлюються лише надані поля.
Поля таргетингу (language_ids, location_targets, ad_schedule, conversion_goals) використовують семантику повної заміни. Коли будь-яке з цих полів надано, існуючі значення повністю замінюються. Якщо поле пропущено, воно залишається без змін.
Відповідь:

Видалити кампанію (Swagger)

Повертає 204 No Content. Це незворотна дія.

Контрольний список міграції

1

Реалізуйте серверний пошук

Це, ймовірно, найбільше завдання для FE. Додайте пошуковий рядок у кожну таблицю та, опціонально, глобальний діалог пошуку Cmd+K. Див. гайд з реалізації вище для паттернів (debounce, захист від race condition, поступове завантаження) та референсний код admin.cattix.com.
2

Обробляйте PAUSED ресурси в таблицях

Таблиці тепер повертають і ENABLED, і PAUSED ресурси. Додайте візуальне розрізнення для призупинених елементів.
3

Побудуйте CRUD UI для груп оголошень, оголошень, ключових слів

Використовуйте нові ендпоінти управління для реалізації дій створення/редагування/видалення в таблицях.
4

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

Використовуйте GET /campaigns/live/{cid}/{campaign_id} для заповнення форми та PATCH для збереження змін.
5

Додайте фільтр campaign_id до таблиці оголошень

Ендпоінт /ads тепер підтримує ?campaign_id= для фільтрації.
6

Приберіть login_customer_id з API-викликів (необов'язково)

Він більше не використовується і буде проігнорований, але його видалення зробить код чистішим.