---
title: "2. Get Facebook Marketing Insight"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{2. Get Facebook Marketing Insight}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  eval=FALSE,
  collapse = TRUE,
  comment = "#>"
)
```


Для загрузки статистических данных из рекламных аккаунтов Facebook в пакете `rfacebookstat` необходимо использовать функцию `fbGetMarketingStat`.

## Аргументы функции `fbGetMarketingStat`

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

* *accounts_id* - ID рекламных аккаунтов, перед ID необходимо указать префикс `act_`, вы можете указать вектор из ID аккаунтов если требуется загрузить данные из набора аккаунтов. По умолчанию запрашивает значение опции *rfacebookstat.accounts_id*.
* *sorting* - Поле для сортировки полученных данных, так же вы можете указать направление добавив "_ascending" или "_descending" в поле сортировки. Например "reach_descending". Для действий вы можете сортировать по типу действия в форме "actions: <action_type>". Например, ["actions: link_click_ascending"]. Вы можете задать только одно поле для сортировки.
* *level* - Уровень группировки данных, принимает одно из следующих значений: ad, adset, campaign, account. По умолчанию имеет значение account.
* *action_breakdowns* - Разбивки по действиям, более подробно о них можно узнать в [документации](https://developers.facebook.com/docs/marketing-api/insights/breakdowns#actionsbreakdown) к API Facebook, так же более подробно они будут рассмотрены позже в этой виньетке.
* *breakdowns* - Общие разбивки которые предоставляют дополнительные возможности по группировке данных, подробности в [документации](https://developers.facebook.com/docs/marketing-api/insights/breakdowns#ageandgender) к API Facebook, так же этот аргумент будет более подробно рассмотрен немного ниже.
* *fields* - Поля которые вы хотите загрузить из API, полный список всех полей доступен по [ссылке](https://developers.facebook.com/docs/marketing-api/reference/ad-account/insights).
* *filtering* - Текстовая строка или вектор. Фильтрацию отчёта вы можете задавать либо в JSON формате либо в упрощенном формате, более подробно о фильтрации будет написано немного ниже.
* *date_start* - Дата начала отчётного периода.
* *date_stop* - Дата завершения рабочего отчётного периода.
* *date_preset* - С попомщью этого аргумента, вы можете использовать преднастройки для запроса данных за относительный период, например за прошлый месяц. Допустимые значения: today, yesterday, this_month, last_month, this_quarter, lifetime, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, last_week_mon_sun, last_week_sun_sat, last_quarter, last_year, this_week_mon_today, this_week_sun_today, this_year
* *request_speed* - Скорость отправки запросов, возможные значения "normal", "fast" или "slow". Так же можно задать числовое значение, которое будет задавать количество секунд в паузе между отправкой запросов к API.
* *fetch_by* - позволяет разбить большой запрос, за длительный период, на части по неделям, месяцам, кварталам и годам. Приннимает одно из следующих значений: "day", "week", "month", "quarter", "year".
* *api_version* - Версия API к которой будет отправлен запрос, по умолчанию берётся значение из опции *rfacebookstat.api_version*.
* *action_report_time* - Допустимые значения: impression, conversion. Определяет отчет о времени действия статистики. Например, если человек видел объявление 1 января, но совершил конверсию 2 января, при запросе API с `action_report_time = "impression"`, вы увидите конверсию 1 января. Когда вы запросите API с помощью `action_report_time = "conversion"`, вы увидите преобразование 2 января.
* *attribution_window* - Окна атрибуции
* *interval* - Группировка по временному интервалу, возможные значения: day, all_days, overall, monthly, weekly, либо вы можете числом указать количество дней, и результат вашего запроса будет сгруппирован такими временными отрезками.
* *use_unified_attribution_setting* - Если для этого параметра установлено значение true, результаты вашей рекламы будут показываться с использованием унифицированных настроек атрибуции, определенных на уровне группы объявлений, а параметр use_account_attribution_setting будет игнорироваться.
* *use_account_attribution_setting* - Если для этого параметра установлено значение true, результаты ваших объявлений будут отображаться с использованием настроек атрибуции, определенных для рекламного аккаунта.
* *console_type* - Тип выводимых в консоль данных, возможные значения progressbar, message.
* *username* - Логин на Facebook под которым вы проходили авторизацию, используется для хранения учётных данных для работы с API.
* *token_path* - Путь к папке в которой хранится файл с учётными данными на Facebook, которые вы получили при авторизации.
* *access_token* - Токен доступа к API полученный с помощью функции `fbGetToken`, по умолчанию запрашивается значение опции. *rfacebookstat.access_token*

## Пример запроса статистики

```{r}
library(rfacebookstat)

