У квітні 2022 року Google унеможливив використання старої версії API — «Google AdWords». Йому на заміну прийшов «Google Ads API».
Розробники стверджують, що Ads API є більш функціональним та корисним інструментом порівняно з AdWords API. До нових можливостей входять:
- рекомендації щодо роботи з інструментом;
- нові типи публікацій;
- можливість керування активами.
Крім того, були оновлені функції виставлення рахунків, історії змін та планувальника ключових слів. Перехід на Ads API допоможе зробити управління рекламними кампаніями більш ефективним та простим.
Проте, ця міграція не пройшла непоміченою для Google Ads Scripts, більшість з яких просто перестали працювати, видаючи помилки. Попри те, що зараз є можливість використовувати й стару версію скриптів, і нову, ми все ж ми рекомендуємо рекламодавцям переводити старі скрипти на нову версію.
Запитаєте, навіщо це робити, якщо можна працювати на старій версії? По-перше, у старій версії не з'являтимуться нові фічі. По-друге, можна переходити, не поспішаючи, паралельно, вивчаючи нові особливості.
Як це зробити? З цим питаннями ми розбиралися разом з Борисом Дзюндзюком, Senior фахівцем з контекстної реклами.
Що це Google Ads API та яку функцію виконують скрипти?
Google Ads API — це програмний інтерфейс, який дозволяє рекламодавцям і розробникам створювати власні програми, що взаємодіють з обліковими записами Google Ads і вносити в них зміни.
Новий інтерфейс Google Ads API більш гнучкий та заснований на інтуїтивно зрозумілій мові запитів. Він допомагає рекламодавцям ще більше розширювати та масштабувати свої можливості звітування.
А скрипти в Google Ads API використовуються для автоматизації повсякденних завдань, збільшення ефективності та зменшення часу, витраченого на ручне управління рекламними кампаніями. В нашому випадку ці скрипти послугують нам для налаштування функцій пошуку та нового синтаксису звітів GAQL (Google Ads Query Language).
Як працює новий API?
Оригінальний AdWords API використовує власну мову запитів, яка називається AdWords Query Language (AWQL), для надсилання запитів до API. Однак новий API використовує сучасний програмний інтерфейс на основі мови запитів Google Ads (GAQL).
Ця мова використовується для надсилання запитів через API Google Ads до ресурсів і пов'язаних з ними атрибутів, сегментів і метрик за допомогою сервісу Google Ads. На практиці це означає, що автоматизовані сценарії потрібно переписати для використання нової мови запитів, щоб вони могли працювати з новим API.
Як активувати нову версію в інтерфейсі скриптів?
Дуже просто, ввімкнути нову версію і перевірити, чи коректно працюватиме ваш скрипт, можна натиснувши на перемикач «New scripts experience» у вікні з текстом скрипта.
Після активації опції, натисніть Preview і виправте помилки, що виникли. Помилок може й не бути, це залежить від того, що саме написано у вашому скрипті.
Які відмінності нової версії від старої
Розгляньмо основні відмінності нової версії від старої:
- Підтримка JavaScript ES6
- Використання мови запитів GAQL замість AWQL для побудови звітів, про що ми писали вище
Приклади можливостей, які дає ES6:
Використання ключових слів let, const поряд із var для оголошення змінних
var campaignName = "Search Campaign";
let campaignName2 = "Search Campaign 2";
const campaignName3 = "Search Campaign 3";
Стрілкові функції
// ES5
var x = function(x, y) {
return x * y;
}
// ES6
const x = (x, y) => x * y;
Використання циклу for/of для перебору ітерованих об'єктів, типу масивів, рядків тощо.
const campaigns = ["Campaign #1", "Campaign #2", "Campaign #3"];
for (let campaign of campaigns) {
Logger.log(campaign);
}
Шаблонні рядки, які швидше і зручніше використовувати при склейці рядків і значень змінних. Наприклад, не потрібно думати про те, чи не пропустили ви пробіл.
const campaignType = "[Search]";
const campaignName = "Super Campaign";
Logger.log(`New campaign name is ${campaignType} ${campaignName}`);
Об'єкт Set, який становить собою колекцію унікальних значень і дає змогу спростити код, опустивши перевірку на те, чи міститься в об'єкті конкретне значення чи ні.
const campaigns = new Set();
campaigns.add("Campaign #1");
campaigns.add("Campaign #2");
campaigns.add("Campaign #2");
for (let campaign of campaigns.keys()) Logger.log(campaign);
Ми двічі спробували додати в campaigns рядок «Campaign #2», але оскільки в об'єкті типу Set містяться тільки унікальні значення, то «Campaign #2» буде додано один раз і в лозі ми побачимо:
Campaign #1
Campaign #2
Є також ще безліч інших нововведень в ES6, з якими ви можете ознайомитися самостійно, наприклад, тут
Новий синтаксис звітів — GAQL (Google Ads Query Language)
Перейдемо до нового синтаксису звітів — GAQL (Google Ads Query Language).
Його потрібно використовувати не тільки у функціях .report() та .search(), але і в .withCondition().
Якщо раніше ми могли отримати кампанію за допомогою такого запису:
var campaigns = AdsApp.campaigns().withCondition("Name = 'SuperCampaign'").get();
То тепер це виглядає так:
var campaigns = AdsApp.campaigns().withCondition("campaign.name = 'SuperCampaign'").get();
Ще один приклад.
Було:
var labelName = "Low Performance";
var campaigns = AdsApp.campaigns().withCondition("Clicks > 100").withCondition("LabelNames CONTAINS_ANY ['"+labelName+"']").forDateRange("LAST_7_DAYS").get();
Стало:
var labelName = "Low Performance";
var label = AdsApp.search("SELECT label.resource_name FROM label WHERE label.name = '"+labelName+"'").next().label.resourceName;
var campaigns = AdsApp.campaigns().withCondition("metrics.clicks > 100").withCondition("campaign.labels CONTAINS ANY ('"+label+"')").forDateRange("LAST_7_DAYS").get();
Зверніть увагу, як тепер потрібно працювати з ярликами.
Якщо раніше ми могли відфільтрувати кампанії (або будь-які інші entities) за ім'ям ярлика, то тепер замість імені ярлика у фільтрі ми маємо використовувати запис виду "customers/1234567890/labels/532785809", де 1234567890 — це id вашого акаунту, а 532785809 — id конкретного ярлика.
У прикладі вище за допомогою функції генерації звітів .search() ми присвоюємо змінній label інформацію про ярлик якраз у потрібному нам вигляді "customers/1234567890/labels/532785809".
На щастя, ця зміна не стосується принципу роботи з самими ярликами, який залишився тим самим. Їх однаково можна вибирати за ім'ям, наприклад,
var label = AdsApp.labels().withCondition('label.name = "Top performance"').get().next();
Чому варто використовувати .search() замість .report()
Якщо ви все ще не почали використовувати .search() замість .report(), рекомендуємо переходити на .search() вже зараз. Чому?
У новій версії скриптів .report() немає нативної підтримки і під час виклику цієї функції відбувається конвертація в зрозумілий для Google Ads API формат. Це означає, що можуть виникати помилки і бути відсутнім доступ до деяких журналів звітів. І навіть при використанні .report() все одно доведеться переписувати старі AWQL запити на нові GAQL.
Найпростіший варіант побудови запиту — звернутися до довідки Google Ads API, у розділ Report, відкрити потрібний звіт (наприклад, звіт за ключовими словами Keyword View) і натиснути кнопку «Help me build a query»
Потім у рядку пошуку просто шукайте назви полів із даними, які хочете бачити у звіті.
Наприклад, щоб знайти, як писатиметься назва кампанії, введіть «name» і в розділі campaign натисніть галочку на «campaign.name»
У результаті буде додано поле з ім'ям кампанії і запит набуде такого вигляду:
Розгляньмо складніший запит і передамо його у функцію .search().
Ми хочемо отримати інформацію про ключові слова, у яких було 0 конверсій за останні 7 днів — текст ключового слова, назву кампанії, назву групи оголошень.
var report = AdsApp.search("SELECT campaign.name, ad_group.name, ad_group_criterion.keyword.text FROM keyword_view WHERE metrics.conversions = 0 AND segments.date DURING LAST_7_DAYS");
while (report.hasNext()){
var row = report.next();
var campaignName = row.campaign.name;
var adgroupName = row.adGroup.name;
var keywordText = row.adGroupCriterion.keyword;
}
Зверніть увагу на наступне:
1. Як записується умова за періодом. Якщо в старій версії скриптів в AWQL запиті ми вказували період наприкінці запиту в такому вигляді "DURING LAST_7_DAYS", то тепер робимо це так "segments.date DURING LAST_7_DAYS". До того ж segments.date це просто ще одна умова, як metrics.conversions > 0 або campaign.name = "Some campaign".
2. Відсутній виклик .rows(). При використанні .report() необхідно викликати функцію .rows() для того, щоб можна було перебрати звіт. Для .search() це робити не потрібно.
3. Для того, щоб отримати доступ до даних із рядка звіту, достатньо звернутися до змінної рядка і у форматі lowerCamelCase написати те, що ви писали в запиті. Наприклад, у запиті було ad_group.name, а ми пишемо row.adGroup.name
Висновки
Попри те, що десь здійснені косметичні зміни, десь дійсно корисні, нова версія скриптів не позбавлена багів. Наприклад, функція .removeLabel() забагована, і вона просто не запускається.
Тому, якщо в старому скрипті вона використовується і ви хочете перевести її на нову версію, потрібно або використовувати bulk upload для управління ярликами, або виносити весь код, пов'язаний з видаленням ярликів, в окремий скрипт і запускати його в старій версії.
Також у Google Ads Scripts все ще немає підтримки Discovery кампаній.
Але, в будь-якому разі, нова версія нікуди не дінеться і в доступному для огляду майбутньому Google відключить підтримку старої версії, тому ми бажаємо вам удачі в опануванні нових можливостей Google Ads Scripts.
Пам'ятайте, що чим більше ви практикуватиметеся, тим простішим стане процес написання скриптів.
на розсилку
