rmytarget 2.0.1 — перевод пакета на работу с MyTarget API v2

Данное обновление связано с недавней новостью от поддержки API MyTarget, о том, что с 1 декабря 2018 года полностью прекращается поддержка API v1, а rmytarget изначально был написан именно на основе этого API.

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

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

Новая версия rmytarget доступна как на GitHub, так и на CRAN.

Установить rmytarget 2.0.1 с CRAN: install.packages("rmytarget")
Установка rmytarget 2.0.1 с GitHub: devtools::install_github("selesnow/rmytarget")

На что необходимо обратить внимание

1. Из пакета была удалена функция myTarGetTotalStats, т.к. она на самом деле не несёт никакой пользы, для работы со статикой используйте функцию myTarGetStats.
2. Во всех функциях которые запрашивают какие либо данные, как информацию по объектам, так и по запросу статистической информации в получамом результате добавились новые поля, поэтому если вы отправляете запрошенные из API mytarget данные в базу данных вам необходимо будет добавить новые поля в таблицы.

Основные изменения

Статистика

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

Аргумент object_id больше не является обязательным, если вы не передаёте id нужных вам объектов функция myTarGetTotalStats сама запросит id всех объектов, в зависимости от того какой тип объекта вы указали в аргументе object_type.

Так же вам теперь доступен один новый агрумент — metrics, данный аргумент отвечает за набор полей который вы получите, начиная с версии rmytarget 2.0.0 вам доступны данные более чем по 100 различным показателям, все показатели разбиты на 10 групп, аргумент metrics позволяет вам передать вектор состоящий из назвыний групп показателей которые вы хотите получить, например c(«base», «video», «viral») позволит вам запросить все метрики входящие в группы base, video и viral. По умолчанию имеет значение «base». Если вы хотите запросить метрики из всех доступных групп вам необязательно перечислять названия всех групп в векторе, можно просто передать в metrics значение «all».

Группы показателей

base — базовые метрики:

• shows — количество показов;
• clicks — количество кликов;
• goals — количество достижений целей (цели Top@Mail.ru для сайтов и установок для мобильных приложений);
• spent — списания;
• cpm — среднее списание за 1000 просмотров;
• cpc — среднее списание за 1 клик;
• cpa — среднее списание за достижение 1 цели;
• ctr — процентное отношение количества кликов к количеству просмотров;
• cr — процентное отношение количества достижений целей к количеству кликов.

events — метрики для рекламируемых сообщений в ленте социальных сетей:

• opening_app — количество открытий рекламируемого приложения соцсетей;
• opening_post — количество открытий рекламируемого сообщения в ленте соцсетей;
• moving_into_group — количество переходов на страницу группы из рекламируемого сообщения;
• clicks_on_external_url — количество кликов по внешней ссылке в рекламируемом сообщении;
• launching_video — количество запусков видео в рекламируемом сообщении;
• comments — количество оставленных комментариев в рекламируемом сообщении;
• joinings — количество присоединений к группе через рекламируемое сообщение;
• likes — количество лайков рекламируемого сообщения;
• shares — количество действий «Поделиться» для рекламируемого сообщения;
• votings — количество действий голосования в рекламируемом сообщении.

uniques — метрики по количеству уникальных пользователей:

• reach — количество уникальных пользователей, увидевших объявление за указанный период;
• total — общее количество уникальных пользователей, увидевших объявление за всё время;
• increment — количество новых уникальных пользователей, увидевших объявление за указанный период;
• frequency — средняя частота показа объявлений одному уникальному пользователю.

video — метрики для видеорекламы:

• started — количество стартов воспроизведения видео;
• paused — количество пауз воспроизведения видео;
• resumed_after_pause — количество воспроизведения видео после паузы;
• fullscreen_on — количество включений полноэкранного режима воспроизведения видео;
• fullscreen_off — количество выключений полноэкранного режима воспроизведения видео;
• sound_turned_off — количество выключений звука видео;
• sound_turned_on — количество включений звука видео;
• viewed_10_seconds — количество просмотров первых 10 секунд видео;
• viewed_25_percent — количество просмотров первых 25% длительности видео;
• viewed_50_percent — количество просмотров первых 50% длительности видео;
• viewed_75_percent — количество просмотров первых 75% длительности видео;
• viewed_100_percent — количество просмотров 100% длительности видео;
• viewed_10_seconds_rate — процент просмотров с достижением первых 10 секунд видео;
• viewed_25_percent_rate — процент просмотров с достижением первых 25% длительности видео;
• viewed_50_percent_rate — процент просмотров с достижением первых 50% длительности видео;
• viewed_75_percent_rate — процент просмотров с достижением первых 75% длительности видео;
• viewed_100_percent_rate — процент просмотров с достижением 100% длительности видео;
• depth_of_view — средняя глубина просмотра видео (в процентах);
• view_10_seconds_cost — средняя стоимость просмотра первых 10 секунд видео;
• viewed_25_percent_cost — средняя стоимость просмотра первых 25% длительности видео;
• viewed_50_percent_cost — средняя стоимость просмотра первых 50% длительности видео;
• viewed_75_percent_cost — средняя стоимость просмотра первых 75% длительности видео;
• viewed_100_percent_cost — средняя стоимость просмотра 100% длительности видео.

