Загрузка расходов из Яндекс Директ в Google Analytics и другие изменения

ryandexdirect 3.6.0

дата: 2020-06-09

• В пакет добавлена функция yadirGetCostData(), которая запрашивает данные о расходах, кликах и показах по рекламным кампаниям, ключевым словам и объвлениям для дальнейшей загрузки в Google Analytics.
• Техническое обновление, исправлена опечатка в функции yadirGetForecast(), изза которой не корректно работал фильтр по регионам.
• Исправлена ошибка C stack usage 1592693 is too close to the limit.
• Исправлен обработчик ошибок в функции yadirGetReport(), который запускается аргументом SkipErrors = FALSE.
• В функции yadirGetReport() измененно дефолтное значение аргумента DateRangeType с 'LAST_30_DAYS' на 'CUSTOM_DATE'.
• Добавлена виньетка vignette("yandex-direct-cost-data", package = "ryandexdirect"), посвящённая функции yadirGetCostData()
• Актуализирована виньетка по авторизации.

Критические исправление к версии 3.4.0

Исправлена ошибка C stack usage 1592693 is too close to the limit с которой могли столкнуться пользователи пакета начиная с версии 3.4.0.

Запрос отчётов из WordStat, построение прогнозов, поддержка опций и переменных среды.

В версии 3.5.0 были добавлены новые функции и возможности:

• Добавлена функция yadirGetForecast(), с помощью которой вы можете получить прогноза показов, кликов и затрат.
• Добавлена виньетка yandex-direct-keyword-bids, в которой подробно описан процесс запроса отчётов из сервиса WordStat и построении прогнозов с помощью функции yadirGetForecast().
• Для удобства авторизации в ryandexdirect были добавлены опции, и поддержка переменных среды.
  • Опции:
    • ryandexdirect.user - логин по умолчанию
    • ryandexdirect.token_path - путь к папке с учётными данными по умолчанию
    • ryandexdirect.agency_account - агентсткий аккаунт по умолчанию
  • Переменные среды:
    • RYD_USER - логин по умолчанию
    • RYD_TOKEN_PATH - путь к папке с учётными данными по умолчанию
    • RYD_AGENCY - агентсткий аккаунт по умолчанию
• Добавлена функция yadirGetLogins(), с помощью которой вы можете получить список всех логинов, учётные данные по которым сохраненны в TokenPath, так же можно с помощью этой же функции переключиться из одного логина на другой.
• Добавлена функция yadirSetLogin(), которая позволяет в коде легко переключаться между логинами под которыми вы прошли авторизацию, если вы укажите логин под которым авторизация ещё не пройдена, то процесс авторизации будет запущен автоматически.
• Добавлена функция yadirSetAgencyAccount(), которая позволяет в коде легко переключаться между агентскими аккаунтами под которыми вы прошли авторизацию, если вы укажите логин аккаунта под которым авторизация ещё не пройдена, то процесс авторизации будет запущен автоматически.

ryandexdirect 3.2.2

ryandexdirect 3.2.2

дата: 2019-10-31

Что нового?

• Функция yadirGetCampaignList() с версии 3.2.2 считается устаревшей. Она будет присутвовать в пакете, но не будет развиваться. Вместо неё рекомендуется использовать функцию yadirGetCampaign().
• В таблицу возвращаемую функцией yadirGetCampaign() добавлены новые поля:
  • SourceId - Идентификатор исходной кампании в у. е., если текущая кампания была создана автоматически при переходе рекламодателя на работу в валюту.
  • FundsMode - Тип финансовых показателей кампании:
    • CAMPAIGN_FUNDS — общий счет не подключен, финансовые показатели кампании возвращаются в поле CampaignFundsBalance;
    • SHARED_ACCOUNT_FUNDS — общий счет подключен, финансовые показатели кампании возвращаются в поле SharedAccountFundsSpend.
  • CampaignFundsBalance - Текущий баланс кампании в валюте рекламодателя, без учета НДС.
  • CampaignFundsBalanceBonus - Скидочный бонус. Параметр утратил актуальность.
  • CampaignFundsSumAvailableForTransfer - Сумма, доступная для переноса на другую кампанию, в валюте рекламодателя, без учета НДС.
  • SharedAccountFundsRefund - Параметр утратил актуальность, всегда возвращается значение 0.
  • SharedAccountFundsSpend - Сумма средств, израсходованных по данной кампании за все время ее существования, с учетом НДС.
  • AttributionModel - Модель атрибуции, используемая для оптимизации конверсий:
    • FC — первый переход.
    • LC — последний переход.
    • LSC — последний значимый переход.
    • LYDC — последний переход из Яндекс.Директа.
