rfacebookstat 2.0.0

Это пожалуй самое обновление за всю историю существования пакета rfacebookstat.

Синтаксис пакета стал значительно лаконичнее за счёт опций и переменных среды, процесс авторизации стал удобней.

Подробности релиза rfacebookstat 2.0.0

• Новые функции

  • fbAuth() - Новая функция авторизации, подробности в разеле Авторизация.
  • fbGetUserAdAccounts() - Загрузка списка аккаунтов к которым есть доступ у определённого пользователя facebook.
  • fbGetAdAccountsConversions() - Получить список конвесий настроенных в рекламной аккаунте.
  • fbGetAdVideos() - Загрузка списка видео из рекламного аккаунта
  • fbGetSettings() - Вывести в консоль все применённые в пакете настройки.

• Доработанные функции

  • В функцию fbGetMarketingStat() добавлен аргумент attribution_window с помощью которого вы можете запрашивать поле actions и применять к нему различные окна атрибуции.
  • Так же был полностью переписан процесс разворачивания вложенных полей типа actions, и прочих. Теперь функция fbGetMarketingStat() работает с ними более стабильно.
  • Изменения в функциях fbGetApps() и fbGetPages() теперь вы можете запрашивать список продвигаемых страниц и приложений непосредственно из рекламных аккаунтов.
    • Теперь вы можете запрашивать список страниц и приложений из конкретного аккаунта, используя аргумент accounts_id. Это новый аргумент который был добавлен вместо устаревшего projects_id.
    • В обеих функциях значительно расширен список полей которые они возвращают.
  • В большинстве функций аргумент accounts_id больше не является обязательным, и по умолчанию запрашивает данные по всем рекламным аккаунтам к которым у вас есть доступ, эта доработка коснулась следующих функций:
    • fbGetCampaigns()
    • fbGetAdSets()
    • fbGetAds()
    • fbGetAdCreative()
    • fbGetApps()
    • fbGetPages()
    • fbGetAdAccountUsersPermissions()
    • fbGetAdAccountUsers()

• Удалённые функции

  • Из пакета полностью удалена функция fbGetProjects(), в связи с тем, что в Facebook больше не существует проектов.

• Авторизация

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

• Документация

  • В виньетку по загрузке статистики добавлена информация про окна атрибуции: vignette('rfacebookstat-get-statistics', package = 'rfacebookstat')
  • В пакет добавлена новая виньетка посвящённая процессу авторизации и его автоматизации: vignette('rfacebookstat-authorization', package = 'rfacebookstat')

• Прочее

  • Пакет переведён на работу с версией API v5.0.

Переход на API v.3.3 и другие обновления

В rfacebookstat более полугода не было обновлений и наконец у меня добрались руки до перевода пакета на работу с API Facebook v3.3, и других доработок которые были достаточно давно запланированы.

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

Новая функция

В пакет добавлена функция fbGetCatalogs, предназначенная для загрузки каталогов

Опции

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

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

library(rfacebookstat)

options(rfacebookstat.api_version  = "v3.3",
        rfacebookstat.access_token = "ваш токен",
        rfacebookstat.accounts_id  = "act_0000000",
        rfacebookstat.business_id  = 0000000)

Далее все функции будут запрашивать эти значение непосредственно из опций.

Упрощённый синтаксис фильтрации данных при загрузке статистики

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

Примеры синтаксиса фильтрации:

• Получить строки в которых менее 5000 показов: "impressions LESS_THAN 5000"
• Получить строки в которых значения поля publisher_platform будет instagram или facebook: "publisher_platform IN instagram,facebook"
• Получить строки в которых менее 500 кликов и более 1000 показов: c("clicks LESS_THAN 500", "impressions GREATER_THAN 1000")

Загрузка action и применения action_breakdowns

После перехода API Facebook на версию 3.1 пакет перестал загружать данные поля actions и работать с параметром action_breakdowns в связи с изменением структуры возвращаемых от API данных.

В версии 1.9.0 ' эта проблема была исправлена.

Новый аргумент в функции fbGetMarketingStat

action_report_time - Допустимые значения: impression, conversion. Определяет отчет о времени действия статистики. Например, если человек видел объявление 1 января, но совершил конверсию 2 января, при запросе API с action_report_time = "impression", вы увидите конверсию 1 января. Когда вы запросите API с помощью action_report_time = "conversion", вы увидите преобразование 2 января.