options(rfacebookstat.access_token = "ваш токен",
        rfacebookstat.accounts_id  = "act_000000000")

fb_data <- fbGetMarketingStat(
                  level              = "campaign",
                  fields             = "campaign_name,
                                        impressions,
                                        clicks,
                                        spend,
                                        actions",
                  date_start         = "2019-05-01",
                  date_stop          = "2019-05-10")
```

Выше приведён простейший способ загрузки статистики по показам, кликам, тратам и действиям в разрезе дней и рекламных кампаний.
Использование опций *rfacebookstat.access_token* и *rfacebookstat.accounts_id* не является обязательным, но поможет вам избежать дублирования этих параметров в аргументах всех функций пакета, поэтому я рекомендую именно такой способ установки значений accout_id, access_token, business_id и api_version.

## Учётные данные
С помощью аргументов *username* и *token_path* функция `fbGetMarketingStat()` определяет какие учётные данные ей необходимо использовать для запроса данных, и где эти учётные данные хранятся.

Более подробно об авторизации и этих аргументах написано в виньетке про авторизацию, открыть можно с помощью функции `vignette('rfacebookstat-authorization', package = 'rfacebookstat')`.

## Разбивки (breakdowns)
Разбивки помогают обогащать ваши данные за счёт дополнительных полей и группировок, на данный момент поддерживаются следующие разбивки:

* ad_format_asset
* age
* body_asset
* call_to_action_asset
* country
* description_asset
* gender
* image_asset
* impression_device
* link_url_asset
* product_id
* region
* title_asset
* video_asset
* dma
* frequency_value
* hourly_stats_aggregated_by_advertiser_time_zone
* hourly_stats_aggregated_by_audience_time_zone
* place_page_id
* publisher_platform
* platform_position
* device_platform

Актуальный список группировок всегда можно найти в официальной документации API Facebook по [ссылке](https://developers.facebook.com/docs/marketing-api/insights/breakdowns#ageandgender).

```{r}
library(rfacebookstat)

options(rfacebookstat.access_token = "ваш токен",
        rfacebookstat.accounts_id  = "act_000000000")

fb_data_breakdowns <- fbGetMarketingStat(
  level              = "campaign",
  fields             = "campaign_name,
                        impressions,
                        clicks,
                        spend,
                        actions",
  breakdowns         = "region",
  date_start         = "2019-05-01",
  date_stop          = "2019-05-10")
```

## Разбивки по действиям (action_breakdowns)
Вы можете сгруппировать результаты в поле *actions*. Аргумент *action_breakdowns* позволяет применить указанные ниже разбивки.

* action_device - Устройство, на котором произошло отслеживаемое событие конверсии. Например, «ПК», если человек выполнил конверсию с ПК.
* action_destination - Куда переходят люди, нажав вашу рекламу. Это может быть ваша Страница Facebook, внешний URL-адрес пикселя конверсий или приложение, сконфигурированное с помощью комплекта разработчика ПО.
* action_reaction - Количество реакций на ваши объявления или продвигаемые публикации. Кнопка реакций в рекламе позволяет людям по-разному отреагировать на ее содержание. Можно выбрать "Нравится", "Супер", "Ха-ха", "Ух ты!", "Сочувствую" или "Возмутительно".
* action_target_id - Идентификатор места назначения, в которое переходят люди, нажавшие на ссылку в вашей рекламе. Это может быть ваша Страница Facebook, внешний URL вашего пикселя конверсий, или приложение, сконфигурированное с помощью SDK.
* action_type - Тип действий, выполненных в отношении вашей рекламы, Страницы, приложения или мероприятия после показа объявления кому-либо, даже если эти люди не нажимали объявления. Типы действий включают отметки «Нравится» Страницы, установки приложений, конверсии, ответы на мероприятия и т.д.

```{r}
library(rfacebookstat)

options(rfacebookstat.access_token = "ваш токен",
        rfacebookstat.accounts_id  = "act_000000000")

fb_data_action_breakdowns <- fbGetMarketingStat(
  level              = "campaign",
  fields             = "campaign_name,
                        impressions,
                        clicks,
                        spend,
                        actions",
  action_breakdowns  = "action_reaction",
  date_start         = "2019-05-01",
  date_stop          = "2019-05-10")