• В пакете появился документ со всеми устаревшими функциями, посмотреть его можно с помощью команды help("ryandexdirect-deprecated").

В ryandexdirect добавлены функции для управления ставками и приоритетами ключевых фраз и автотаргетингов.

В версии ryandexdirect 3.2.0 добавлено 3 новые функции позволяющие назначать ставки и приоритеты ключевым фразам и автотаргетингам, а также для получения данных, полезных при назначении ставок.

• yadirGetKeyWordsBids - Возвращает ставки и приоритеты для ключевых фраз и автотаргетингов, отвечающих заданным критериям, а также данные торгов: ставки и списываемые цены для различных объемов трафика на поиске и ставки для охвата различных долей аудитории в сетях;
• yadirSetKeyWordsBids - Назначает фиксированные ставки и приоритеты для ключевых фраз и автотаргетингов;
• yadirSetAutoKeyWordsBids - Назначает для фраз ставки на поиске в зависимости от желаемого объема трафика или ставки в сетях в зависимости от желаемой частоты показа (доли аудитории).

Подробно ознакомится с тем, как использовать новые функции можно в виньетке: vignette("yandex-direct-keyword-bids", package = "ryandexdirect").

Пример кода для загрузки данных о ставках и назначении новых ставок.

# подключаем пакет
library(ryandexdirect)

# запрашиваем список ключевых слов
kw <- yadirGetKeyWords()
                       
# запрашиваем ставки
bids  <- yadirGetKeyWordsBids(kw$Id)

# запрашиваем ставки и данные торго на поиске
bids_search <- yadirGetKeyWordsBids(kw$Id,
                                    AuctionBids = "search")
                                    
# запрашиваем ставки и данные торго в сетях
network_bids <- yadirGetKeyWordsBids(kw$Id,
                                     AuctionBids = "network")

# запрашиваем список рекламных кампаний
camp <- yadirGetCampaign()

# меняем ставки
setbid     <- yadirSetKeyWordsBids(CampaignIds = camp$Id[1],
                                   SearchBid   = 9)

# меняем ставки
autosetbids <- yadirSetAutoKeyWordsBids(KeywordIds = kw$Id,
                                        TargetTrafficVolume = 50)

Установка новой версии пакета

На данный момент функционал находится в тестовом режиме и доступен только при установке из GitHub с помощью команды: devtools::install_github("selesnow/ryandexdirect").

Новые виньетки и аргумент FetchBy

Достаточно важное обновление ryandexdirect:

1. В ryandexdirect добавлены 2 виньетки:

• Загрузка статистики из сервиса API Reports. vignette("yandex-direct-get-statistic", package = "ryandexdirect")
• Авторизация в API Яндекс Директ. vignette("yandex-direct-auth", package = "ryandexdirect")

2. В функцию yadirGetReport добавлен аргумент FetchBy. За эту доработку спасибо Эдуарду Горху.

Аргумент FetchBy знаком пользователям пакета RGA написанным Артёмом Клевцовым.

Зачем это надо?
В сервисе API Reports существует недокументированное ограничение на 1 000 000 строк который вы можете загрузить в рамках одного отчёта. В случае если у вас большой аккаунт, и вы запрашиваете данные за длительный период в глубокой детализации возможна ситуация, что вы получите не полный ответ. При этом API не даст никакого оповещения о проблеме.

