This page is also available in English.
Огляд
Цей реліз додає дві основні групи ендпоінтів:- Google Ads Management CRUD — створення, оновлення та видалення груп оголошень, оголошень (RSA), ключових слів, розкладу показів та таргетингу за локацією
- Редагування активних кампаній — читання та оновлення налаштувань вже опублікованих кампаній Google Ads
Зміни в існуючих ендпоінтах
Параметр 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.
Два рівні пошуку
Адмін-панель реалізує пошук на двох рівнях:- Пошуковий рядок у кожній таблиці — текстове поле над таблицею, яке
фільтрує конкретну таблицю через
?search=<term> - Глобальний пошуковий діалог (
Cmd+K) — відправляє той самий?search=запит до всіх 7 таблиць паралельно, показуючи результати згруповані за категоріями
Рекомендований паттерн реалізації
1. Debounce вводу (300мс)
Не робіть API-виклик на кожне натискання клавіші. В адмінці використовується debounce 300мс:2. Захист від застарілих результатів (race condition)
Якщо користувач набирає “sho”, а потім швидко змінює на “brand”, відповідь на “sho” може прийти після “brand”. Використовуйте search-ID ref для відкидання застарілих відповідей:3. Для глобального пошуку — паралельні запити
В адмінці всі 7 запитів категорій відправляються незалежно (не черезPromise.all), тому результати з’являються поступово:
4. Стани UI для обробки
| Стан | Що показувати |
|---|---|
| Клієнт не вибраний | Вимкнене поле вводу, підказка вибрати акаунт |
| Порожній запит | Плейсхолдер (“Пошук кампаній, оголошень, ключових слів…”) |
| Завантаження | Скелетон-рядки або спінер на кожну категорію |
| Часткові результати | Показати готові категорії, скелетон для очікуваних |
| Немає результатів | ”Немає результатів для ‘запит‘“ |
| Помилка | Повідомлення про помилку для кожної категорії |
5. Навігація з глобального пошуку до таблиці
Коли користувач обирає результат у діалозі, перенаправте на сторінку з таблицею з передзаповненим пошуком:search з URL-параметрів і автоматично зробіть
запит при завантаженні.
Референсна реалізація
Повна робоча реалізація знаходиться вadmin.cattix.com:
| Файл | Призначення |
|---|---|
src/hooks/use-global-search.ts | Хук пошуку з debounce, паралельними запитами, захистом від race condition |
src/components/global-search-dialog.tsx | UI діалогу Cmd+K з cmdk |
src/lib/api/google-ads.ts | API-клієнт, що передає параметр search |
src/app/admin/google-ads-data/page.tsx | Сторінка даних, що зчитує ?search= з URL |
Google Ads Management CRUD
Усі ендпоінти управління знаходяться під префіксом/api/v1/google-ads/ і
потребують параметра customer_id.
Базовий шаблон URL:
Authorization: Bearer <token>.
Групи оголошень
Створити групу оголошень (Swagger)
| Поле | Тип | Обов’язкове | Опис |
|---|---|---|---|
campaign_id | integer | Так | ID кампанії |
name | string | Так | Назва (1-256 символів) |
ad_group_type | string | Ні | SEARCH_STANDARD (за замовч.), DISPLAY_STANDARD, SHOPPING_PRODUCT_ADS |
status | string | Ні | ENABLED (за замовч.) або PAUSED |
cpc_bid_micros | integer | Ні | CPC ставка в мікро (1 000 000 = $1.00) |
AdGroupMutationResult
Оновити статус групи оголошень (Swagger)
{ "status": "ENABLED" | "PAUSED" }
Видалити групу оголошень (Swagger)
Оголошення (RSA)
Створити RSA (Swagger)
| Поле | Тип | Обов’язкове | Опис |
|---|---|---|---|
ad_group_id | integer | Так | ID групи оголошень |
final_url | string | Так | URL посадкової сторінки |
headlines | RSAAssetInput[] | Так | 3-15 заголовків (text + опціональний pinned_field) |
descriptions | RSAAssetInput[] | Так | 2-4 описи |
display_path_1 | string | Ні | Макс. 15 символів |
display_path_2 | string | Ні | Макс. 15 символів |
final_mobile_url | string | Ні | Мобільний URL |
tracking_url_template | string | Ні | Шаблон трекінгу |
Оновити RSA (Swagger)
headlines або descriptions надані, вони замінюють усі існуючі.
Видалити оголошення (Swagger)
Ключові слова
Створити ключові слова (Swagger)
| Поле | Тип | Обов’язкове | Опис |
|---|---|---|---|
ad_group_id | integer | Так | ID групи оголошень |
keywords | KeywordInput[] | Так | Масив: text (обов.) + match_type (EXACT, PHRASE, BROAD, за замовч. PHRASE) |
Оновити ключове слово (Swagger)
| Поле | Тип | Опис |
|---|---|---|
status | string | ENABLED або PAUSED |
cpc_bid_micros | integer | Нова CPC ставка в мікро |
Видалити ключові слова (пакетно) (Swagger)
Розклад показів
Додати записи розкладу (Swagger)
| Поле | Тип | Обов’язкове | Опис |
|---|---|---|---|
campaign_id | integer | Так | ID кампанії |
entries | AdScheduleEntryInput[] | Так | day_of_week, start_hour (0-23), start_minute, end_hour (0-24), end_minute |
Замінити весь розклад (Swagger)
Видалити записи розкладу (Swagger)
{ "campaign_id": ..., "resource_names": [...] }
Таргетинг за локацією
Додати локації (Swagger)
| Поле | Тип | Обов’язкове | Опис |
|---|---|---|---|
campaign_id | integer | Так | ID кампанії |
locations | LocationTargetingEntry[] | Так | geo_target_constant_id + target_type (INCLUDE/EXCLUDE) |
Замінити всі локації (Swagger)
Видалити таргетинг локацій (Swagger)
Редагування активних кампаній
Ці ендпоінти дозволяють читати та оновлювати налаштування вже опублікованих кампаній, під префіксом/api/v1/campaigns/live/.
Отримати налаштування кампанії (Swagger)
Оновити налаштування кампанії (Swagger)
| Поле | Тип | Опис |
|---|---|---|
campaign_name | string | Нова назва (1-256 символів) |
status | string | ENABLED або PAUSED |
daily_budget_micros | integer | Денний бюджет в мікро |
bidding_strategy | object | Стратегія ставок |
network_settings | object | Налаштування мереж |
language_ids | integer[] | Мови (повна заміна) |
location_targets | object[] | Локації (повна заміна) |
ad_schedule | object | Розклад (повна заміна) |
start_date | string | Дата початку (YYYY-MM-DD) |
end_date | string | Дата завершення (YYYY-MM-DD) |
conversion_goals | object[] | Цілі конверсій (повна заміна) |
Видалити кампанію (Swagger)
204 No Content. Це незворотна дія.
Контрольний список міграції
Реалізуйте серверний пошук
Це, ймовірно, найбільше завдання для FE. Додайте пошуковий рядок у кожну
таблицю та, опціонально, глобальний діалог пошуку
Cmd+K. Див.
гайд з реалізації вище для паттернів
(debounce, захист від race condition, поступове завантаження) та
референсний код admin.cattix.com.Обробляйте PAUSED ресурси в таблицях
Таблиці тепер повертають і ENABLED, і PAUSED ресурси. Додайте візуальне
розрізнення для призупинених елементів.
Побудуйте CRUD UI для груп оголошень, оголошень, ключових слів
Використовуйте нові ендпоінти управління для реалізації дій
створення/редагування/видалення в таблицях.
Побудуйте сторінку редагування кампанії
Використовуйте
GET /campaigns/live/{cid}/{campaign_id} для заповнення
форми та PATCH для збереження змін.Додайте фільтр campaign_id до таблиці оголошень
Ендпоінт
/ads тепер підтримує ?campaign_id= для фільтрації.