Рекламные сети

Коннекторы рекламных сетей и сервисов позволяют выгружать из них данные о расходах на трафик. Эти данные используются для формирования статистики по ROI.

Общие принципы работы

Коннектор реализует функцию fetch, которая отвечает за выгрузку данных и возвращает массив с расходами за период. Функция должна запросить сведения из сервиса и разбить их по указанным критериям, например, UTM-метке.

Результирующий массив может включать следующие поля:

cpc - стоимость за один клик.
cost - общая стоимость всех кликов по указанным условиям.
currency - ISO-код валюты цены, например, usd.
from и to - lаты начала и окончания периода, по которому задавать цену, в формате UNIX Timestamp.
flow - идентификатор потока.
utms - метка utm_source.
utmc - метка utm_campaign.
utmn - метка utm_content.
utmt - метка utm_term.
utmm - метка utm_medium.
extu - метка "Идентификатор" для агентств.
exts - метка "Источник" для агентств.

В запросе обязательно должны присутствовать параметры cpc или cost и хотя бы одно условие (даты, поток, UTM-метки). Цена присваивается только тем кликам, которые система считает входящими - уникальным кликам на прелендингах и уникальным кликам на лендингах без использования прелендинга.

Создание коннектора

Работа с коннкеторами для рекламных сетей ведется в разделе "Рекламные сети" по кнопке "Файлы". Сами файлы коннекторов располагаются в папке adv вашего хака. Название файла может состоять из маленьких латинских букв и цифр. Оно обязательно должно начинаться с буквы, а не цифры. Нельзя использовать заглавные буквы и спецсимволы, в том числе дефис или знак подчёркивания.

В момент создания коннектора, в файле автоматически создаётся соответствующий класс. Название класса состоит из слова adv, названия хака и названия коннектора, разделенных знаком подчёркивания, например: adv_facebook. Коннектор должен наследоваться от класса advbase.

В коннекторе должно быть определено поле $auths с массивом данных для авторизации и функция fetch для выгрузки данных.

class adv_facebook extends advbase {

  // Auth parameters: login, pass, api
  public $auths = [ 'login', 'pass' ];

  // Fetcher
  public function fetch() {

    $info = curl( "https://some.url/api", [
      "login"  => $this->auths["login"],
      "pass"  => $this->auths["pass"],
      "from"  => $this->from(),
      "to"  => $this->to(),
    ]);

    foreach ( $info["stats"] as $d ) {
      if ( ! $d["spent"] ) continue;
      $data[] = [
        "from" => $this->from(),
        "to" => $this->to(),
        $this->field() => $d["item"],
        "cost" => $d["spent"],
        "currency" => $d["currency"],
      ];
    }

    return $data;

  }

}

Чтобы созданный коннектор красиво показывалось в списке, добавьте в языковой файл поле advrt_name, где вместо name указывается название созданного коннектора. Вы также можете использовать advrt_name_d для добавления описания коннектора и его настроек.

'advrt_facebook' => 'Facebook',
'advrt_facebook_d' => 'Выгрузка расходов из Facebook. В настройках укажите токен из личного кабинета, который начинается на EAAB',

Подключение к системе

Коннекторы не появятся в списке рекламных сетей автоматически, вам нужно указать их через файл запуска. Для этого в массиве инициализации укажите ключ adv, а в качестве значения - список доступных в вашем хаке коннекторов. Например:

return [
  /* другие команды инициализации */
  'adv' => [ 'facebook' ],
];

Особенности реализации

В начале файла обязательно укажите параметры, необходимые для настройки авторизации. Эти поля будут показаны в форме настройки рекламной сети. Они указываются в поле $auths в виде массива, например:

public $auths = [ 'login', 'pass' ];

В качестве параметров могут использоваться:

url - ссылка или домен для выгрузки данных.
login - логин для доступа к сервису.
pass - пароль для доступа к сервису.
api - ключ API от сервиса.
key - секретный ключ API от сервиса.

Внутри класса вы можете использовать полезные функции для доступа к конфигурации:

$this->config[$name] - массив конфигурации.
$this->auths[$name] - массив данных для доступа.
$this->from() - начало периода выгрузки в формате UNIX timestamp.
$this->to() - окончание периода выгрузки в формате UNIX timestamp.
$this->field() - поле, по которому определяется идентификатор кампании.
$this->curl( $url, $post, $cc ) - журналируемый запрос к сервер по $url с необязательными параметрами данных в $post и конфигурации в $cc.
$this->json( $url, $post, $cc ) - CURL-запрос с получением данных в формате JSON.

Любые запросы к серверу рекомендуется делать через встроенные функции curl или json, чтобы любые запросы сохранялись в журнале и их можно было проанализировать в случае ошибок.

Функция настройки

Чтобы добавить дополнительные поля к настройкам, необходимо реализовать две функции:

form - возвращает массив с дополнительными полями формы.
save - принимает сырые данные и возвращает массив с полями конфигурации.

Функция form не имеет параметров. Доступ к полям конфигурации должен выполняться через массив $this->config. Результатом работы функции должен быть массив полей формы. Каждое поле - это массив, который может содержать следующие поля:

type - тип поля: text, email, textarea, number, select, mselect, radio, checkbox.
name - название поля, рекомендуется добавлять префикс с названием модуля.
head - заголовок поля, используйте языковой файл для хранения.
descr - описание поля, используйте языковой файл для хранения.
value - текущее значение поля, используйте $this->config.
options - набор опций для полей типа select, mselect, radio.
checked - пометка для поля типа checkbox.

Пример реализации формы:

public function form() {
  $cur = $this->config['cur'] ? $this->config['cur'] : 'usd';
  return [
    [ 'type' => 'select', 'name' => 'dolphin_type', 'head' => $this->core->lang['advrt_dolphin_f'], 'value' => $this->config['type'], 'options' => $this->core->lang['advrt_dolphin_t'] ],
    [ 'type' => 'select', 'name' => 'dolphin_cur', 'head' => $this->core->lang['currency'], 'value' => $cur, 'options' => $this->core->currency->codes ],
  ];
}

Функция save получает на вход параметр $data и должна вернуть обработанный массив параметров в виде ключ-значение. Текстовые значения обработайте через $this->esc(). Пример реализации:

public function save( $data ) {
  return [
    'type' => (int) $data['dolphin_type'],
    'cur' => $this->core->text->link( $data['dolphin_cur'] ),
  ];
}