Advertising networks

Connectors of advertising networks and services allow you to load data on traffic expenses from them. This data is used to form statistics on ROI.

General principles

The connector implements the fetch function, which is responsible for loading data and returns an array with spends for the period. The function should request information from the service and break them according to these criteria, for example, an UTM tag.

The resulting array may include the following fields:

cpc - price per one click.
cost - total price for all the clicks for these contitions.
currency - ISO code of prices currency, for example, usd.
from and to - the start and the end dates of the period which to set the price, UNIX TimeStamp.
flow - flow ID.
utms - utm_source tag.
utmc - utm_campaign tag.
utmn - utm_content tag.
utmt - utm_term tag.
utmm - utm_medium tag.
extu - "ID" tag for the agency.
exts - "Source" tag for the agency.

The request must have cpc or cost parameters and at least one condition (date, stream, UTM tags). The price is assigned only to those clicks that the system considers incoming - unique clicks on prelandings and unique clicks on landing pages without the use of prelandings.

Creating a connector

Working with connectors is carried out in the "Advertising networks" section by clicking the "Files" button. The connector files themselves are located in the adv folder of your hack. The file name with the connector can consist of small Latin letters and numbers. It must begin with a letter, not a number. You cannot use capital letters or special characters, including hyphens or underscores.

When a connector is created, the corresponding class is automatically created in the file. The class name consists of the word adv and the name of the connectors, separated by an underscore, for example: adv_facebook. The connector must be inherited from the advbase class.

The connector must have the $auths field with an array of data for authorization and the fetch function for loading data.

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;

  }

}

To display connector nicely in the list, add the advrt_name field to the language file, where the name of the created connector is indicated instead of name. You can also use advrt_name_d to add a description of the connector and its settings.

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

Connecting to the system

Connectors will not automatically appear in the list of ad networks, you need to specify them through the startup file. To do this, specify the adv key in the initialization array, and the list of connectors available in your hack as the value. For example:

return [
  /* other initialization commands */
  'adv' => [ 'facebook' ],
];

Features of implementation

At the beginning of the file, be sure to specify the parameters required to configure authorization. These fields will be shown in the ad network setup form. They are specified in the $auths field as an array, for example:

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

The following can be used as parameters:

url - link or domain for uploading data.
login - login to access the service.
pass - password to access the service.
api - API key from the service.
key - API secret key from the service.

Inside the class, you can use useful functions to access the configuration:

$this->config[$name] - configuration array.
$this->auths[$name] - array of access data.
$this->from() - start of load period in UNIX timestamp format.
$this->to() - end of load period in UNIX timestamp format.
$this->field() - the field by which the campaign ID is determined.
$this->curl( $url, $post, $cc ) - logged request to the server at $url with optional data parameters in $post and configuration in $cc.
$this->json( $url, $post, $cc ) - CURL request to receive data in JSON format.

It is recommended to make any requests to the server through the built-in curl or json functions so that any requests are logged and can be analyzed in case of errors.

Setting function

To add additional fields to the settings, you need to implement two functions:

form - returns an array with additional form fields.
save - accepts raw data and returns an array with configuration fields.

The form function has no parameters. Configuration fields must be accessed via the $this->config array. The result of the function should be an array of form fields. Each field is an array that can contain the following fields:

type - field type: text, email, textarea, number , select, mselect, radio, checkbox.
name - field name, it is recommended to add a prefix with the module name
head - field heading, use language file for storage.
descr - description of the field, use the language file for storage.
value - current field value, use $this->config
options - a set of options for fields like select, mselect, radio.
checked - flag for a field of type checkbox.

Form implementation example:

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 ],
  ];
}

The save function receives the $data parameter as input and must return the processed parameter array as a key-value. Process text values with $this->esc(). Implementation example:

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