In selesnow/rgoogleads: Loading Data from 'Google Ads API'

knitr::opts_chunk$set(
  collapse = TRUE,
  eval = FALSE,
  comment = "#>"
)

Пакет RAdwords работает с Google AdWords API версии 201809. Данный API давно не обновляется и прекратит работу 27 апреля 2022 года.

В этой виньетке мы подробно разберёмся с тем, как перейти с RAdwords на rgoogleads, для того, чтобы с апреля 2022 года ваши скрипты по прежнему корректно собирали необходимые данные из рекламных аккаунтов в Google Ads.

Возможности пакета rgoogleads

авторизация в API Google Ads;
загрузка списка аккаунтов верхнего уровня;
загрузка всей иерархии аккаунтов из управляющих аккаунтов;
загрузка объектов рекламного кабинета: кампании, группы объявлений, объявления и другое;
загрузка статистических данных из рекламных аккаунтов;
загрузка метаданных ресурсов, полей ресурсов, сегментов и метрик;
загрузка прогноза и исторических данных из планировщика ключевых слов.

Преимущества пакета rgoogleads

Сначала давайте разберёмся, какие преимущества дает переход на новый пакет rgoogleads:

rgoogleads работает с Google Ads API v8 (релиз от 09.06.2021), RAdwords работает с Google AdWords API v201809. Google AdWords API прекратит работу 27.04.2022;
для авторизации rgoogleads использует пакет gargle, что даёт гораздо больше гибкости по сравнению с тем, как устроен процесс авторизации в RAdwords;
в rgoogleads есть вшитый токен разработчика Google Ads и OAuth клиент для авторизации. Это избавит большинство пользователей от необходимости запрашивать у поддержки Google базовый доступ к API Google Ads и тратить время на создание проекта и OAuth клиента в Google Cloud Console;
у большинства функций rgoogleads аргумент cl, который позволяет осуществлять загрузку данных в многопоточном режиме;
в отличие от RAdwords, у rgoogleads есть функции для загрузки списков и иерархии аккаунтов;
у rgoogleads есть отдельные функции для загрузки основных объектов рекламных кабинетов, таких как рекламные кампании, группы объявлений, ключевые слова и объявления;
за счёт того, что запрос данных не разделён на отдельные функции, синтаксис rgoogleads более понятный и лаконичный. В RAdwords вам необходимо было изначально создать запрос функцией statement(), после чего использовать его для запроса данных в функции getData();
у rgoogleads нет проблем при загрузке названий, содержащих кириллицу;
если запрос к API столкнулся со сбоем на сервере (статус ответа 429 или выше), пакет rgoogleads автоматически выждет паузу в 100 секунд и повторит попытку запросить данные. За счёт этого работа данного пакета более стабильна и устойчива к сбоям на сервере Google Ads API;
rgoogleads выводит подробное сообщение об ошибке. Для сравнения, если пользователь допустил ошибку в составлении запроса, RAdwords не выводит никакие сообщения;
rgoogleads позволяет запрашивать данные из планировщика ключевых слов.
используя rgoogleads вы можете запрашивать статистику по объектам, которые появились в Google Ads после сентября 2018 года.

Основные различия между Google AdWords API и Google AdsAPI

К счастью, ключевых различий между устаревшим и новым API не так много, и процесс миграции не должен вызвать у вас особых сложностей. Ниже я перечислю ключевые моменты миграции.

нет необходимости менять автоионизационные данные, токен разработчика, id и secret OAuth клиента будут работать также и с новым Google Ads API;
в AdWords API отчёты были выделены в отдельную службу, в Google Ads API отчёты являются частью одного сервиса. Вам достаточно включить в отчёты необходимые поля с метриками, которые нужно получить;
В AdWords API существовали типы отчётов, например, CAMPAINGN_PERFORMANCE_REPORT. В Google Ads API их нет, вместо типов отчётов представлен огромный набор ресурсов;
у AdWords API и Google Ads API разный формат ответа от API;
в Google Ads API отсутствует параметр includeZeroImpressions, вместо него вы можете использовать фильтр metrics.impressions > 0.

