Search Console і GA4 у Claude Code: один сервісний акаунт і нюанси API

4 серпня я поставив своєму агенту запитання, яке скидалося на проблему з доступом. Він повідомив про 4 покази в Google для plants.place — сайту, якому було кілька днів. У Google Search Console у браузері я бачив більше. Може, агенту потрібен ще один сервісний акаунт?

Ні. З доступом усе було гаразд, а із запитом — ні. API Google Search Console повертає лише остаточні дані, якщо не попросити свіжі. А в такого молодого сайту остаточних даних майже не було. З іще одним параметром той самий запит повернув 37 показів.

Це був один із кількох випадків, коли відповідь API не збігалася з реальною картиною. У цьому плейбуку — схема, яку я тепер використовую на кожному сайті, і нюанси, на які натрапив дорогою. Правила зберігаються у файлі скілу (skill), який мій агент завантажує щоразу, коли працює з аналітикою. Завантажте його або вставте в інструкції будь-якого агента.

Встановіть скіл у Claude Code

Це готовий скіл. У заголовку написано, що він робить і коли Claude Code має його завантажувати:

---
name: search-console-ga4
description: Give an AI agent Search Console, GA4 and Tag Manager through one Google service account. Setup order, permissions, scripts, and the API gotchas (final vs fresh data, query rows vs totals, sitemap counts, URL Inspection limits). Load before setting up analytics on a site or pulling data from these APIs.
---

• Для всіх проєктів: збережіть його як ~/.claude/skills/search-console-ga4/SKILL.md.
• Для одного проєкту: збережіть його як .claude/skills/search-console-ga4/SKILL.md у папці проєкту.
• Перевірте, чи він завантажується: почніть нову сесію й запитайте Claude, які скіли він має. search-console-ga4 має бути у списку.

У файлі також є два короткі скрипти на Python. Один отримує токен для сервісного акаунта. Інший створює ресурс GA4 і контейнер Tag Manager для сайту. Не потрібні ні Google SDK, ні додатковий сервер: агент напряму звертається до API Google, а кожна зміна відбувається через скрипт, який можна прочитати перед запуском.

Один сервісний акаунт на профіль

До того як це стало скілом, мені доводилося запитувати агента, як організовані мої сервісні акаунти Google. Тепер відповідь записана один раз.

Профіль у моїй системі — це набір пов’язаних облікових записів, наприклад для особистих проєктів або одного клієнта. Для Google це означає один обліковий запис Analytics і один обліковий запис Tag Manager на профіль, а всередині них — ресурс і контейнер для кожного сайту. І один проєкт Google Cloud з одним сервісним акаунтом — на профіль, а не на сайт.

Причина проста. У проєкті Cloud є лише ввімкнені API, сервісний акаунт і квота. Доступ до даних надають окремо в кожному продукті. Тому новий сайт не потребує жодної роботи в Google Cloud: я додаю ту саму адресу сервісного акаунта до його Google Search Console, GA4 і Tag Manager.

Один сервісний акаунт на профіль→ та сама адреса додана до кожного сайту

Search Console

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

GA4

Редактор облікового запису. Створює ресурси й потоки даних. Для читання звітів достатньо ролі читача.

Tag Manager

Адміністратор облікового запису. Створює контейнери. Для зміни й публікації одного контейнера достатньо права на публікацію в ньому.

Як під’єднати Search Console і GA4 до Claude Code

1. Створіть один проєкт Google Cloud для профілю та ввімкніть чотири API: Google Search Console API, Google Analytics Admin API, Google Analytics Data API і Tag Manager API.
2. Створіть сервісний акаунт і ключ JSON. Ключ зберігайте в менеджері паролів, а не в чаті. Мій агент читає його в коді й ніколи не виводить. Є одна пастка: приватний ключ усередині JSON містить переноси рядків, тому менеджер паролів, який зберігає все одним рядком, може обрізати його. Я зберігаю ключ у кодуванні base64.
3. Додайте сервісний акаунт до кожного продукту. Для Google це звичайний користувач із незвичною адресою електронної пошти.
4. Попросіть агента зробити пробний запуск для одного сайту й прочитайте план до того, як щось зміниться.

