/rfacebookstat

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

Primary LanguageR

rfacebookstat

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

Содержание README

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

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

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

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

Заполните поля «Отображаемое название приложения»,«Эл. адрес для связи», «Категория» и нажмите «Создайте ID приложения».
  1. Далее вы попадете в меню «Установка и настройка продукта». Кликните на кнопку «Начать» напротив пункта «Вход через Facebook».

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

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

  • «Отображаемое название»;
  • «Домены приложений»;
  • «Эл. адрес для связи»;
  • «URL-адрес политики конфиденциальности»;
  • «URL-адрес Пользовательского соглашения».

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

  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 консоли.

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

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

На данный момент в пакете rfacebookstat доступно 7 функций.

ФункцияОписание
fbGetTokenПолучает окен для доступа к API Facebook
fbGetLongTimeTokenМеняет краткосрочный на долгосрочный токен
fbGetBusinessManagersЗагружает список доступных бизнес менеджеров
fbGetAdAccountUsersЗагружает список пользователей из рекламных аккаунтов
fbGetAppsПолучает список рекламируемых приложений
fbGetPagesПолучает список рекламируемых страниц
fbGetProjectsПолучает список проектов доступных в бизнес менеджере
fbGetAdAccountsПолучает список доступных рекламных аккаунтов
fbGetMarketingStatПолучает статистику из рекламного кабинета

fbGetToken

Описание

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

Синтаксис

fbGetToken(app_id = 000000000)

Аргументы

app_id - ID вашего приложени в Facebook

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

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)

Аругменты

client_id - ID вашего приложени в Facebook

client_secret - Секрет вашего приложения в Facebook

fb_exchange_token - Значение краткосрочного токена полученного с помощью функции fbGetToken

fbGetBusinessManagers

Описание

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

Синтаксис

fbGetBusinessManagers(api_version = "v2.10", access_token = NULL)

Аругменты

api_version - Версия API Facebook в формате v*.*, например v2.10

access_token - Токен достепа полученный с помощью функции fbGetToken или fbGetLongTimeTokenn

fbGetAdAccountUsers

Описание

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

Синтаксис

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

Аругменты

accounts_id - Вектор ID рекламных аккаунтов с префиксом act_, получить список всех доступны рекламных аккаунтов можно с помощью функции fbGetAdAccounts

api_version - Версия API Facebook в формате v*.*, например v2.10

access_token - Токен достепа полученный с помощью функции fbGetToken или fbGetLongTimeTokenn

fbGetProjects

Описание

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

Синтаксис

fbGetProjects(bussiness_id, api_version, access_token)

Аругменты

bussiness_id - ID вашего бизнес менеджера, посмотреть ID можно перейдя в основном меню бизнес менеджера в "Настройки Business Manager" на вкладку "Информация о компании".

api_version - Версия API Facebook в формате v*.*, например v2.8

access_token - Токен достепа полученный с помощью функции fbGetToken или fbGetLongTimeToken

fbGetApps

Описание

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

Синтаксис

fbGetApps(projects_id, api_version, access_token)

Аругменты

projects_id - ID проекта в котором ведётся реклама приложени, список ID всех доступных вам проектов можно получить с помощью функции fbGetProjects

api_version - Версия API Facebook в формате v*.*, например v2.8

access_token - Токен достепа полученный с помощью функции fbGetToken или fbGetLongTimeToken

fbGetPages

Описание

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

Синтаксис

fbGetPages(projects_id, api_version, access_token)

Аругменты

projects_id - ID проекта в котором ведётся реклама приложени, список ID всех доступных вам проектов можно получить с помощью функции fbGetProjects

api_version - Версия API Facebook в формате v*.*, например v2.8

access_token - Токен достепа полученный с помощью функции fbGetToken или fbGetLongTimeToken

fbGetAdAccounts

Описание

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

Синтаксис

fbGetAdAccounts(source_id, api_version, access_token )

Аругменты

source_id - ID проекта или бизнес менеджера в котором ведётся реклама приложени, список ID всех доступных вам проектов можно получить с помощью функции fbGetProjects, если не указать никакое значение в аргументе source_id функция вернёт список всех доступных вам рекламных аккаунтов.

api_version - Версия API Facebook в формате v*.*, например v2.8

access_token - Токен достепа полученный с помощью функции fbGetToken или fbGetLongTimeToken

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

ПолеОписание
nameИмя учетной записи. Если имя учетной записи не установлено, будет возвращено имя первого администратора, видимого пользователю.
idID рекламного аккаунта с префиксом "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.idID бизнес менеджера к которому приклеплён аккаунт
business.nameНазвание бизнес менеджера к которому приклеплён аккаунт
owner.idID владельца рекламного аккаунта
owner.nameИмя владельца рекламного аккаунта

fbGetMarketingStat

Описание

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

Синтаксис

fbGetMarketingStat(accounts_id, sortingL, level, breakdowns, fields, filtering, date_start, date_stop, api_version, access_token)

Аругменты

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

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

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

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

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 = "[{'field':'publisher_platform','operator':'IN','value':['instagram']}]

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

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

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

api_version — версия API Facebook, в формате v*.*, например "v2.8"

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

Пример работы с пакетом rfacebookstat

Перед тем как запускать описанные ниже примеры, необходимо получить API-токен и сохраните его в объект token. token <- fbGetToken(app_id = 00000000000000)

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

AccStat <- fbGetMarketingStat(accounts_id = «act_0000000000»,
                              level = "account",
                              fields = "account_id,account_name,impressions,clicks,spend",
                              breakdowns = "region",
                              date_start = "2016-11-01",
                              date_stop = "2016-11-30",
                              api_version = "v2.8",
                              access_token = token)

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

CampStat <-     fbGetMarketingStat(accounts_id = "act_0000000000",
                                   level = "campaign",
                                   fields = "campaign_name,unique_impressions,unique_clicks",
                                   breakdowns = "age",
                                   sorting = "unique_impressions_descending",
                                   filtering = "[{'field':'age','operator':'IN','value':['18-24','25-34']}]",
                                   date_start = "2016-10-01",
                                   date_stop = "2016-10-10",
                                   api_version = "v2.8",
                                   access_token = token)

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

Контакты: