Как загрузить статистику рекламных кампаний из API Facebook с помощью языка R

Популярность Facebook как рекламной площадки стремительно растет, но анализировать статистику в рекламном кабинете неудобно. Один из альтернативных способов — загрузить статистику в R и визуализировать ее. В этой статье я подробно расскажу, как получить данные из API Facebook и работать с ними в R.

Я написал ряд функций для работы с API Facebook и их собрал в пакет rfacebookstat, доступный на GitHub и CRAN.

1. Создайте приложение в Facebook

1.1. Чтобы начать работу с API Facebook, нужно создать новое приложение. Для этого перейдите по этой ссылке, или найдите пункт «Управление приложениями» в левом меню.

1.2. В кабинете разработчика нажмите кнопку «+ Добавить новое приложение».

Заполните поля «Отображаемое название приложения»,«Эл. адрес для связи», «Категория» и нажмите «Создайте ID приложения».

1.3. Далее вы попадете в меню «Установка и настройка продукта». Кликните на кнопку «Начать» напротив пункта «Вход через Facebook».

1.4. Выберите платформу веб.

1.5. Вводим https://selesnow.github.io в поле «URL сайта» и жмём Save — Продолжить — Далее...

1.6. В меню приложения перейдите в раздел «Вход через Facebook». В поле «Действительные URL-адреса для перенаправления OAuth» введите «https://selesnow.github.io/rfacebookstat/getToken/get_token.html».

1.7. Подключаем ещё один продукт — «API Marketing»

На этом создание и настройка приложения завершены. Перейдите в меню Настройка — Основное и скопируйте идентификатор и секрет приложения.

Эти данные нам понадобятся для авторизации.

Важно: многие ошибочно выводят своё приложения из статуса «В разработке», и при попытке авторизации получают ошибку, так как для публикации приложения необходимо пройти серьёзные проверки со стороны Facebook. К счастью, если вы регистрируете приложение для своих личных нужд то выводить его из разработки не требуется.

2. Установите пакет rfacebookstat

Пакет rfacebookstat доступен для установки из CRAN и GitHub.

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

install.packages("rfacebookstat")

2.2. Подключите пакет rfacebookstat.

Пакет можно рассматривать как отдельное программное обеспечение, поэтому, как и любую программу его необходимо сначала установить, и при каждой необходимости - запускать. В R подключение пакетов осуществляется функцией library().

library(rfacebookstat)

3. Получите токен для работы с API Facebook

Для начала работы с API Facebook осталось пройти авторизацию. Воспользуйтесь функцией fbAuth() в пакете rfacebookstat.

3.1. На вкладке «Настройки» —> «Основное» скопируйте ID и секрет вашего приложения и введите их в соответствующие аргументы функций.

fbAuth(app_id     = 00000000000000,      app_secret = "xxxxxxxxxxxxx",       username   = "ваш логин")

В аргумент username передайте ваш логин на Facebook.

3.2. Возможно, впервые получая токен, вы попадете на страницу с предупреждением, что некоторые разрешения еще не одобрены для использования Facebook. Пропустите это предупреждение с помощью кнопки «Продолжить как, ...».

Подтвердите вход через Facebook.

Далее вы будете перенаправлены на страницу сайта моих пакетов https://selesnow.github.io, где для вас будет сгенерирован краткосрочный авторизационный токен. 

В своё время меня часто спрашивали о безопасности использования разработанных мной пакетов. Многих беспокоил именно процесс авторизации через мой сайт. Поэтому я написал о безопасности использования пакетов подробную статью  «Насколько безопасно использовать R пакеты для работы с API рекламных систем».

Если у вас включён JavaScript, то токен автоматически будет скопирован в буфер обмена,  и через 30 секунд вы будете перенаправлены на страницу с официальной справкой к пакету. Если вы отключили выполнение JavaScript, то самостоятельно скопируйте токен.

3.3. Полученный токен необходимо ввести в R консоль.

3.4. Далее ваш краткосрочный токен автоматически будет заменён на долгосрочный, и вы увидите в консоли сообщение: 

Token changed to long time successfully
Do you want save your access token into rds file 
C:/Users/Username/Documents/blog_login.rfb_auth.rds 
for use it between R sessions ? y / n (recmedation y) ?:

Первая строка сообщения говорит о том, что ваш краткосрочный токен был успешно заменён долгосрочным токеном. После, пакет спрашивает вас, хотите ли вы сохранить полученные учётные данные, что бы использовать в разных сессиях работы в R. Я крайне рекомендую вам отвечать на этот вопрос y, это избавить вас от необходимости постоянно проходить авторизацию через браузер.

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

fbGetAdAccounts(username = "ваш логин")

Если вы получите список аккаунтов – значит авторизация пройдена успешно, если получите ошибку — то скорее всего вы неправильно настроили приложение.

4. Получите статистику по рекламным аккаунтам в Facebook

Мы завершили подготовительный этап и можем перейти непосредственно к импорту данных.

Основная функция пакета rfacebookstat — fbGetMarketingStat(). Рассмотрим подробнее работу с этой функцией, потому что с ее помощью можно получить любые данные об эффективности рекламного аккаунта.

4.1. Синтаксис

В приведённом выше коде представлены значения большинства аргументов функции fbGetMarketingStat() принятые по умолчанию.

4.2. Аргументы функции