Як додати користувача в Search Console

Відкрийте Налаштування → Користувачі й дозволи → Додати користувача. Вставте адресу сервісного акаунта й виберіть повний доступ. Цього достатньо, щоб читати дані, перевіряти адреси й надсилати карти сайту. Додавати інших користувачів може лише власник.

У GA4 потрібний розділ — Адміністратор → Керування доступом до облікового запису. У Tag Manager — Адміністратор → Керування користувачами. Надайте ролі з рисунка вище.

Налаштування GA4 і Tag Manager через API

Порядок завжди однаковий:

1. Створити ресурс GA4 і його потік даних для сайту. Взяти ідентифікатор вимірювання з відповіді API — ніколи не вводити його вручну.
2. Створити контейнер Tag Manager.
3. Додати фрагмент контейнера до шаблону сайту. Його ідентифікатор береться з конфігурації сайту, а не прописується в коді.
4. Додати тег Google у контейнер із тригером «Усі сторінки», створити версію й опублікувати її.
5. Перевірити сторінку на сайті.
6. Записати ідентифікатори в нотатки проєкту.

Цей сайт отримав аналітику саме так 3 жовтня. Пробний запуск вивів план і нічого не змінив:

[dry run] would create GA4 property mxkeey.com in accounts/…
[dry run] would create GTM container mxkeey.com

Перший справжній запуск створив ресурс GA4. Наступний запит — до його потоків даних — повернув помилку 503: сервіс недоступний. За хвилину чи дві той самий запит спрацював, тому версія у скілі повторює запити після серверних помилок.

Потім Tag Manager повернув помилку 404: «Не знайдено або немає дозволу». Насправді все було на місці. Сервісний акаунт був в обліковому записі Tag Manager, але не мав ролі адміністратора, а створювати контейнери може лише адміністратор. Я змінив роль, і наступний запуск зробив решту:

GA4 property exists: properties/…
GA4 measurement ID: G-…
GTM container created: GTM-…
Google tag created and published, version 2

Після цього — найважливіша перевірка. На сторінці сайту у вкладці мережевих запитів браузера було три запити: контейнер, завантажений ним тег Google і запит collect з en=page_view та правильним ідентифікатором вимірювання.

Я навчився наполягати на цій перевірці після plants.place. Там мій агент вручну ввів ідентифікатор вимірювання в сім тегів і помилився. Усі теги надсилали б дані в нікуди, хоча зовні все виглядало б справним. Того ж дня агент сказав, що нові події працюють. Вони доходили до dataLayer сторінки, але в контейнері не було тригерів для них, тому до GA4 нічого не надходило. Відтоді я беру ідентифікатори лише з відповідей API, а «готово» означає, що на сторінці сайту є відповідний запит.

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

Нюанси API Search Console

Покази, які API Search Console повернув за ті самі дні

plants.place, перші дні в пошуку. Запит за замовчуванням: 4 покази загалом, 1 у рядках за запитами. З dataState all: 37 загалом, 23 у рядках за запитами.

Запит за замовчуванням, усього по сайту 4

Запит за замовчуванням, рядки за запитами 1

dataState «all», рядки за запитами 23

dataState «all», усього по сайту 37

За замовчуванням — остаточні дані. Якщо не передати dataState, API повертає лише остаточні дані. За інформацією Google, остаточні дані зазвичай з’являються через два-три дні. У панелі видно свіжіші числа, тому дані не збігаються. На сайті, якому було кілька днів, різниця становила 4 покази проти 37. На старішому сайті це лише останні два-три дні — але цього досить, щоб зламати звіт «за останні 7 днів» або перевірку наступного дня після релізу. Свіжі дані можуть трохи змінитися, перш ніж стануть остаточними, і це нормально.