Виньетка посвящённая загрузке статистики из API Facebook

Для упрощения понимания основной функции пакета fbGetMarketingStat я написал подробную виньетку, открыть её можно с помощью команды vignette('rfacebookstat-get-statistics', package = 'rfacebookstat').

Содержание виньетки:

1. Аргументы
2. Разбивки
3. Разбивки по событиям
4. Применить одновременно несколько разбивок
5. Фильтрация данных
6. Лимиты API и аргумент request_speed

Обработчик лимитов API

В Facebook API v3.3 поменялись лимиты на количество возможных запросов, в пакет был дописан обработчик лимитов, но пока сам API по лимитам работает не корректно поэтому при запросе статистики по дням за длительный период используйте аргумент request_speed.

Новое поле возвращаемое функцией fbGetAdCreative

Ранее fbGetAdCreative возвращала только поля link и url_tags на уровне объявления, в которых хранились основная ссылка и параметры URL соответственно. Теперь, благодаря доработке Эдуарда Горха появилось поле link_nested, которое хранит данные по ссылкам и меткам, если они стоят на уровень ниже в иерархии объявления (например, в кольцевой галерее). Если таких параметров несколько, то они записывается в одну ячейку через точку с запятой. Это позволит выгружать полные данные по ссылкам и UTM-меткам рекламы.

Переход на версию API v3.1

Все функции пакета переведены на работу с версией API Facebook v3.1.

В rfacebookstat добавлены 4 новые функции.

В rfacebookstat 1.7.0 добавлены 4 новые функции с помощью которых вы можете получить информацию и параметры следующих объектов рекламного аккаунта.

• fbGetCampaigns - Загрузка списка рекламных кампаний;
• fbGetAds - Загрузка списка объявлений;
• fbGetAdCreative - Загрузка контента объявлений;
• fbGetAdSets - Загрузка списка групп объявлений.

Все новые функции имеют одинаковый набор аргументов:

• accounts_id - ID рекламного аккаунта из которого вы хотите загрузить список объектов, пример: 'act_0000001'.
• api_version - Версия API к которой вы обращаетесь, по умолчанию 'v3.0'.
• access_token - Ваш токен доступа к API, токен можно получить с помощью функции fbGetToken, после чего его можно обменять на долгосрочный токен с помощью функции fbGetLongTimeToken.

Пример загрузки списка рекламных кампаний:

library(rfacebookstat)
fb_token <- fbGeToken(app_id = 0000000)
fb_camp <- fbGetCampaigns(accounts_id  = 'act_0000001', api_version  = 'v3.0', access_token = fb_token)

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

В rfacebookstat 1.6.1 добавлено 3 новые функции, направленные на управление доступами к рекламным аккаунтам.

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

Функции для управления списком пользователей в рекламных аккаунтах Facebook

• fbGetAdAccountUsersPermissions - Загружает список пользователей с их привилегиями и ролью для рекламного аккаунта.
• fbUpdateAdAccountUsers - Добавить пользователей в рекламные аккаунты на Facebook.
• fbDeleteAdAccountUsers - Удалить пользователей из рекламных аккаунтов в Facebook.
  .

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

# Подключаем пакет
library(rfacebookstat)

# Получаем токен для работы с API, вместо 000000000000 необходимо указать ID приложения в Facebook
tk <- fbGetToken(000000000000) 

# Получаем список рекламных аккаунтов, вместо 1111111111111 необходимо указать ID вашего бизнес менеджера
accounts <- fbGetAdAccounts(source_id = 1111111111111,
                            api_version = "v2.12", 
                            access_token = tk)

# Получаем список пользователей с привелегиями из всех рекламных аккаунтов в бизнес менеджере
UserList <- fbGetAdAccountUsersPermissions(accounts_id = accounts$id,
                                           api_version = "v2.12", 
                                           access_token = tk)

# Добавляем пользователей с id 2222 и 3333 с правами администратора во все рекламные аккаунты
fbUpdateAdAccountUsers(user_ids = c(2222, 3333), 
                       accounts_id = accounts$id, 
                       role = "administator",
                       api_version = "v2.12",
                       access_token = tk)

