--- title: "1. API facebook Authorization" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{1. API facebook Authorization} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( eval=FALSE, collapse = TRUE, comment = "#>" ) ``` ```{r setup} library(rfacebookstat) ``` Для начала работы с Facebook Marketing API предварительно требуется пройти процесс авторизации. В пакете `rfacebookstat` есть несколько вариантов авторизации: * Простейшая авторизация с использованием приложения по умолчанию; * Авторизация через собственное приложение. # Простейшая авторизация Наиболее быстрый и простой способ пройти авторизацию и получить маркер для работы с API Facebook - использовать приложение вшитое в пакет `rfacebookstat`. Для этого вам достаточно использовать функцию `fbAuth()`. ```{r} 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: App id: 176943372709235 App name: rfbstat User id: 1246563312029308 User name: Алексей Селезнёв Expires at: never ``` Из этого сообщения вы можете узнать id и название приложения которому вы предоставили разрешение на доступ к данным, id и имя пользователя под которым вы прошли авторизацию, а также дату до которой будет действителен полученный вами маркер доступа, never означает что вы получили бессрочный токен. В поле *Access token* должен отображаться ваш маркер, но по умолчанию он не выводится в консоль, если вы работаете под Windows, то каждый раз когда вы будете выводить на печать объект полученный с помощью функции `fbAuth()` ваш маркер доступа автоматически будет передан в буфер обмена. Если вам необходимо вывести в консоль полученный маркер, то это можно сделать с помощью функции `print()` с использованием аргумента *show_token*. ```{r} 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()`. ```{r} 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 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 ``` Это действительно самый простой способ авторизации, но у API Facebook очень быстро меняются требования к приложениям в связи с чем, приложение которое вшито в `rfacebookstat` может быть недоступно для авторизации пользователям, если вы столкнулись с такой ошибкой то вы можете создать собственное приложение и пройти авторизацию через него. # Авторизация с использованием собственного приложения Функция `fbAuth()` по умолчанию использует встроенное приложение, но при необходимости вы можете создать собственное приложение и пройти процесс авторизации через него. ## Создание и настройка собственного приложения для авторизации в Facebook API Подробно о приложениях, их регистрации и настройке можно узнать в официальной [справке](https://developers.facebook.com/docs/development). Для создания своего приложения необходимо выполнить следующие действия: 1. Перейти на [страниц приложений](https://developers.facebook.com/apps/). 2. Нажать кнопку "Добавьте новое приложение". 3. В появившемся диалоговом окне ввести название приложения и ваш email, и нажать "Создать ID приложения". 4. Далее в панели приложение добавьте продукт "Вход через Facebook", нажав на нём кнопку "Настроить" 5. Выберите из предложенных платформ "Веб". 6. В блоке "Укажите URL вашего сайта" введите https://selesnow.github.io, и нажмите "Save", а затем "Продолжить" > "Далее" > "Далее" > "Далее". 7. В меню вашего приложения в области "Продукты" вы увидите "Вход через Faceook", перейдите в раздел настройки. ![Настройки Вход через Facebook](http://img.netpeak.ua/alsey/157259948210_kiss_9kb.png) 8. В настройках найдите "Действительные URI перенаправления для OAuth" и введите следующий URL: https://selesnow.github.io/rfacebookstat/getToken/get_token.html 9. В нижней части экрана настройки "Вход через Facebook" нажмите "Сохранить изменения". 10. В основном меню приложения перейдите в раздел "Панель". 11. В окне "Панель" спуститесь в область "Добавьте продукты" и нажмите в продукте "API Marketing" кнопку "настроить". 12. Теперь можете вернуться в основном меню приложения в раздел Настройки > Основное. 13. В разделе Настройки > Основное вы найдёте Идентификатор приложения и секрет приложения, далее вы будете использовать эти параметры для авторизации через собственное приложение. **Важно! Не выводите своё приложение из статуса "в разработке", т.к. для этого требуется проверка приложения со стороны поддержки API Facebook, процесс проверки длительный и сложный. Но вы можете работать со своими рекламными кампаниями даже если ваше приложение имеет статус "в разработке"** ## Аргументы функции `fbAuth()` * app_id - Идентификатор приложения * app_secret - Секрет приложения * username - Ваш логин на Facebook * token_path - Путь к папке в которой вы хотите создать файл для хранения учётных данных * reauth - Переавторизоваться под указанным в username пользователем, если вы уже ранее запрашивали для него учётные данные * skip_option - Игнорировать опции и переменные окружения при авторизации (будет рассмотрено ниже) Соответственно авторизоваться с помощью собственного приложения можно передав в аргументы *app_id* и *app_secret* идентификатор и секрет созданного вами приложения. ```{r} 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: 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, и позволяет вам задавать переменные среды. Для начала необходимо найти домашний каталог: ```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. Создайте нужные вам переменные, перечисленные в прошлом пункте. ![Переменная среды в Windows](http://img.netpeak.ua/alsey/157625864454_kiss_4kb.png) ### Задать в начале скрипта с помощью команды Ещё один способ, до подключения пакета `rfacebookstat` в скрипте задать переменные с помощью функции `Sys.setenv()`. ```r 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()` вы можете запрашивать список логинов, под которыми вы уже успешно прошли авторизацию, и переключаться между ними.