index.md

window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'UA-114798296-1');

ul.nm_ul { list-style: none; /*убираем маркеры списка*/ margin: 0; /*убираем отступы*/ padding-left: 0; /*убираем отступы*/ margin-top:25px; /*делаем отступ сверху*/ background:#DCDCDC; /*добавляем фон всему меню*/ height: 30px; /*задаем высоту*/ } a.nm_a { text-decoration: none; /*убираем подчеркивание текста ссылок*/ background:#696969; /*добавляем фон к пункту меню*/ color:#fff; /*меняем цвет ссылок*/ padding:0px 5px; /*добавляем отступ*/ font-family: arial; /*меняем шрифт*/ line-height:30px; /*ровняем меню по вертикали*/ display: block; border-right: 1px solid #677B27; /*добавляем бордюр справа*/ -moz-transition: all 0.3s 0.01s ease; /*делаем плавный переход*/ -o-transition: all 0.3s 0.01s ease; -webkit-transition: all 0.3s 0.01s ease; } a.nm_a:hover { background:#FF8C00;/*добавляем эффект при наведении*/ } li.nm_li { float:left; /*Размещаем список горизонтально для реализации меню*/ position:relative; /*задаем позицию для позиционирования*/ } /*Стили для скрытого выпадающего меню*/ li.nm_li > ul.nm_ul { position:absolute; top:5px; display:none; } /*Делаем скрытую часть видимой*/ li.nm_li:hover > ul.nm_ul { display:block; width:280px; /*Задаем ширину выпадающего меню*/ } li.nm_li:hover > ul.nm_ul > li.nm_li { float:none; /*Убираем горизонтальное позиционирование*/ }

Menu:

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

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

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

function runWfpWdgt(url){var wayforpay=new Wayforpay();wayforpay.invoice(url);}

Оплатить

Ссылки

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 приложения».

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

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

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

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

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

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

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

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

  2. Далее нужно выбрать, из каких рекламных аккаунтов вы будете получать статистику через 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 следующие разрешения: + ads_read - Возможность просматривать отчеты по рекламе в API Ads Insights для ваших собственных рекламных аккаунтов или рекламных аккаунтов, доступ к которым вам предоставили их владельцы посредством этого разрешения. Это разрешение не позволяет обновлять, покупать или изменять рекламу. + ads_management - Возможность просматривать рекламу и управлять ею для собственных рекламных аккаунтов или рекламных аккаунтов, доступ к которым вам дали их владельцы посредством этого разрешения. + business_management - Чтение и запись с помощью API Business Management. + manage_pages - Позволяет 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 )

Аругменты

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

ПолеОписание 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Имя владельца рекламного аккаунта

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_idID рекламного аккаунта. 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_idID группы объявлений. campaign_idID рекламной кампании. account_idID рекламного аккаунта. account_idID рекламного аккаунта. 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)

Аругменты

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

ПолеОписание idИдентификатор креатива. nameНазвание креатива. statusСтатус креатива. url_tagsНабор GET параметров, включая все UTM метки которые добавляются к URL объявления. account_idID рекламного аккаунта. page_idID страницы в Facebook на которое будет перенаправлены пользователи кликнувшие на рекламное объявление. linkURL на который перенапрапралвтся пользователи кликнувшие по объявлению. 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



selesnow/rfacebookstat documentation built on March 30, 2024, 12:43 a.m.