Теперь функция yadirGetReport при возникновении подобной ситуации выведет вам сообщение 'You have reached the limits of Yandex.Direct API. Try to use "FetchBy" parameter with DateRangeType = "CUSTOM_DATE", "DateFrom" and "DateTo". If you are already using it, try to choose a smaller value.'. Это говорит о том, что вы превысили лимит, и скорее всего в ответе получили неполный объём данных.

Теперь вы можете использовать аргумент FetchBy и разбить ваш запрос на части, по временному диапазону.

Возможные значения: "DAY", "WEEK", "MONTH", "QUARTER", "YEAR"

Я решил этот функционал сделать ещё полезнее и дописал следующее. В случае достижения лимита, помимо предупреждения в возвращаемый дата фрейм будет добавлен атрибут limit_reached, в котором будет храниться вектор с логинами, тех аккаунтов по которым был достигнут лимит. С помощью команды attr вы можете получить этот вектор, и использовать его для фильтрации полученного результата и повторного сбора данных из с разбивкой запроса на части.

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

Пример использования описанного выше функционала:

library(ryandexdirect)

# создаём результирующий фрейм
res   <- data.frame()

# список логинов
log_list <- c("login1", "login2","login3", "login4")

# создаём последовательность уровней временной разбивки запросов
fetching_seq <- c("OFF", "MONTH", "WEEK", "DAY")

# счётчик последовательностей разбивки
fetch_id <- 1

# запускаем цикл загрузки данных с проверкой лимитов
while ( ! is.null( log_list ) ) {
  
  # определяем уровень разбивки запроса
  if ( fetching_seq[fetch_id] == "OFF" ) fetching <- NULL else fetching <- fetching_seq[fetch_id]
  
  # запускаем сбор данных
  data <- yadirGetReport(DateRangeType = "CUSTOM_DATE", 
                         DateFrom      = "2018-06-01", 
                         DateTo        = "2019-05-31", 
                         FieldNames    = c("Date","CampaignName","Impressions","Clicks"),
                         Login         = log_list,
                         FetchBy       = fetching)
  
  # если загрузка была по одному аккаунту добавляем его логин
  if ( length(log_list) == 1 ) {
    data$Login <- log_list
  }
  
  # проверяем список аккаунтов достигших лимита
  log_list <- attr(data, "limit_reached")
  
  # выводим список аккаунтов достигших лимита
  print(log_list)
  
  # если есть аккаунты достигшие лимита
  if ( length(log_list) > 0 ) {
    # очищаем от них общую таблицу
    data <- data[ ! data$Login %in% log_list, ]
    # переключаем уровень разбивки на более мелкий
    fetch_id <- fetch_id + 1
  } 
  
  # дописываем в результирующий фрейм данные
  # по тем аккаунтам которые не упёрлись в лимит
  if ( nrow(data) > 0 ) {
    res <- dplyr::bind_rows(res, data)
  }
  
  # проверяем модно ли разбить запрос на более мелкие части
  if ( fetch_id > length(fetching_seq) && length(log_list) > 0 ) {
    message("Запрос невозможно разбить на меньшие части")
    message("Аккаунты которые достигли лимита при загрузке данных по дням: ", paste(log_list, collapse = ", "))
    limits_login <- log_list
    break
  }
}

3. Исправлена проблема, которая возникала при запросе статистики сразу из нескольких клиентских аккаунтов, которые являются автономными по отношению друг к другу, т.е. не привязаны к одному агентскому аккаунту.

Версия 3.6.0 в течении ближайших нескольких недель будет находиться в тесовом режиме, в связи с чем пока установить актуальную версию можно только с GtHub с помощью команды devtools::install_github("selesnow/ryandexdirect").

Доработки ryandexdirect и публикация пакета на CRAN

За последние несколько месяцев было проведено много работ по подготовке ryandexdirect к публикации на CRAN, большая часть из которых была направлена на исправление его документации.

Ранее под разные операционные системы были две разные версии пакета, теперь, после публикации на CRAN у вас не будет проблем с установкой пакета, и кодировкой текста. Правда все русскоязычные сообщения из пакета были удалены, таковы требования CRAN, в коде можно использовать только латиницу.