# Удаляем из всех аккаунтов пользователей с ID 4444 и 5555
fbDeleteAdAccountUsers(user_ids = c(4444, 5555), 
                       accounts_id = accounts$id, 
                       api_version = "v2.12",
                       access_token = tk)

Улучшена функция fbGetMarketingStat

В fbGetMarketingStat добавлен аргумент request_speed, с помощью которого можно регулировать скорость отправки запросов к API Facebook, в зависимости от уровня доступа к API вашего приложения на Facebook рекомендуется использовать следующие значения.

• С уровнем доступа Development - "slow"
• С уровнем доступа Basic - "normal"
• С уровнем доступа Standart - "fast"

Так же вы можете передать в этот аргумент числовое значение, количество секунд в паузе между отправкой запросов.

Подробно работа с этим аргументом расписана в этой статье.

Так же был доработан аргумент interval, теперь он поддерживает работу со значением "overall", передав в аргумент interval значение "overall" вы получите суммарные данные за выбранный временной интервал.

Исправлена ошибка в функции fbGetAdAccounts

Исправлена ошибка в функции fbGetAdAccounts которая возникала при попытке получить список доступных аккаунтов из API v2.11, с версии 1.4.7 эта ошибка возникать не будет, теперь fbGetAdAccounts можно использовать как для работы с API v2.10 так и с API v2.11.

Доработана функция fbGetMarketingStat

В rfacebookstat 1.4.6 была улучшена основная функция пакета fbGetMarketingStat.

• Ранее при запросе данных в разбивке по дням за длительный период у пользователей с уровнем доступа к API ниже Стандартного возникала ошибка (#17) User request limit reached, связано это было с большим количеством запросов к API, теперь при возникновении такой ошибки загрузка данных не сбивается, а запускается механизм обхода лимита, который заключается в том, что необходимо подождать от 1 до 5 минут и продолжить загрузку данных, таким образом процесс загрузки при попадании в лимит будет проходить дольше, но при этом данные будут загружены не смотря на лимит.
• В функцию добавлен аргумент console_type, который принимает одно из двух значений:
  • "progressbar" (по умолчанию) - для вывода в консоли прогресс бара, отображающего % загруженных даных.
  • "message" - для вывода сообщений о процессе загрузки, например вывод сообщений о том, что был запущен механизм обхода пользовательского лимита на количество допустимых запросов к API Facebook.
• Добавлено итоговое сообщение содержащее общую информацию о загруженных данных, количество строк, количество запросов к API, количество запросов, вернувших ошибки.

---

Data loaded successfully!
Loaded 14393 rows.
Sended 309 API requests.
21 error request.

Добавлена возможность работы с action_breakdowns.

В версии 1.4.3 была доработана функция fbGetMarketingStat, теперь она поддерживает работу с action_breakdowns.

Для начала переустановите пакет rfacebookstat.

devtools::install_github("selesnow/rfacebookstat")

Пример кода для работы с action_breakdowns:

library(rfacebookstat)
token <- fbGetToken(app_id = 00000000000000)
fb_data <- fbGetMarketingStat(accounts_id = "act_123456789123456789",
                                                  level = "campaign",
                                                  fields = "campaign_name,actions",
                                                  action_breakdowns = "action_link_click_destination",
                                                  date_start = "2017-11-01",
                                                  date_stop = "2017-11-20",
                                                  interval = "month",
                                                  access_token = token)

В функции fbGetMarketingStat добавлена временная разбивка.

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

Допустимые значения аргумента:

• "day" - получить данные в разбивке по дням
• "week" - понедельная разбивка
• "month" - помесячная разбивка
• "quarter" - поквартальная разбивка
• "year" - погодовая разбивка

По умолчанию функция берёт значение day.

Пример кода для понедельной выгрузки данных.

library(rfacebookstat)

token <- fbGetToken(app_id = 1111111)

#Проходим аутентификацию в AdWords
fb_week <- fbGetMarketingStat(accounts_id = "act_1111111111",
                              level = "campaign",
                              fields = "campaign_name,impressions,clicks,spend",
                              breakdowns = "impression_device",
                              date_start = "2017-10-09",
                              date_stop = Sys.Date(),
                              interval = "week",
                              access_token = "abcde12345")