---
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:  <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*.

```{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
   <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
Подробно о приложениях, их регистрации и настройке можно узнать в официальной [справке](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:  <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, и позволяет вам задавать переменные среды. 

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

```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()` вы можете запрашивать список логинов, под которыми вы уже успешно прошли авторизацию, и переключаться между ними.