4.2.1. accounts_id — ID рекламного аккаунта. Это обязательный аргумент. Вы можете получить его из URL, если перейдете в нужный рекламный аккаунт Facebook.

Так как указывать id рекламного аккаунта вам необходимо при каждом обращении к API, вы можете избежать дублирования этой информации, передав в начале скрипта список нужных аккаунтов в опцию rfacebookstat.accounts_id.

options( rfacebookstat.accounts_id = c("47725506", "361373151") )

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

4.2.2. sorting — cортировка данных. Необязательный аргумент. На входе принимает список полей и направление сортировки (по возрастанию или по убыванию). Пример: reach_descending, impressions_ascending.

4.2.3. level — основной уровень детализации данных. Обязательный аргумент. Принимает значения ad, adset, campaign, account. Пример — level = "account".

4.2.4. fields — список полей, по которым вы планируете получить данные. Обязательный аргумент. Пример: fields = "account_id,account_name,campaign_name,impressions,unique_impressions,clicks,unique_clicks,reach,spend".

Список доступных полей в версии API 2.8. смотрите в таблице ниже или официальной документации.

4.2.5. breakdowns — аргумент, с помощью которого можно получить данные в разбивке на различные сегменты. Можно разбивать информацию по следующим срезам:

• age;
• country;
• gender;
• frequency_value;
• hourly_stats_aggregated_by_advertiser_time_zone;
• hourly_stats_aggregated_by_audience_time_zone;
• impression_device;
• place_page_id;
• placement;
• device_platform;
• product_id;
• region;
• actions;
• publisher_platform;
• platform_position;
• impression_device.

В одном запросе можно комбинировать несколько срезов. На данный момент доступны следующие комбинации:

• action_type *;
• action_target_id *;
• action_device *;
• action_device, placement *;
• action_device, placement, 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 *;
• placement *;
• placement, impression_device *;
• publisher_platform *;
• publisher_platform, impression_device *;
• publisher_platform, platform_position *;
• publisher_platform, platform_position, impression_device *;
• product_id *;
• hourly_stats_aggregated_by_advertiser_time_zone *;
• hourly_stats_aggregated_by_audience_time_zone *;
• action_carousel_card_id / action_carousel_card_name;
• action_carousel_card_id / action_carousel_card_name, placement;
• action_carousel_card_id / action_carousel_card_name, placement, impression_device;
• action_carousel_card_id / action_carousel_card_name, country;
• action_carousel_card_id / action_carousel_card_name, age;
• action_carousel_card_id / action_carousel_card_name, gender;
• action_carousel_card_id / action_carousel_card_name, age, gender.

Пример: breakdowns = "region"

4.2.6. filtering — фильтр данных. Необязательный аргумент. Фильтры задаются в виде JSON объектов «ключ:значение». Необходимо прописать три свойства:

• field — поле, по которому будет осуществляться фильтрация;
• operator — оператор логического значения ('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', 'ANY', 'ALL', 'NONE');
• value — значения, по которому будет фильтроваться указанное поле.

Пример:   filtering = "impressions LESS_THAN 5000"

4.2.7. date_start — начальная дата отчетного периода в формате YYYY-MM-DDD.

4.2.8. date_stop — конечная дата отчетного периода в формате YYYY-MM-DDD.

4.2.9. api_version — версия API Facebook.

4.2.10. access_token — токен доступа.

5. Примеры использования функции fbGetMarketingStat

5.1. Перед тем как запускать описанные ниже примеры, сгенерируйте API-токен и сохраните его в виде файла, с помощью функции fbAuth().

fbAuth(app_id     = 00000000000000,       app_secret = "xxxxxxxxxxxxx",        username   = "ваш логин")

5.2. Чтобы получить статистику о количестве показов, кликов и затрат на рекламу на уровне аккаунта и в  разрезе регионов, введите следующий код:

AccStat <- fbGetMarketingStat(                       
accounts_id = «act_0000000000»,                      
level = "account",                      
fields = "account_id,                                
account_name,                                
impressions,                                
clicks,                                spend",                      
breakdowns = "region",                      
date_start = "2020-03-01",                      
date_stop = "2020-03-30",                      
username   = "ваш логин")

5.3. Получите статистику по количеству уникальных показов и уникальных кликов, с фильтром по возрастным группам «18-24», «25-34» и сортировкой данных в порядке убывания количества уникальных показов (поле reach).

CampStat <-     fbGetMarketingStat(accounts_id = "act_0000000000",                          
level = "campaign",                          
fields = "campaign_name,                                    
reach,                                    
unique_clicks",                          
breakdowns = "age",                          
sorting = "reach_descending",                          
filtering  = "age IN 18-24,25-34",                          
date_start = "2020-03-01",                          
date_stop  = "2020-03-30",                          
username   = "ваш логин")

6. Официальные учебные материалы

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

Официальные ссылки:

1. Виньетки:

• авторизация в API facebook;
• загрузки статистики из рекламных аккаунтов Facebook;

• Страница документации.
• Плейлист с видеоуроками.
• Страница пакета на CRAN.
• Страница проекта на GitHub.

Выводы

Используя API Facebook и пакет функций на языке R rfacebookstat, вы сможете:

• получить данные по своим рекламным аккаунтам, кампаниям, объявлениям и так далее во множестве различных разрезов.
• строить на основе полученных данных любые визуализации, используя всю мощь языка R.
• передавать полученные данные в любую базу данных или сохранять в виде CSV-файла.

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

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