```

### Описание полей возвращаемых в разбивке action_type
* app_custom_event.fb_mobile_achievement_unlocked: Разблокированные функции в мобильном приложении
* app_custom_event.fb_mobile_activate_app: Запуски мобильного приложения
* app_custom_event.fb_mobile_add_payment_info: Сведения об оплате в мобильном приложении
* app_custom_event.fb_mobile_add_to_cart: Добавления в корзину в мобильном приложении
* app_custom_event.fb_mobile_add_to_wishlist: Добавления в список желаний в мобильном приложении
* app_custom_event.fb_mobile_complete_registration: Регистрации в мобильном приложении
* app_custom_event.fb_mobile_content_view: Просмотры материалов мобильного приложения
* app_custom_event.fb_mobile_initiated_checkout: Оформление заказов в мобильном приложении
* app_custom_event.fb_mobile_level_achieved: Достижения в мобильном приложении
* app_custom_event.fb_mobile_purchase: Покупки в мобильном приложении
* app_custom_event.fb_mobile_rate: Оценки в мобильном приложении
* app_custom_event.fb_mobile_search: Поисковые запросы в мобильном приложении
* app_custom_event.fb_mobile_spent_credits: Траты кредитов в мобильном приложении
* app_custom_event.fb_mobile_tutorial_completion: Использования обучающей программы в мобильном приложении
* app_custom_event.other: Другие действия в мобильном приложении
* app_install: Установки приложения
* app_use: Использования приложения
* checkin: Посещения
* comment: Комментарии к публикации
* credit_spent: Траты кредитов
* games.plays: Количество раз, когда играли в вашу игру
* landing_page_view: Просмотры целевой страницы
* leadgen.other: Лиды (Форма)
* like: Отметки «Нравится» Страницы
* link_click: Количество кликов на ссылку
* mobile_app_install: Установки мобильного приложения
* offsite_conversion.custom.<custom_conv_id>: Индивидуально настроенные рекламодателем конверсии
* offsite_conversion.fb_pixel_add_payment_info: Добавление платежной информации
* offsite_conversion.fb_pixel_add_to_cart: Добавления товаров в корзину
* offsite_conversion.fb_pixel_add_to_wishlist: Добавления в список пожеланий
* offsite_conversion.fb_pixel_complete_registration: Завершенная регистрация
* offsite_conversion.fb_pixel_custom: Специально настроенные события пикселя, заданные рекламодателем
* offsite_conversion.fb_pixel_initiate_checkout: Инициирует оформление заказа
* offsite_conversion.fb_pixel_lead: Потенциальные клиенты
* offsite_conversion.fb_pixel_purchase: Покупки
* offsite_conversion.fb_pixel_search: Поиск
* offsite_conversion.fb_pixel_view_content: Просматривает контент
* onsite_conversion.flow_complete: Завершенные рабочие процессы на Facebook
* onsite_conversion.messaging_block: Заблокированные переписки
* onsite_conversion.messaging_conversation_started_7d: Начата переписка
* onsite_conversion.messaging_first_reply: Новые переписки
* onsite_conversion.post_save: Сохранения публикации
* onsite_conversion.purchase: Покупки на Facebook
* outbound_click: Исходящие клики
* photo_view: Отметки фотографии Страницы
* post: Репосты публикации
* post_reaction: Реакции на публикацию
* rsvp: Ответы на мероприятие
* video_view: 3-секундные просмотры видео

## Применить одновременно несколько разбивок
Некоторые разбивки можно применять одновременно.
Типы группирования, помеченные звездочкой (*), можно объединить с action_type, action_target_id и action_destination (название action_target_id).

* action_type *
* action_target_id *
* action_device *
* action_device, impression_device *
* action_device, publisher_platform *
* action_device, publisher_platform, impression_device *
* action_device, publisher_platform, platform_position *
* action_device, publisher_platform, platform_position, impression_device *
* action_reaction
* action_type, action_reaction
* age *
* gender *
* age, gender *
* country *
* region *
* publisher_platform *
* publisher_platform, impression_device *
* publisher_platform, platform_position *
* publisher_platform, platform_position, impression_device *
* product_id *

## Окна атрибуции
Количество дней между просмотром или нажатием рекламы и выполнением действия называется окном атрибуции. В функции `fbGetMarketingStat()` управление окнами атрибуции осуществляется с помощью аргумента *attribution_window*.

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

* Атрибуция по кликам: человек нажал рекламу и выполнил действие.
* Атрибуция по просмотрам: человек посмотрел рекламу, не нажал ее, но выполнил действие в пределах окна атрибуции.

По умолчанию окно атрибуции настроено на 1 день после просмотра и 28 дней после клика. Это означает, что вы видите действия, которые произошли в течение 1 дня после просмотра рекламы и в течение 28 дней после ее нажатия. Вы можете изменить окно атрибуции на 1, 7 или 28 дней после просмотра или нажатия рекламы.

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

Например, чтобы узнать, сколько покупок было совершено после просмотра или клика по рекламе за последние 7 дней, выберите для окон атрибуции по просмотрам и кликам продолжительность `attribution_window = c("7d_view", "7d_click")`. 

Аргумент *attribution_window* принимает вектор состоящий из окон атрибуции по которым вы хотите получить данные, при этом значение поля по каждой модели атрибуции которое вы получаете в массиве *actions* будет выделено в отдельный столбец. Например если вы применяете атрибуции *7d_view* и *7d_click*  то поле *lead* будет представлено в трёх столбцах: *lead*, *lead_7d_view*, *lead_7d_click*.

Возможные модели атрибуции: account_default, default, inline, 1d_view, 7d_view, 28d_view, 1d_click, 7d_click, 28d_click, 1d_view_1d_click, 7d_view_1d_click, 28d_view_1d_click, 28d_view_7d_click, 7d_view_7d_click, 28d_view_7d_click, 7d_view_28d_click, 28d_view_28d_click.

### Пример использования окон атрибуции


```{r}
library(rfacebookstat)

