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

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

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

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

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

  • cpc — стоимость за один клик.
  • cost — общая стоимость всех кликов по указанным условиям.
  • currency — ISO-код валюты цены, например, usd.
  • from и to — даты начала и окончания периода, по которому задавать цену, в формате UNIX Timestamp.
  • flow — идентификатор потока.
  • utms — метка utm_source.
  • utmc — метка utm_campaign.
  • utmn — метка utm_content.
  • utmt — метка utm_term.
  • utmm — метка utm_medium.
  • customer — метка customer.
  • 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'] ),
  ];
}