rfacebookstat

Загрузка статистики по рекламных кампаниям из Facebook в R.

Project maintained by selesnow Hosted on GitHub Pages — Theme by mattgraham

Menu:


rfacebookstat - Пакет для загрузки данных из Marketing API Facebook в R.

Поддержать проект

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

Ссылки

CRAN

Rdoc rpackages.io rank

Содержание README

Доклад о пакете rfacebookstat с конференции Analyze Lviv 2019

Видео уроки по работе с пакетом rfacebooktat

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

Вы можете сразу перейти к просмотру всего плейлиста на YouTube.

Или же перейти к просмотру интересующего вас урока:

  1. Простая авторизация в Facebook Marketing API
  2. Авторизация в Facebook Marketing API через собственное приложение
  3. Автоматическая авторизация, файл .Renviron
  4. Автоматическая авторизация и создание переменных среды на Windows
  5. Опции пакета и загрузка объектов из рекламных кабинетов Facebook
  6. Загрузка статистики, конверсии и окна атрибуции в Facebook Marketing API

Виньетки с подробной документацией к пакету

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

Начало работы с API Facebook

Для начала работы с API Facebook необходимо создать приложение:

  1. Перейдите в левое меню и в разделе «Разработчик» выберите команду «Управление приложениями».

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

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

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

  1. Перейдите в настройки приложения. Во вкладке «Основное» находится информация по ID и секрету приложения, которая понадобится для работы с API.

На этой вкладке также заполните поля:

Можно указать произвольное название приложение, а остальные поля заполнить как на примере ниже.

  1. В нижней части окна нажмите «Добавить платформу».

Из списка предложенных платформ выберите веб-сайт.

В поле «URL-адрес сайта» введите «https://github.com/selesnow/rfacebookstat» и нажмите «Сохранить изменения».

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

  1. Далее нужно выбрать, из каких рекламных аккаунтов вы будете получать статистику через API и скопировать их ID (Чтобы получить ID аккаунта, перейдите в рекламный кабинет и скопируйте цифры из параметра act в URL.).

Перейдите в раздел «Настройки» —> «Дополнительно» и в блоке «Рекламные аккаунты» нажмите кнопку «API Ads».

В открывшемся окне введите ID выбранных рекламных аккаунтов.

На данном этапе вы получили уровень доступа к API «Development» и можете работать максимум с пятью рекламными аккаунтами. Если вам понадобится полный доступ к API, подробная инструкция находится здесь

Установка пакета rfacebookstat

Для установки пакета запустите приведённый ниже код в RStudio или R консоли. Установка из главного репозитория CRAN:

install.packages("rfacebookstat")

Устновка наиболее актульной dev версии пакета:

if(!"devtools" %in% installed.packages()[,1]){install.packages("devtools")}
devtools::install_github('selesnow/rfacebookstat')

Пример кода для работы с rfacebookstat

# Установка и подключение пакета rfacebookstat
devtools::install_github("selesnow/ryandexdirect")
library(rfacebookstat)

# опции для авторизации
options(rfacebookstat.username = "Ваш логин на FACEBOOK",
        rfacebookstat.token_path = "Путь к папаке где будут храниться учётные данные")

# авторизация в API
fbAuth()

# Загрузка объектов API
# бизнес менеджеры
my_fb_bm   <- fbGetBusinessManagers()

# рекламные аккаунты
my_fb_acc  <- fbGetAdAccounts(source_id = my_fb_bm$id,
                              access_token = fb_token)

# опции для выбора рекламных аккаутов
options(rfacebookstat.accounts_id = c("act_111", 
                                      "act_222", 
				      "act_333"))
# Объекты рекламного аккаунта
# кампании
my_fb_camp <- fbGetCampaigns()

# группы объявлений
my_fb_adsets <- fbGetAdSets()

# объявления
my_fb_ads    <- fbGetAds()

# контент объявлений
my_fb_ad_content <- fbGetAdCreative()

# страницы
my_fb_page <- fbGetPages()

# приложения
my_fb_apps <- fbGetApps()