options(rfacebookstat.access_token = "ваш токен",
        rfacebookstat.accounts_id  = "act_000000000")

fb_data_action_breakdowns <- fbGetMarketingStat(
  level              = "campaign",
  fields             = "campaign_name,
                        impressions,
                        clicks,
                        spend,
                        actions",
  action_breakdowns  = "action_reaction",
  attribution_window = c('default', '1d_view', '28d_view', '28d_click'),
  date_start         = "2019-05-01",
  date_stop          = "2019-05-10")
```

Более подробно об окнах атрибуции в Facebook можно узнать по следующим ссылкам:

* [Об окнах атрибуции в Ads Manager](https://www.facebook.com/business/help/2198119873776795?id=768381033531365)
* [API Insights / Статистика / Окна атрибуции](https://developers.facebook.com/docs/marketing-api/insights/#sample)
* [Система правил для рекламы](https://developers.facebook.com/docs/marketing-api/ad-rules)

## Фильтрация данных
Вы можете применять фильтры к запрашиваемым данным. Использовать для этого необходимо аргумент `filtering`.
Указывать выражение для фильтрации ы можете в упрощённом формате или в виде JSON объектов, ниже я приведу пример использования обоих вариантов.

Для фильтрации вам необходимо указать поле по которому вы будете фильтровать данные, оператор и значение.
Допустимые операторы для фильтрации: EQUAL, NOT_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, IN_RANGE, NOT_IN_RANGE, CONTAIN, NOT_CONTAIN, IN, NOT_IN, STARTS_WITH, ANY, ALL, AFTER, BEFORE, NONE

### Пример фильтрации в упрощенном формате
```{r}
library(rfacebookstat)

options(rfacebookstat.access_token = "ваш токен",
        rfacebookstat.accounts_id  = "act_000000000")
fb_data <- fbGetMarketingStat(
  level              = "campaign",
  fields             = "campaign_name,
                        impressions,
                        clicks,
                        spend,
                        actions",
  filtering          = "impressions LESS_THAN 5000",
  date_start         = "2019-05-01",
  date_stop          = "2019-05-10")
```

В приведённом примере мы указали фильтр `impressions LESS_THAN 5000` и таким образом оставили строки в которых поле impressions имеет значение менее 5000.

Если вам необходимо использовать множественный оператор (IN_RANGE, NOT_IN_RANGE, IN, NOT_IN) то в упрошенном формате запись будет выглядеть так: `"publisher_platform IN instagram,facebook"`. Важно не ставить проблемы между списком значений.

```{r}
library(rfacebookstat)

options(rfacebookstat.access_token = "ваш токен",
        rfacebookstat.accounts_id  = "act_000000000")