Миграция с RAdwords на rgoogleads

migrate_table <- data.frame(
  operation = c("Авторизация", "Запрос метаданных", "Запрос отчётов"),
  radwords = c("doAuth()", "reports(), metrics()", "statement() + getData()"),
  rgoogleads = c("gads_auth_configure() + gads_auth()", "gads_get_metadata(), gads_get_fields()", "gads_get_report()")
  )

DT::datatable(
  migrate_table, 
  colnames = c("Операция", "RAdwords", "rgoogleads"),
  options = list(pageLength = 5, dom = 'tip'))

Бывшие в Google AdWords типы отчётов, в Google Ads стали ресурсами. Ниже — таблица сопоставления из официальной справки:

library(dplyr)
library(rvest)
reports_table <- data.frame(
  adwords = c("ACCOUNT_PERFORMANCE_REPORT", "AD_PERFORMANCE_REPORT", "ADGROUP_PERFORMANCE_REPORT", "AGE_RANGE_PERFORMANCE_REPORT",
              "AUDIENCE_PERFORMANCE_REPORT", "AUTOMATIC_PLACEMENTS_PERFORMANCE_REPORT", "BID_GOAL_PERFORMANCE_REPORT", "BUDGET_PERFORMANCE_REPORT",
              "CALL_METRICS_CALL_DETAILS_REPORT", "CAMPAIGN_AD_SCHEDULE_TARGET_REPORT", "CAMPAIGN_CRITERIA_REPORT", "CAMPAIGN_PERFORMANCE_REPORT",
              "CAMPAIGN_SHARED_SET_REPORT", "CAMPAIGN_LOCATION_TARGET_REPORT", "CLICK_PERFORMANCE_REPORT", "DISPLAY_KEYWORD_PERFORMANCE_REPORT"),
  ads     = c("customer", "ad_group_ad", "ad_group", "age_range_view",
              "campaign_audience_view, ad_group_audience_view", "group_placement_view", "bidding_strategy", "campaign_budget",
              "call_view", "ad_schedule_view", "campaign_criterion", "campaign",
              "campaign_shared_set", "location_view", "click_view", "display_keyword_view"))

# reports <- read_html("https://developers.google.com/google-ads/api/docs/migration/mapping") %>% 
#            html_element(css = ".responsive") %>% 
#            html_table(header = TRUE)

DT::datatable(
  reports_table, 
  colnames = c("Тип отчёта в Google AdWords API", "Ресурс в Google Ads API"),
  options = list(pageLength = 20)
  )

Соответствие полей «Отчёт» и полей ресурсов можно найти в официальной справке. Таблица очень большая, поэтому не вижу смысла дублировать её здесь.

Ниже приведу пример запроса отчёта по эффективности рекламных кампаний с одним и тем же набором полей, с помощью пакета RAdwords и rgoogleads.

Запрос отчёта по эффективности рекламных кампаний с помощью RAdwords

library(RAdwords)

# авторизация
adwords_auth <- doAuth()

# составляем запрос
query <- statement(
  select = c('CampaignName',
            'Date',
            'Clicks'),
  report = 'CAMPAIGN_PERFORMANCE_REPORT',
  start  = '2021-06-01',
  end    = '2021-06-30'
)

# загрузка данных
data1 <- getData(
  clientCustomerId = 'xxx-xxx-xxxx',
  statement        = query, 
  google_auth      = adwords_auth
)

Запрос отчёта по эффективности рекламных кампаний с помощью rgoogleads

library(rgoogleads)

# авторизация
gads_auth_configure(path = 'D:/ga_auth/app.json')
gads_auth(email = 'me@gmail.com')

# загрузка данных
data2 <- gads_get_report(
  resource = 'campaign',
  fields   = c('campaign.name',
              'segments.date',
              'metrics.clicks'),
  date_from         = '2021-06-01',
  date_to           = '2021-06-30',
  customer_id       = 'xxx-xxx-xxxx',
  login_customer_id = 'xxx-xxx-xxxx'
)