# рекламируемые видео
my_fb_videos <- fbGetAdVideos()

# список настроенных кастомных конверсий
my_fb_conversions <- fbGetAdAccountsConversions()

# загрузка статистики
my_fb_stats <- fbGetMarketingStat(level = "campaign",
                                  fields = "account_name,campaign_name,impressions,clicks",
                                  breakdowns = "device_platform",
                                  date_start = "2018-08-01",
                                  date_stop = "2018-08-07",
                                  interval = "day")


# управление пользователями
# получить список пользователей
fb_acc_user <- fbGetAdAccountUsers(accounts_id  =  "act_262115113",
                                   console_type = "message")

# удалить пользователя из рекламного аккаунта
fbDeleteAdAccountUsers(user_ids = "823041644481205",
                       accounts_id  =  "act_262115113")

# добавить пользователя в рекламный аккаунт
fb_acc_user2 <- fbGetAdAccountUsers(accounts_id  =  "act_262115113",
                                    console_type = "message")

Безопасность использования rfacebookstat

Вся работа с API Facebook Marketing происходит через зарегистрированное вами приложение. О том, как устроен процесс аутентификации в Facebook Marketing API подробно описано тут.

Для прохождения авторизации в пакете rfacebookstat есть функция fbGetToken, реализуется через одноэтапную аутентификацию. Никакой опасности в том, что ваш токен будет перехвачен через отчёты Google Analytics нет, скрин того, как в Google Analytics выглядит посещение страницы генерации токена.

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

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

ВАЖНО никому не передавайте полученные с помощью пакета rfacebookstat авторизационные токены, т.к. передав токен вы предоставите доступ к управлению вашеми рекламными матеариалами, при этом доступ к аккаунту вы в любом случае не потеряете, но ваши объявления сможет редактировать человек завладевший токеном.

Политика конфиденциальности

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

При авторизации, вы соглашаетесь предоставить пакету rfacebookstat следующие разрешения:

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

Опции пакета rfacebookstat

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

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

Пример установки опций

library(rfacebookstat)

options(rfacebookstat.accounts_id = c("act_111", 
                                      "act_222", 
				      "act_333"))

fbGetSettings()

Переменные среды в пакете rfacebookstat

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

Задать опции можно с помощью специальных утилит вашей операционной системы, файла .Renviron или команды Sys.setenv().

Имена переменных среды в rfacebookstat

Пример установки переменных среды

Sys.setenv(RFB_USER="seleznev_a", 
           RFB_TOKEN_PATH="D:/fb_auth_store")

library(rfacebookstat)
fbGetSettings()

Через переменные среды рекомендуется устанавливать значения пользователя Facebook и путь к папаке с фалом в котором хранятся учётные данные.

Функции пакета rfacebookstat

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

Функция
Описание
fbAuth
Авторизация в API
fbGetSettings
Выводит в консоль текущие настройки пакета
fbGetToken
Получает краткосрочный токен для доступа к API Facebook
fbGetLongTimeToken
Меняет краткосрочный на долгосрочный токен
fbGetBusinessManagers
Загружает список доступных бизнес менеджеров
fbGetAdAccountUsers
Загружает список пользователей из рекламных аккаунтов
fbGetAdAccountUsersPermissions
Загружает список пользователей из рекламных аккаунтов с их привилегиями и ролью, по смыслу очень схожа с fbGetAdAccountUsers
fbUpdateAdAccountUsers
Добавить пользователей в рекламные аккаунты Facebook
fbDeleteAdAccountUsers
Удалить пользователей из рекламных аккаутов в Facebook
fbGetApps
Получает список рекламируемых приложений
fbGetPages
Получает список рекламируемых страниц
fbGetAdVideos
Получает список рекламируемых видео
fbGetAdAccountsConversions
Получает список настроенных в рекламных аккаунтах пользовательских конверсий
fbGetAdAccounts
Получает список доступных рекламных аккаунтов
fbGetCampaigns
Получает список всех рекламных кампаний из рекламного аккаунтов Facebook
fbGetAdSets
Получает список всех групп объявлений из рекламных аккаунтов
fbGetAds
Получает список всех объявлений из рекламных аккаунтов
fbGetAdCreative
Получает список контента всех объявлений из рекламных аккаунтов
fbGetMarketingStat
Получает статистику из рекламного кабинета