Сума рядків за запитами не збігається із загальною кількістю. За ті самі дні рядки, згруповані за запитом, дали 23 із 37 показів. Google не додає рідкісні анонімізовані запити до даних на рівні запитів. Загальні числа також відрізняються, якщо групувати за сторінкою, а не брати весь сайт. Загальні числа отримуйте із запиту без виміру запиту. Рядки із запитами сприймайте як список того, що шукають люди, а не як складові суми.

Кількість «проіндексованих» у карті сайту. У перші дні запис карти сайту в API показував 61 надіслану адресу й 0 проіндексованих. Водночас перевірка URL для вибірки сторінок показала, що 7 із 8 були в індексі. Пізніше я побачив у довідці API, що це поле позначено як застаріле: не використовуйте його. Натомість користуйтеся перевіркою URL.

Нюанс	Що я побачив	Що робити
Остаточні дані	4 покази замість 37 на новому сайті	Передавати dataState: "all" у кожному запиті
Рядки із запитами	Для 23 із 37 показів був видимий запит	Загальні числа брати на рівні сайту або сторінки, а рядки із запитами використовувати як орієнтир
Кількість у карті сайту	0 проіндексованих, хоча 7 із 8 сторінок у вибірці були в індексі	Перевіряти індексацію через перевірку URL

Обмеження API Search Console, про які варто знати

• API перевірки URL: 2 000 запитів на день і 600 на хвилину для одного ресурсу. Він показує лише версію в індексі Google; перевірити актуальну версію через API не можна. Перевіряйте вибірку, а не весь сайт щодня.
• Аналітика пошуку: до 25 000 рядків на запит; перегортайте сторінки через startRow. У довідці Google написано, що API віддає не більше ніж 50 000 рядків даних на день для кожного типу пошуку.
• В API цього взагалі немає: запиту на індексацію і статистики сканування. API має чотири частини: аналітика пошуку, карти сайту, сайти й перевірка URL. Це все.

Усе це взято з довідки API Google і сторінки з обмеженнями використання, які я перевірив у жовтні 2026 року. Обмеження змінюються, тому скіл просить агента перевірити актуальну сторінку, коли конкретне число важливе.

Нюанси GA4 і Tag Manager

• Абсолютно новий ресурс спочатку може повертати помилку 503. Зачекайте й повторіть запит. Для всіх інших помилок одразу зупиняйтеся з чітким повідомленням.
• Tag Manager пише «не знайдено», коли насправді бракує дозволу. Перевірте роль, перш ніж шукати одрук.
• Подія в dataLayer — ще не подія в GA4. Для неї потрібні тригер, тег і опублікована версія. Перевірте запит collect.
• Ключові події не діють заднім числом. У довідці Google написано, що після позначення події як ключової звіти змінюються лише від цього моменту, а історичні дані — ні. Для історичних даних використовуйте кількість подій із фільтром за назвою події.
• GA4 потрібен час. Звіт у реальному часі показує дані за кілька хвилин, але обробка може тривати 24–48 годин. Учорашні числа сьогодні вранці ще не остаточні.

Що досі має робити людина

• Запит на індексацію. Один клік у Search Console.
• Статистика сканування. Вивантаження звіту в браузері.
• Підтвердження ресурсу домену. DNS-запис, який потрібно додати самостійно, перш ніж можна буде додати сервісний акаунт.
• Жива видача. В одному проєкті агент шукав у Google через браузер і приблизно після 40 пошуків поспіль натрапив на капчу. Для живої видачі я натомість використовую API пошукової видачі.

В обліковому записі клієнта

Та сама схема працює для клієнтів, але з жорсткішими правилами:

• За замовчуванням — лише читання.
• Зміни в Tag Manager або GA4 — лише на мій запит, через скрипт із пробним запуском.
• Після публікації — перевірити події від реальних відвідувачів у звіті в реальному часі й зберегти копію версії контейнера.
• Рекламні облікові записи залишаються під ручним керуванням.