Так же был исправлен ряд ошибок, и немного внедрены некоторые доработки.

Доработки

1. Для сокращении имени, и приведения названия функций к одному виду у функции yadirGetCampaignList появилась дублирующая функция yadirGetCampaign, для совмещения новой версии пакета с кодом написанным под более ранними версиями обе функции в нём остаются;
2. Доработка предложенная в тикете #18 , в результат возвращаемый функцией yadirGetCampaign добавлены следующие поля:
   • SearchBidStrategyType - Тип стратегии показа объявлений в поисковой сети Яндекса;
   • NetworkBidStrategyType - Тип стратегии показа объявлений в поисковой сети Яндекса;
3. Из пакета удалены следующие устаревшие функции: yadirGetSummaryStat, yadirGetCampaignListOld, yadirGetLogsData, yadirGetMetrikaGAData;
4. В функции yadirGetCampaign и yadirGetCampaignList по умолчанию в фильтр по типу кампаний включена загрузка кампаний с типом CPM_BANNER_CAMPAIGN;
5. Функция yadirGetToken теперь так же может сохранять полученный токен в локальный файл, если пользователь даст на это разрешение, но обновляться такой токен по истечению срока не будет, т.к. к нему не привязан refresh token.

Исправления

1. Исправлена ошибка в функции yadirAuth, возникающая после автоматического обновления просроченного токена.
2. Исправлена ошибка в функции yadirGetToken, которую я допустил внедрив доработку по сохранению токена в локальный файл.

Для установки или обновления пакета из CRAN можно воспользоваться стандартной командой install.packages("ryandexdirect").

Бейджи

Небольшие доработки функций yadirGetAds и yadieGetSiteLinks

Последний релиз 2018 года посвящён улучшениям функций yadirGetAds и yadieGetSiteLinks.

Данные обновления связаны с тикетом #15

Собственно, что было доработано:

1. Функция yadirGetAds теперь возвращает поле SitelinkSetId, инедтификаторы набора быстрых ссылок прикреплённого к объявлению.
2. В функцию yadirGetSiteLinks добавлен аргумент Ids, который на вход принимает вектор с идентификаторами наборов быстрых ссылок, информацию по которым вам необходимо получить.

Для обновления пакета до версии 3.0.13 воспользуйтесь одной из приведённых ниже команд:

обновить на Windows: devtools::install_github("selesnow/ryandexdirect")
обновить на Linux/Mac: devtools::install_github("selesnow/ryandexdirect", subdir = "utf8")

Изменения в справочнике валют

Что нового

1. Переписана функция yadirGetDictionary.
2. Функция yadirCurrencyRates удалена из ryandexdirect.

Функция yadirGetDictionary

В связи с изменениями в справочнике валют, которые недавно были опубликованы в блоге API Яндекс.Директ, была частично переписана функция yadirGetDictionary.

• из справочника исключена валюта YND_FIXED;
• для остальных валют не возвращаться курс у. е. — параметры Rate и RateWithVAT.

Соответственно сам справочник валют теперь нельзя использовать для конвертации денежных данных из одной валюты в другую. Сам справочник валют теперь хранит следующую информацию.

• FullName — название валюты на языке, указанном в запросе в HTTP-заголовке Accept-Language;
• BidIncrement — шаг торгов;
• MaximumBid — максимальная ставка за клик (техническое ограничение);
• MaximumCPM — максимальная ставка или цена за тысячу показов для медийной рекламы;
• MinimumAverageCPA — минимальное значение средней цены конверсии для стратегии AVERAGE_CPA, минимальное значение средней цены установки для стратегии AVERAGE_CPI;
• MinimumAverageCPC — минимальное значение средней цены клика для стратегий AVERAGE_CPC, WEEKLY_CLICK_PACKAGE;
• MinimumBid — минимальная ставка за клик;
• MinimumCPM — минимальная ставка или цена за тысячу показов для медийной рекламы;
• MinimumDailyBudget — минимальный дневной бюджет кампании;
• MinimumPayment — минимальный платеж (без учета НДС), минимальный дневной бюджет общего счета;
• MinimumTransferAmount — минимальная сумма перевода между кампаниями;
• MinimumWeeklySpendLimit — минимальный недельный бюджет.