Авторизация для доступа к API Facebook

Для работы с функциями пакета rfacebookstat и доступа к API Facebook вам понадобится токет (маркер), получить его можно либо с помощью представленой ниже формы, или функции fbGetToken

Форма для генерации маркера доступа к API Facebook:

ID приложения в Facebook:


fbAuth

Описание:

Авторизация в API Facebook. Если ответить y на вопрос “Do you want save your access token into rds file C:/my_develop_workshop/ppc_report_2/.rfb_auth.rds for use it between R sessions ? то после прохождения процесса авторизации создаёт в указанной папке файл с учётными данными.

Дополнительная документация:

Наиболее подробное описание процесса авторизации, настройки пакета rfacebookstat и то как надо работать с функцией fbAuth() можно найти в виньетке “Авторизация в API facebook”

Аргументы:

fbGetSettings

Описание:

Функция возвращает текущие настройки применённые к пакету rfacebookstat

fbGetToken (Устаревшая функция)

Описание:

Функция предназначена для получения краткосрочного токена для доступа к API Facebook.

Синтаксис:

fbGetToken(app_id = 000000000)

Аргументы:

Пример прохождения процесса аутентификации

MyFBToken <- fbGetToken(app_id = 1111111111111111)

После запуска приведённого выше кода при первом запуске функции наиболее вероятно что вы попадёте на страницу предупреждения:

Пропустите это предупреждение с помощью кнопки «Продолжить как, …».

Далее откроется окно в котором приложение запрос разрешение на доступ к данным.

После того как вы подтвердите доступ, нажав ОК вы попадаете на страницу https://selesnow.github.io/rfacebookstat/getToken/get_token.html, на которой будет сгенерирован токен доступа к API Facebook.

fbGetLongTimeToken (Устаревшая функция)

Описание:

Данная функция меняет краткосрочный токен с сроком 2 часа на долгосрочный токен который действителен на протяжении двух месяцев.

Синтаксис

fbGetLongTimeToken(client_id,client_secret,fb_exchange_token)

Аругменты

fbGetBusinessManagers

Описание

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

Синтаксис

fbGetBusinessManagers(api_version = “v2.10”, access_token = NULL)

Аругменты

fbGetAdAccountUsers

Описание:

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

Синтаксис

fbGetAdAccountUsers(accounts_id = NULL ,api_version = “v2.10”, access_token = NULL)

Аругменты

fbGetAdAccountUsersPermissions

Описание

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

Расшифровка привилегий:
1: ACCOUNT_ADMIN: Имеет права на изменение списка пользователей рекламного аккаунта и привелегий пользователей.
2: ADMANAGER_READ: Имеет права просмотра рекламных кампаний и объявлений.
3: ADMANAGER_WRITE: Имеет права вносить изменения в рекламные аккаунты.
4: BILLING_READ: Право просмотра информации о платежах
5: BILLING_WRITE: Права внесения изменений в платёжные данные
7: REPORTS: Просмотр отчётов
9, 10 - Право подать заявку на некоторые управляемые аккаунты. В настоящее время не требуется для вызовов API маркетинга.

Расшифровка роли
1001 = Администратор
1002 = Рекламодатель
1003 = Аналитик
1004 = Прямой доступ к продажам. Для ограниченных управляемых учетных записей.

Синтаксис

fbUpdateAdAccountUsers(accounts_id = NULL, access_token = NULL)

Аругменты

fbUpdateAdAccountUsers

Описание

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

Синтаксис

fbUpdateAdAccountUsers(user_ids = NULL, role = “advertiser”, accounts_id = NULL, access_token = NULL)

Аругменты

fbDeleteAdAccountUsers

Описание

Удаляет пользователей из рекламных аккаунтов Facebook с определённым набором прав. Для того, что бы удалить пользователей из аккаунта вы должны быть админисратором данного аккаунта.