fb_data <- fbGetMarketingStat(
  level              = "campaign",
  fields             = "campaign_name,
                        impressions,
                        clicks,
                        spend,
                        actions",
  filtering          = "publisher_platform IN instagram,facebook",
  breakdowns         = "publisher_platform",
  date_start         = "2019-05-01",
  date_stop          = "2019-05-10")
```

Если вы хотите применить несколько фильтров, то вы можете передать в аргумент `filtering` вектор из выражений, например: `c("clicks LESS_THAN 500", "impressions GREATER_THAN 1000")`.

```{r}
library(rfacebookstat)

options(rfacebookstat.access_token = "ваш токен",
        rfacebookstat.accounts_id  = "act_000000000")
fb_data <- fbGetMarketingStat(
  level              = "campaign",
  fields             = "campaign_name,
                        impressions,
                        clicks,
                        spend,
                        actions",
  filtering          = c("clicks LESS_THAN 500", "impressions GREATER_THAN 1000"),
  date_start         = "2019-05-01",
  date_stop          = "2019-05-10")
```

### Пример фильтрации в JSON формате
Как я уже писал выше вы можете описывать фильтры в виде JSON объектов, но такая запись будет более громоздка. Давайте  приведу вам аналогию с представленными выше фильтрами.

Упрощённый формат: `"impressions LESS_THAN 5000"`

JSON: `"[{"field":"impressions","operator":"LESS_THAN","value":"5000"}]"`

---

Упрощённый формат: `"publisher_platform IN instagram,facebook"`

JSON: `[{"field":"publisher_platform","operator":"IN","value":["instagram","facebook"]}]`

---

Упрощённый формат: `c("clicks LESS_THAN 500", "impressions GREATER_THAN 1000")`

JSON: `[{"field":"clicks","operator":"LESS_THAN","value":"500"},{"field":"impressions","operator":"GREATER_THAN","value":"1000"}]`

## Лимиты API и аргумент request_speed
По использованию аргумента `request_speed` есть целая [статья](https://alexeyseleznev.wordpress.com/2017/12/26/rfacebookstat-1-5-0-%D0%BA%D0%B0%D0%BA-%D0%BF%D1%80%D0%B0%D0%B2%D0%B8%D0%BB%D1%8C%D0%BD%D0%BE-%D0%B8%D1%81%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D1%8C-%D0%B0%D1%80%D0%B3%D1%83%D0%BC/), но я всё же немного опишу зачем данный аргумент нужен.

В API Facebook на данный момент существует 2 уровня доступа к API ([раздел в справке](https://developers.facebook.com/docs/marketing-api/get-started/authorization) API Facebook):

* Разработка - Тестирование приложений с помощью API.
* Стандартный уровень доступа для управления рекламой - Дополнительные ресурсы, например менее строгие ограничения количества обращений, а также возможность принять участие в программе для партнеров Facebook.

По умолчанию все создаваемые вами приложения получают уровень "Разработка". Данный уровень имеет серьёзные ограничения на количество отправляемых в API запросов. Функция `fbGetMarketingStat` при использовании аргумента `interval` равным `"day"` загружает данные по дням, и на каждый день отправляет отдельный запрос в API.

Так же отдельно разделяются запросы если вы загружаете данные сразу по несколько аккаунтам, таким образом если вы планируете загрузить данные с 1 января по 21 января по 3ём аккаунтам функция отправит (31 * 3) 93 запроса к API.

В случае если вы имеете стандартный доступ то для вас это не будет проблемой, и вы можете установить `request_speed = "fast"`, но для приложений с уровнем доступа "Разработка" такой объём отправляемых запросов может выйти далеко за лимиты API, от части `fbGetMarketingStat` умеет обходить такие лимиты каждый раз уходя в бан при их превышении, но скорость загрузки данных при попадании в бан будет очень низкий, иногда бан может составлять 5 минут.

Поэтому если ваше приложение имеет уровень доступа "Разработке" при загрузке данных по дням за длительный период рекомендуется использовать `request_speed = "slow"`. Если значение "slow" не помогает вы можете самостоятельно задавать паузу в секундах между запросами, например `request_speed = 4` будет задавать 4 секундную паузу между отправкой запросов.

Для получения стандартного доступа требуется перейти в [ваше приложение](https://developers.facebook.com/apps/) в раздел настроек API Marketing и отправить заявку на "Ads Management Standart Access".