viral — метрики виральных событий:

• impressions — количество показов расшаренного рекламного сообщения в социальных сетях;
• reach — количество уникальных пользователей, увидивших расшаренное рекламное сообщение за указанный период;
• total — общее количество уникальных пользователей, увидевших расшаренное рекламное сообщение за всё время;
• increment — количество новых уникальных пользователей, увидевших расшаренное рекламное сообщение за указанный период;
• frequency — средняя частота показа расшаренного рекламного сообщения одному уникальному пользователю;
• opening_app — количество открытий рекламируемого приложения из расшаренного рекламного сообщения;
• opening_post — количество открытий расшаренного рекламируемого сообщения в ленте соцсетей;
• moving_into_group — количество переходов на страницу группы из расшаренного рекламируемого сообщения;
• clicks_on_external_url — количество кликов по внешней ссылке в расшаренном рекламируемом сообщении;
• launching_video — количество запусков видео в расшаренном рекламируемом сообщении;
• comments — количество оставленных комментариев в расшаренном рекламируемом сообщении;
• joinings — количество присоединений к группе через расшаренное рекламируемое сообщение;
• likes — количество лайков расшаренного рекламируемого сообщения;
• shares — количество действий «Поделиться» для расшаренного рекламируемого сообщения;
• votings — количество действий голосования в расшаренном рекламируемом сообщении.

carousel — статистика по отдельным слайдам рекламной карусели (N — от 1 до количества слайдов):

• slide_N_shows — количество показов слайда N;
• slide_N_clicks — количество кликов по слайду N;
• slide_N_ctr — процентное отношение количества кликов к количеству просмотров по слайду N;

tps — статистика по дополнительным списаниям:

• tps — дополнительные списания за использование сервиса moat;
• tpd — дополнительные списания за использование сторонних данных (от dmp).

moat — статистика по данным сервиса moat:

• impressions — количество показов;
• in_view — количество видимых показов;
• never_focused — количество показов в неактивной вкладке;
• never_visible — количество показов вне зоны видимости;
• never_50_perc_visible — количество показов с зоной видимости объявления менее 50%;
• never_1_sec_visible — количество показов с длительностью видимости менее 1 секунды;
• human_impressions — количество верифицированных показов;
• impressions_analyzed — количество анализируемых показов;
• in_view_percent — процент видимых показов;
• human_and_viewable_perc — процент верифицированных показов;
• never_focused_percent — процент показов в неактивной вкладке;
• never_visible_percent — процент показов вне зоны видимости;
• never_50_perc_visible_percent — процент оказов с зоной видимости объявления менее 50%;
• never_1_sec_visible_percent — процент показов с длительностью видимости менее 1 секунды;
• in_view_diff_percent — разница в количестве видимых показов;
• active_in_view_time — среднее время нахождения объявления в зоне видимости;
• attention_quality — уровень вовленчения;

Загрузка объектов

Рекламные кампании

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

• status — Статус кампании. Так же может возвращаться статус deleted для удаленных кампаний. В кампании со статусом deleted возможно изменить только сам статус.
• name — Название кампании
• created — Время создания
• date_end — Дата окончания кампании
• date_start — Дата старта кампании
• utm — UTM-метки для добавления в URL объявлений. Если не указаны и enable_utm=true, то метки будут формироваться автоматически.
• mixing — Распределение бюджета
• id — Идентификатор кампании

Объявления

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

• id — Идентификатор объявления
• status — Статус объявления. Также может возвращаться статус deleted для удаленных кампаний. В объявлении со статусом deleted возможно только изменение статуса
• updated — Время последнего обновления
• moderation_status — Статус модерации объявления. Возможные значения: pending — объявление не промодерировано; allowed — объявление разрешено; banned — объявление запрещено
• call_to_action — Действие при клике по баннеру. Возможные значения описаны в баннерном формате объявления
• created — Время создания
• campaign_id — Идентификатор рекламной кампании
• title — Заголовок объявления
• text — Текст объявления
• url — Ссылка
• url_object_id — Идентификатор связанного объекта
• url_object_type — Тип связанного объекта
• url_id — Идентификатор ссылки

Ограничения

• Статистика с разбивкой по дням возвращается не более чем за последние 92 дня.
• По прежнему вы можете запросить всего 5 токенов на один аккаунт, при этом теперь пакет предложит вам удалить все старые токены, в случае если у вас неосталось слотов для получения токена под какой либо аккаунт, при этом повторно необходимо ввести логин аккаунта токены к которому требуется удалить.