Синтаксис

fbDeleteAdAccountUsers(user_ids = NULL, accounts_id = NULL, api_version = “v2.12”, access_token = NULL)

Аругменты

fbGetApps

Описание

Данная функция возвращает набор данных со списком аккаунтов в вашем бизнес менеджере.

Синтаксис

fbGetApps(accounts_is, api_version, access_token)

Аругменты

fbGetPages

Описание

Функция возвращает список всех страниц по конкретному проекту бизнес менеджера.

Синтаксис

fbGetPages(accounts_is, api_version, access_token)

Аругменты

fbGetAdAccounts

Описание

Функция возвращает список всех рекламных аккаунтов по конкретному проекту бизнес менеджера.

Синтаксис

fbGetAdAccounts(source_id, api_version, access_token )

Аругменты

Структура возвращаемого дата фрейма

</tr>
Поле
Описание
name
Имя учетной записи. Если имя учетной записи не установлено, будет возвращено имя первого администратора, видимого пользователю.
id
ID рекламного аккаунта с префиксом "act_"
account_id
ЗID рекламного аккаунта
account_status
Статус аккаунта, возможные значения 1 = ACTIVE, 2 = DISABLED, 3 = UNSETTLED, 7 = PENDING_RISK_REVIEW, 9 = IN_GRACE_PERIOD, 100 = PENDING_CLOSURE, 101 = CLOSED, 102 = PENDING_SETTLEMENT, 201 = ANY_ACTIVE, 202 = ANY_CLOSED
amount_spent
Сумма потраченных средств, этот параметр можно сбрасывать в настройках аккаунта
balance
Остаток средств аккаунта
currency
Валюта аккаунта
business_city
Город указанный в настройках бизнес менеджера
business_country_code
Страна указанная в настройках бизнес менеджера
age
Количество дней после активации рекламного аккаунта
spend_cap
Лимит средств который может быть потрачен в рекламном аккаунта, после чего рекламные кампании будут остановлены, если установлено значения 0 то лимита нет.
business.id
ID бизнес менеджера к которому приклеплён аккаунт
business.name
Название бизнес менеджера к которому приклеплён аккаунт
owner.id
ID владельца рекламного аккаунта
owner.name
Имя владельца рекламного аккаунта

fbGetCampaigns

Описание

Функция возвращает список всех рекламных кампаний из рекламного аккаунта Facebook.

Синтаксис

fbGetCampaigns(accounts_id, api_version, access_token)

Аругменты

Структура возвращаемого дата фрейма

Поле
Описание
id
Идентификатор кампании.
name
Название кампании.
created_time
Время создания.
budget_remaining
Оставшийся бюджет.
buying_type
Тип покупки, возможные значения AUCTION (по умолчанию), RESERVED (для объявлений с охватом и частотой)
status
Статус рекламной кампании, возможные значения ACTIVE, PAUSED, DELETED, ARCHIVED, Если этот статус PAUSED, все его активные рекламные блоки и объявления будут приостановлены и будут иметь effective_status CAMPAIGN_PAUSED. Поле возвращает то же значение, что и configure_status.
configured_status
Статус рекламной кампании, возможные значения ACTIVE, PAUSED, DELETED, ARCHIVED, Если этот статус PAUSED, все его активные рекламные блоки и объявления будут приостановлены и будут иметь effective_status CAMPAIGN_PAUSED. Рекомендуется использовать поле status.
account_id
Идентификатор рекламного аккаунта к которому принадлежит данная рекламная кампания.
source_campaign_id
Идентификатор исходной рекламной кампании, из которой была скопирована текущая рекламная кампания.
spend_cap
Лимит бюджета для рекламной кампании.

fbGetAdSets

Описание

Функция возвращает список всех групп объявленйий из рекламного аккаунта Facebook.

Синтаксис

fbGetAdSets(accounts_id, api_version, access_token)

Аругменты

Структура возвращаемого дата фрейма