Пример кода для запроса справочника валют:

cd <- yadirGetDictionary(DictionaryName = "Currencies",
                         Login          = "my_login",
                         Language       = 'en')

Функция yadirCurrencyRates

В связи с теми же изменениями yadirCurrencyRates теперь работает не корректно, я не вижу смысла в дальнейшем поддерживать две функции которые выполняют одну и туже операцию, поэтому данная функция удалена из пакета.

Доработана функция для загрузки списка клиентов из агентского аккаунта.

Функция yadirGetClientList переведена на работу с API версии 5

С сегодняшнего дня многие из вас при работе с функцией yadirGetClientList могли столкнуться со следующей ошибкой:

Error in dataRaw$data[[i]][c("FIO", "Login", "DateCreate", "Phone", "Email", : invalid subscript type 'list'

Связана она с тем, что функция работа со старой, т.е. 4 версией API Яндекс.Директ, и метод которой она использовался больше не поддерживается, в связи с чем функция была полностью переписана на 5 версию API.

Что нового

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

Был значительно расширен список полей которые она возвращает.

В результирующую таблицу были добавлены следующие поля:

• Currency - Валюта рекламодателя.
• VatRate - Ставка НДС агентства.
• ClientId - Идентификатор рекламодателя.
• CountryId - Идентификатор страны рекламодателя из справочника регионов.
• AccountQuality - Показатель качества аккаунта (см. раздел Показатель качества аккаунта помощи Директа).
• Grants - Полномочия рекламодателя по управлению кампаниями. Возвращаюется в виде строки, формата "Агентство: Имя полномочия - Есть ли у клиента данное полномочие", полномочия между собой разделяются знаком ";".
• Representatives - Представители рекламодателя. Возвращаюется в виде строки, формата "Логин пользователя: Роль пользователя". Роли могут быть:
  * CHIEF — главный представитель рекламодателя.
  * DELEGATE — обычный представитель рекламодателя.
  * UNKNOWN — роль не поддерживается в данной версии API.
• Restrictions - Количественные ограничения на объекты рекламодателя. Возвращаюется в виде строки, формата "Имя ограничения: Значение ограничения". Ограничения бывают следующие:
  * CAMPAIGNS_TOTAL_PER_CLIENT — максимальное количество кампаний у рекламодателя.
  * CAMPAIGNS_UNARCHIVED_PER_CLIENT — максимальное количество кампаний, не находящихся в архиве.
  * ADGROUPS_TOTAL_PER_CAMPAIGN — максимальное количество групп в кампании.
  * ADS_TOTAL_PER_ADGROUP — максимальное количество объявлений в группе.
  * KEYWORDS_TOTAL_PER_ADGROUP — максимальное количество ключевых фраз в группе.
  * AD_EXTENSIONS_TOTAL — максимальное количество расширений к объявлениям у рекламодателя.
  * STAT_REPORTS_TOTAL_IN_QUEUE — максимальное количество одновременно формируемых статистических отчетов.
  * FORECAST_REPORTS_TOTAL_IN_QUEUE — максимальное количество хранимых на сервере отчетов о прогнозируемом бюджете, количестве показов и кликов.
  * WORDSTAT_REPORTS_TOTAL_IN_QUEUE — максимальное количество хранимых на сервере отчетов о статистике поисковых запросов.
• Setting - Настройки рекламодателя. Возвращается в виде строки формата "Имя настройки: Значение настройки". На данный момент доступны следующие настройки:
  * CORRECT_TYPOS_AUTOMATICALLY — автоматически исправлять ошибки и опечатки.
  * DISPLAY_STORE_RATING — дополнять объявления данными из внешних источников (см. раздел Данные из внешних источников помощи Директа).
  * SHARED_ACCOUNT_ENABLED — подключен общий счет.

Как установить новую версию

Для установки новой версии воспользуйтесь следующим кодом:

install.packages("devtools")
devtools::install_github("selesnow/ryandexdirect")

Внимание

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