In selesnow/rfacebookstat: Load Data from Facebook API Marketing

knitr::opts_chunk$set(
  eval=FALSE,
  collapse = TRUE,
  comment = "#>"
)

library(rfacebookstat)

Для начала работы с Facebook Marketing API предварительно требуется пройти процесс авторизации. В пакете rfacebookstat есть несколько вариантов авторизации:

• Простейшая авторизация с использованием приложения по умолчанию;
• Авторизация через собственное приложение.

Простейшая авторизация

Наиболее быстрый и простой способ пройти авторизацию и получить маркер для работы с API Facebook - использовать приложение вшитое в пакет rfacebookstat. Для этого вам достаточно использовать функцию fbAuth().

library(rfacebookstat)

fbAuth()

После запуска функции fbAuth() вы будете перенаправлены в браузер для подтверждения разрешения пакету rfacebookstat доступа к вашим рекламным кабинетам. Далее вы будете перенаправлены на другую страницу, где для вас будет сгенерирован краткосрочный маркер доступа к API. Его необходимо скопировать и вставить в консоль RStudio в качестве ответа на запрос "Enter your token:".

Полученный ранее краткосрочный токен будет изменён на долгосрочный, о чём вы узнаете из сообщения "Token changed to long time successfully" в консоли RStudio.

У вас есть возможно сохранить полученные данные в файл, для того, что бы в следующий раз не было необходимости проходить авторизации через браузер. Для этого ответьте y или yes на вопрос "Do you want save your access token into rds file C:/my_develop_workshop/ppc_report_2/selesnow.rfb_auth.rds for use it between R sessions ?", который вы увидите в консоли RStudio.

Если вы сделали всё согласно инструкции, то вы увидите сообщение "Token saved in C:/facebook/credentials/.rfb_auth.rds", которое говорит о том, что вы успешно получили и сохранили учётные данные необходимые для работы с Facebook Narketing API.

Также в консоль будет выведена некоторая информация о ваших учётных данных.

 Facebook access token
 Access token:  <hidden> 
 App id:        176943372709235 
 App name:      rfbstat 
 User id:       1246563312029308 
 User name:     Алексей Селезнёв 
 Expires at:    never

Из этого сообщения вы можете узнать id и название приложения которому вы предоставили разрешение на доступ к данным, id и имя пользователя под которым вы прошли авторизацию, а также дату до которой будет действителен полученный вами маркер доступа, never означает что вы получили бессрочный токен.

В поле Access token должен отображаться ваш маркер, но по умолчанию он не выводится в консоль, если вы работаете под Windows, то каждый раз когда вы будете выводить на печать объект полученный с помощью функции fbAuth() ваш маркер доступа автоматически будет передан в буфер обмена.

Если вам необходимо вывести в консоль полученный маркер, то это можно сделать с помощью функции print() с использованием аргумента show_token.

print(fbAuth(), show_token = T)

 Facebook access token
 Access token:  EAACg7dbg.................... 
 App id:        176943372709235 
 App name:      rfbstat 
 User id:       1246563312029308 
 User name:     Алексей Селезнёв 
 Expires at:    never

Теперь можно выполнить первый вызов к Facebook Marketing API. Например вы можете запросить список рекламным аккаунтам к которым у вас есть доступ с помощью функции fbGetAdAccounts().

fbGetAdAccounts()

Token load from C:/facebook/credentials/.rfb_auth.rds
# A tibble: 420 x 10
   id    name  account_id account_status amount_spent balance business_name currency owner
   <chr> <chr> <chr>               <int> <chr>        <chr>   <chr>         <chr>    <chr>
 1 act_~ 4772~ 47725506                1 9177567      2272    DEMOBAZA Ltd. EUR      7445~
 2 act_~ capp~ 14794670                1 2787098      0       ""            AED      2642~
 3 act_~ Rual~ 67398193                1 3681338      4825    Rual Travel ~ USD      2357~
 4 act_~ Plas~ 66869331                1 6355231      3069    Plasico Comp~ USD      8519~
 5 act_~ Maxi~ 77890760                1 2101480      426     Maxi.az       USD      1910~
 6 act_~ heal~ 171226248               1 3653879      0       Нетпик ЕООД   USD      3689~
 7 act_~ Tric~ 363293104               1 81285        0       ""            USD      5031~
 8 act_~ Spor~ 361373151               1 1424069      2053    Соларшоп ЕООД EUR      2201~
 9 act_~ Netp~ 262115113               1 7393426      2615    Netpeak       USD      9055~
10 act_~ Nata~ 362381897               1 6207085      6290    ""            USD      1950~
# ... with 410 more rows, and 1 more variable: user_role <chr>