Поле
Описание
id
Идентификатор группы объявлений.
name
Название группы объявлений.
account_id
ID рекламного аккаунта.
budget_remaining
Оставшийся бюджет.
configured_status
Статус установленный на уровне группы объявлений. Он может отличаться от фактического статуса из-за его родительской кампании. Предпочитаете вместо этого использовать «статус».
effective_status
Статус группы объявлений, который может быть либо его собственным статусом, либо вызван его родительской кампанией.
status
Статус установленый на уровне группы объявлений. Он может отличаться от фактического статуса из-за его родительской кампании. Поле возвращает то же значение, что и 'configure_status'.
created_time
Время создания группы объявлений.
bid_strategy
Стратегия назначения ставок для группы объявления.
pacing_type
Тип показа объявлений, стандартный или планированные показы.

fbGetAds

Описание

Функция возвращает список всех объявленйий из рекламного аккаунта Facebook.

Синтаксис

fbGetAds(accounts_id, api_version, access_token)

Аругменты

Структура возвращаемого дата фрейма

Поле
Описание
id
Идентификатор объявления.
creative_id
Идентификатор креатива который будет использоваться этим объявлением.
adset_id
ID группы объявлений.
campaign_id
ID рекламной кампании.
account_id
ID рекламного аккаунта.
account_id
ID рекламного аккаунта.
bid_amount
Ставка для данного объявления, которая будет использоваться в аукционе.
bid_type
Тип ставки, возможные значения:CPC, CPM, MULTI_PREMIUM, ABSOLUTE_OCPM, CPA.
configured_status
Статус установленный для данного объявления, в данном статусе не учитывается статус родительской группы объявлений или рекламной кампании.
effective_status
Актуальный статус объявления, данный статус учитывает статус родительской группы объявлений и рекламной кампании. Возможные значения: ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, CAMPAIGN_PAUSED, ARCHIVED, ADSET_PAUSED

fbGetAdCreative

Описание

Функция возвращает список контента объявлений из рекламного аккаунта Facebook.

Синтаксис

fbGetAdCreative(accounts_id, api_version, access_token)

Аругменты

Структура возвращаемого дата фрейма

</tr> </tr> </tr> </tr> </tr> </tr> </tr> </tr> </tr> </tr> </tr> </tr> </tr>
Поле
Описание
id
Идентификатор креатива.
name
Название креатива.
status
Статус креатива.
url_tags
Набор GET параметров, включая все UTM метки которые добавляются к URL объявления.
account_id
ID рекламного аккаунта.
page_id
ID страницы в Facebook на которое будет перенаправлены пользователи кликнувшие на рекламное объявление.
link
URL на который перенапрапралвтся пользователи кликнувшие по объявлению.
message
Основной текст объявления.
caption
Подпись к ссылке.
caption
Подпись к ссылке.
attachment_style
Стиль креатива, возможные значения: link, default.
description
Описание.
image_hash
Хеш изображения прикреплённого к объявлению.

fbGetAdVideos

Описание

Функция возвращает список рекламируемых видео из рекламного аккаунта Facebook.

Синтаксис

fbGetAdVideos(accounts_id, api_version, access_token, username, token_path)

Аругменты

fbGetAdAccountsConversions

Описание

Функция возвращает список настроенных в рекламных аккаунтах пользовательских конверсий из рекламного аккаунта Facebook.

Синтаксис

fbGetAdAccountsConversions(accounts_id, api_version, access_token, username, token_path)

Аругменты

fbGetMarketingStat

Описание

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

Дополнительная документация

Работа с данной функцией, и всё её аргументы подробно рассмотренны в виньетке “Загрузки статистики из рекламных аккаунтов Facebook”

Синтаксис

fbGetMarketingStat(accounts_id, sorting, level, breakdowns, action_breakdowns, fields, filtering, date_start, date_stop, interval, console_type, request_speed, api_version, access_token)

Аругменты

Автор пакета: Алексей Селезнёв, Head of Analytics Dept. at Netpeak

Контакты
email: selesnow@gmail.com
skype: selesnow
telegram: @AlexeySeleznev
Facebook Vkontakte Linkedin Blog GitHub Stepic