knitr::opts_chunk$set( eval = FALSE, collapse = TRUE, comment = "#>" )
Для начала работы с пакетом предварительно его требуется подключить.
library(ryandexdirect)
Для загрузки статистики =в пакете ryandexdirect
предназначена функция yadirGetReport
. Данная функция взаимодействует с API 'Сервис Reports', подробно о нём можно узнав в офйициальной документации, в текущей виньетке так же используется материал официальной спавки по работе с API сервиса 'Reports'.
c("Date","CampaignName","Impressions","Clicks")
. Актуальный список полей можно найти по ссылке.c("Clicks GREATER_THAN 99","Impressions LESS_THAN 1000")
.c(182453, 182452, 23458860)
. Получить список идентификаторов целей можно с помозью функции rym_get_goals
входящей в пакет rym
.c("LSC", "LC", "FC")
. Более подробно можно узнать в разделе "Модели атрибуции".yadirAuth
или yadirGetToken
. Авториа=зационный токен для работы с API Яндекс.Директ.В параметре ReportType укажите тип отчета. Тип отчета влияет на набор доступных полей и группировку данных.
Например, если выбран тип отчета SEARCH_QUERY_PERFORMANCE_REPORT, то данные в отчете будут сгруппированы по идентификатору группы AdGroupId и поисковому запросу Query. Обратите внимание, что добавление группировок данных не приводит к автоматическому добавлению соответствующих полей в отчет: отчет содержит только поля, явным образом перечисленные в параметре FieldNames.
Наиболее общий тип отчета — CUSTOM_REPORT. Он не добавляет никаких дополнительных группировок.
Типы отчетов представлены в таблице.
library(magrittr) table_report_types <- data.frame(reptype = c("ACCOUNT_PERFORMANCE_REPORT", "CAMPAIGN_PERFORMANCE_REPORT", "ADGROUP_PERFORMANCE_REPORT", "AD_PERFORMANCE_REPORT", "CRITERIA_PERFORMANCE_REPORT", "CUSTOM_REPORT", "REACH_AND_FREQUENCY_PERFORMANCE_REPORT", "SEARCH_QUERY_PERFORMANCE_REPORT"), descr = c("Статистика по аккаунту рекламодателя", "Статистика по кампаниям", "Статистика по группам объявлений", "Статистика по объявлениям", "Статистика по условиям показа", "Статистика с произвольными группировками", "Статистика по медийным кампаниям. Отчет содержит только данные по кампаниям с типом «Медийная кампания», кампании остальных типов игнорируются", "Статистика по поисковым запросам"), grouping = c("–", "CampaignId", "AdGroupId", "AdId", "AdGroupId, CriteriaId, CriteriaType", "–", "В запросе на формирование отчета необходимо указать в поле FieldNames значение CampaignId", "AdGroupId, Query")) names(table_report_types) <- c("Тип отчёта", "Описание", "Добавляется группировка") table_report_types <- kableExtra::kable(table_report_types) kableExtra::kable_styling(table_report_types, bootstrap_options = c("striped", "hover"))
Во всех типах отчетов применяется единичная атрибуция (single attribution): каждый показ и клик относится только к одному условию показа, региону, возрасту пользователя и т.д.
Полный список допустимых полей можно найти в официальной документации.
Поля указываются в следующих параметрах отчета:
Наборы допустимых полей в этих параметрах различаются. Например, поле CampaignName может быть добавлено как столбец в отчете, но не может использоваться для фильтрации данных, а поле Keyword — наоборот, используется только для фильтрации данных и в отчете не выводится.
Тип отчета также влияет на набор допустимых полей и их назначение, смотрите таблицу по ссылке.
Каждое поле в зависимости от выбранного типа отчёта может иметь свой тип:
Например, поле CampaignId для типа отчета CUSTOM_REPORT является сегментом: если его добавить в отчет, данные будут сгруппированы по кампаниям. А для типа отчета ADGROUP_PERFORMANCE_REPORT поле CampaignId является атрибутом: данные уже сгруппированы по AdGroupId, а идентификатор кампании является для каждой группы фиксированным значением.
Для фильтрации данных в отчете используйте аргумент FilterList
. Каждый фильтр представляет собой критерий отбора данных. Фильтры объединяются по условию AND: в отчет попадают данные, для которых выполнены все фильтры. Фильтр состоит из трех параметров:
Например, чтобы отобрать в отчет строки, в которых количество целевых визитов больше 10, используйте фильтр FilterList = "Conversions GREATER_THAN 10"
. Для применения нескольких фильтров перечислите их выражения в векторе, например FilterList = c("Clicks GREATER_THAN 99","Impressions LESS_THAN 1000")
оставит строки в которых более 99 кликов и менее 1000 показов.
Соответствие полей и операторов представлено в таблице.
library(magrittr) table_report_types <- data.frame(field = c("AdNetworkType, CampaignId, CampaignType", "AdFormat, AdGroupId, AdId, Age, AudienceTargetId, CarrierType, ClickType, CriteriaType, CriterionType, Device, DynamicTextAdTargetId, ExternalNetworkName, Gender, LocationOfPresenceId, MatchType, MobilePlatform, Placement, RlAdjustmentId, Slot, SmartBannerFilterId, TargetingLocationId", "Clicks, Conversions, ImpressionReach, Impressions", "AvgClickPosition, AvgCpc, AvgCpm, AvgImpressionFrequency, AvgImpressionPosition, AvgPageviews, AvgTrafficVolume, BounceRate, ConversionRate, Cost, CostPerConversion, Ctr, GoalsRoi, ImpressionShare, Profit, Revenue, WeightedCtr, WeightedImpressions, ", "Keyword, MatchedKeyword, Query"), operators = c("EQUALS, IN", "EQUALS, IN, NOT_EQUALS, NOT_IN", "EQUALS, IN, GREATER_THAN, LESS_THAN", "GREATER_THAN, LESS_THAN", "EQUALS, IN, NOT_EQUALS, NOT_IN, STARTS_WITH_IGNORE_CASE, STARTS_WITH_ANY_IGNORE_CASE, DOES_NOT_START_WITH_IGNORE_CASE, DOES_NOT_START_WITH_ALL_IGNORE_CASE")) names(table_report_types) <- c("Имя поля", "Доступные операторы") table_report_types <- kableExtra::kable(table_report_types) kableExtra::kable_styling(table_report_types, bootstrap_options = c("striped", "hover"))
Все денежные значения в фильтрах следует указывать в виде целых чисел: сумм в валюте, умноженных на 1 000 000.
Вы можете запрашивать количество достижений каждой отдельно взятой цели с помощью аргумента Goals.
Данный аргумент принимает вектор из набора идентификаторов целей, при этом в одном запросе можно запрашивать данные не более чем по 10 целям. Получить идентификаторы цели можно несколькими способами:
rym
и входящей в него функции rym_get_goals
;Если параметр указан, то в отчете вместо полей ConversionRate, Conversions, CostPerConversion, GoalsRoi и Revenue с агрегированными данными по всем целям будут выведены аналогичные поля с именами вида <поле>
Модель атрибуции — это правило, какой переход считать источником визита:
Модели атрибуции, используемые при расчете данных по целям Яндекс.Метрики. Аргумент AttributionModels можно указать, только если указан параметр Goals. Если параметр Goals указан, а параметр AttributionModels — нет, по умолчанию используется значение LSC.
Если указано несколько моделей атрибуции, данные будут выведены по каждой модели в отдельности.
В сервисе 'API Reports' есть недокументированное ограничение на максимальное количество строк которое можно получить в ответе. По умолчанию оно равняется 1 000 000 строк. В большинстве случаев это незначительное ограничение, но при загрузке отчётов из больших аккаунтов с глубокой детализацией, за длительный период скорее всего вы столкнётесь с этой проблемой, и даже её не заметите.
Функция yadirGetReports
столкнувшись с этим ограничением выведет уведомление '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"
Загрузка в таком случае потребует большего времени но вернёт полные данные.
Помимо уведомления, таблица которую вы получите в рзельтате работы функции yadirGetReports
будет иметь атрибут limit_reached. В данном атрибуте хранится список логинов тех аккаунтов по котором был достигнул лимит при загрузке данных. Получить этот список можно с помощью attr(data, "limit_reached")
, в том случае если объект с полученной статистикой имеет имя data, в другом случае attr(имя_полученного_объекта, "limit_reached")
.
Наиболее правильный вариант использования этого функцияала заключается в следующем:
while
запускает сбор статистики из любого колличества аккаунтов. Первый раз без разбивки запроса на временные интервалы.Данный цикл должен работать до тех пор пока не будет выполненно одно из следующих условий:
Ниже приведён пример кода реализующего описанный выше механизм.
library(ryandexdirect) # создаём результирующий фрейм res <- data.frame() # список логинов log_list <- c("login1", "login2","login3", "login4") # проверка лиситов # отмечаем что это первый запуск check <- "first" # создаём последовательность уровней временной разбивки запросов 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 } }
Все перечисленные в заголовке аргументы используются для авторизации в API, хранении и использовании учётных данных. Более подробно о них можно узнать из виньетке посвящённой процессу авторизации, с помощью vignette("yandex-direct-auth", package = "ryandexdirect")
.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.