Это действительно самый простой способ авторизации, но у API Facebook очень быстро меняются требования к приложениям в связи с чем, приложение которое вшито в rfacebookstat может быть недоступно для авторизации пользователям, если вы столкнулись с такой ошибкой то вы можете создать собственное приложение и пройти авторизацию через него.

Авторизация с использованием собственного приложения

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

Создание и настройка собственного приложения для авторизации в Facebook API

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

Для создания своего приложения необходимо выполнить следующие действия:

1. Перейти на страниц приложений.
2. Нажать кнопку "Добавьте новое приложение".
3. В появившемся диалоговом окне ввести название приложения и ваш email, и нажать "Создать ID приложения".
4. Далее в панели приложение добавьте продукт "Вход через Facebook", нажав на нём кнопку "Настроить"
5. Выберите из предложенных платформ "Веб".
6. В блоке "Укажите URL вашего сайта" введите https://selesnow.github.io, и нажмите "Save", а затем "Продолжить" > "Далее" > "Далее" > "Далее".
7. В меню вашего приложения в области "Продукты" вы увидите "Вход через Faceook", перейдите в раздел настройки.

1. В настройках найдите "Действительные URI перенаправления для OAuth" и введите следующий URL: https://selesnow.github.io/rfacebookstat/getToken/get_token.html
2. В нижней части экрана настройки "Вход через Facebook" нажмите "Сохранить изменения".
3. В основном меню приложения перейдите в раздел "Панель".
4. В окне "Панель" спуститесь в область "Добавьте продукты" и нажмите в продукте "API Marketing" кнопку "настроить".
5. Теперь можете вернуться в основном меню приложения в раздел Настройки > Основное.
6. В разделе Настройки > Основное вы найдёте Идентификатор приложения и секрет приложения, далее вы будете использовать эти параметры для авторизации через собственное приложение.

Важно! Не выводите своё приложение из статуса "в разработке", т.к. для этого требуется проверка приложения со стороны поддержки API Facebook, процесс проверки длительный и сложный. Но вы можете работать со своими рекламными кампаниями даже если ваше приложение имеет статус "в разработке"

Аргументы функции fbAuth()

• app_id - Идентификатор приложения
• app_secret - Секрет приложения
• username - Ваш логин на Facebook
• token_path - Путь к папке в которой вы хотите создать файл для хранения учётных данных
• reauth - Переавторизоваться под указанным в username пользователем, если вы уже ранее запрашивали для него учётные данные
• skip_option - Игнорировать опции и переменные окружения при авторизации (будет рассмотрено ниже)

Соответственно авторизоваться с помощью собственного приложения можно передав в аргументы app_id и app_secret идентификатор и секрет созданного вами приложения.

fbAuth(app_id      = 556970798471513, 
       app_secret  = "10fbc64e0c426feb4e774395c97237fa",
       username    = "seleznev_a",
       skip_option = TRUE, 
       reauth      = FALSE,
       token_path  = "D:/fb_auth_store")

 Facebook access token
 Access token:  <hidden> 
 App id:        556970798471513 
 App name:      MyAPP 
 User id:       2834875706531386 
 User name:     Алексей Селезнёв 
 Expires at:    2019-12-31 09:32:15

При авторизации через собственное приложение с минимальным уровнем доступа к API срок действия вашего токена будет ограничен. В сообщение приведённом выше видно, что полученный токен действителен до 31 декабря 2019 года 09:32:15.

На самом деле пакет rfacebookstat сам автоматически будет продлевать ваш токен по мере необходимости в случае если до завершена срока действия остаётся менее 10 дней.

Автоматическая авторизация

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

Переменные среды

Это наиболее удобный способ работы с учётными данными в rfacebookstat, к тому же его преимущество заключается в том, что не будет необходимости хранить ваш токен в виде текстовой строки в скрипте.

Создать переменные среды можно несколькими способами:

1. Прописать их в файл .Renviron;
2. Настроить переменные окружения (для пользователей Windows):
3. Задать в начале скрипта с помощью команды Sys.setenv().

Настройка переменных среды через файл .Renviron

Файл .Renviron в домашнем каталоге R, и позволяет вам задавать переменные среды.

Для начала необходимо найти домашний каталог:

path.expand("~")

[1] "C:/Users/username/Documents"

Обычно это папка с вашими документами, как и в моём примере. Далее вам необходимо создать в этой папке файл .Renviron. И прописать в нём значение некоторых переменных, которые используются в rfacebookstat:

• RFB_TOKEN_PATH - Путь к папке в которой у вас хранится файл с раширением .rfb_auth.rds, в котором хранятся учётные данные.
• RFB_USER - Имя пользователя Facebook, который вы указали в аргументе username при прохождении авторизации с помощью функции fbAuth().
• RFB_API_TOKEN - Полученный с помощью функции fbAuth() токен доступа к API.

На самом деле указывать все три переменные не имеет смысла, наибольший приоритет имеет переменная RFB_API_TOKEN. Если она указана то остальные две переменные игнорируются. Но использовать эту переменную имеет смысл только если вы получили бессрочный токен доступа, т.к. пакет не может обновить переменную среды, и если токен имеет срок действия по его истечению вы получите ошибку.

В случае если вы прошли авторизацию через собственное приложение, и получили токен с ограниченным сроком действия, следует использовать переменные RFB_TOKEN_PATH и RFB_USER. Указав имя пользователя и путь к папке в которую был сохранён файл с учётными данными в процессе авторизации через функцию fbAuth(), при авторизации вы можете указать папку с помощью аргумента token_path. По умолчанию файл сохраняется в рабочей директории на момент прохождения авторизации.

Т.е. у вы можете настроить файл .Renviron одним из двух вариантов.

RFB_API_TOKEN="abcdef788dsydsy9dcy"

Где abcdef788dsydsy9dcy ваш токен для работы с Facebook API.

Либо:

RFB_USER="seleznev_a"
RFB_TOKEN_PATH="D:/fb_auth_store"

Настройка переменных среды в Windows

В Windows можно создать переменные среды следующем способом:

1. В строке "Поиск" выполните поиск: Система (Панель управления)
2. Нажмите на ссылку Дополнительные параметры системы.
3. Нажмите Переменные среды.
4. Нажмите кнопку "Создать..."
5. Создайте нужные вам переменные, перечисленные в прошлом пункте.

Задать в начале скрипта с помощью команды

Ещё один способ, до подключения пакета rfacebookstat в скрипте задать переменные с помощью функции Sys.setenv().

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

library(rfacebookstat)

Как определить что вы успешно установили переменные среды

Если вы правильно определили переменные среды при подключении пакета в приветственном сообщении вы увидите отметку 'success' напротив успешно установленных переменных. Например если вы установили имя пользователя и путь к папке то вы увидите следующее сообщение:

rfacebookstat presets:
...Set rfacebookstat token_path: success
...Set rfacebookstat username: success
...Set rfacebookstat access_token: none
...Set Facebook Marketing API Version: v5.0

Опции

Ещё один вариант инициализации учётных данных задать их с помощью опций. Также опции позволяют избежать дублирования аргументов без необходимости. Все опции вы можете задать в начале скрипта после подключения пакета. В rfacebookstat доступны следующие опции:

• rfacebookstat.api_version - Версия API к которой пакет будет направлять запросы, не рекомендуется изменять эту опцию;
• rfacebookstat.access_token - Ваш токен доступа, также не рекомендуется хранить его текстом в ваших скриптах;
• rfacebookstat.accounts_id - ID аккаунтов которые вы используете в скрипте по умолчанию, можно задавать вектором;
• rfacebookstat.business_id - ID бизнес менеджера который вы планируете использовать в скрипте по умолчанию
• rfacebookstat.token_path - Путь к папке, где хранятся файлы с учётными данными;
• rfacebookstat.username - Имя пользователя facebook;
• rfacebookstat.app_id - ID созданного вами приложения в Facebook для авторизации;
• rfacebookstat.app_secret - Секрет созданного вами приложения в Facebook.

Пример использования опций:

library(rfacebookstat)

options(rfacebookstat.username = "seleznev_a",
        rfacebookstat.token_path = ""D:/fb_auth_store")

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

Так же для установки опций в пакете реализован набор функций с префиксом fbSet*().

• fbSetUsername(username) - установка имя пользователя
• fbSetAccount(accounts_ids) - установка идентификатор аккаунтов
• fbSetBusinessId(business_ids) - установка идентификаторов бизнес менеджеров
• fbSetTokenPath(token_path) - установка пути к папке для работы с токенами
• fbSetApiVersion(api_version) - установка версии API

Приоритет переменных для авторизации

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

1. Заданные в функции аргументы;
2. Опции;
3. Переменные среды.

Соответственно аргументы функции имеют максимальный приоритет.

Рекомендации

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

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

Данный подход избавит вас от избыточности и дублирование в коде.

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

С помощью функции fbGetLogins() вы можете запрашивать список логинов, под которыми вы уже успешно прошли авторизацию, и переключаться между ними.

selesnow/rfacebookstat documentation built on Feb. 22, 2025, 5:21 a.m.