JS клиент

Js клиент - это код, который размещается в теме оформления вашего сайта и запускается в браузере при посещении клиентом. Этот код необходим для показа виджетов и отслеживания активности посетителя, его характеристик.

Главный исполняемый код размещается перед закрывающим </head> на всех страницах сайта:

<script type="text/javascript">
(function(w,d,c,h){w[c]=w[c]||function(){(w[c].q=w[c].q||[]).push(arguments)};var t = d.createElement('script');t.charset = 'utf-8';t.async = true;t.type = 'text/javascript';t.src = h;var s = d.getElementsByTagName('script')[0];s.parentNode.insertBefore(t, s);})(window,document,'difflex','https://cdn.jsdelivr.net/gh/difflex/difflex_js_client@latest/difflex.js');

difflex('appKey', 'xxxxxxxxxxxxxxxxxxxxxx');
</script>

В нем указываются настройки инициализации (вместо "xxxxxxxxxxxxxxxxxxxxxx" подставляется ключ вашего аккаунта Difflex). Как правило, это appKey вашего аккаунта и данные о зарегистрированном пользователе (если такие имеются).

Настройки

Задание appKey аккаунта. Этот ключ уникален для каждого аккаунта.

difflex('appKey', 'yyyyyyyyyyyyyyyyyyyyy');

Включение режима отладки. В этом режиме в консоли браузера отображается ключевая отладочная информация о всех событиях в js-api.

difflex('debug', true);

Явное указание адреса сервера.

difflex('setEndpoint', '//tracker.difflex.ru/')

Колбек инициализации js-api. После завершения загрузки скрипта выполняется данный колбек. Внутри колбека через объект this доступны системные методы и переменные.

difflex(function() {
  console.log('On ready');
});

Указание данных текущего посетителя. Как правило, используется для подстановки uid, firstName, lastName, email для текущего зарегистрированного пользователя. Важно объявлять только известные данные, т.к. передача пустого значения одной из характеристик сотрет текущее значение в базе контактов.

difflex('setVisitorInfo', {
  uid: 1,
  firstName: 'John',
  lastName: 'Konor'
});

В js-api предусмотрены различные триггеры, на которые можно подписаться. Это может быть отправка каких-либо событий или нажатие на кнопку в виджете. 

difflex('subscribe', 'url.change', function(url) {
  console.log('Change url', url)
});

Список доступных триггеров:

События

Для передачи данных об активности посетителя на сайте используются события. Существует список стандартных e-commerce событий, которые можно расширить дополнительными в настройках аккаунта.

Синтаксис отправки всех событий имеет одинаковый вид:

difflex('track', [eventName], [properties], [callbackFunction]);

"link" - просмотр страницы

Это событие отправляется автоматически при посещении страницы или при изменении ее адреса для SPA сайтов. В событии передаются характеристики текущей страницы - ее адрес, заголовок и referrer. По умолчанию они добавляются автоматически, задавать их вручную не нужно.

difflex('track', 'link');

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

difflex('track', 'link', {title: 'My title', url: 'http://mysite.com', referrer: 'http://somesite.com'});

"productView" - просмотр товара

Событие просмотра товара (варианта товара) должно отправляться с каждой продуктовой страницы. С помощью этого события фиксируются товарные предложения, которые просматривал посетитель.

Обязательные поля, которые нужно задавать: sku, price

difflex('track', 'productView', {
  offer: {
    sku: 'sku',
    name: 'My product',
    price: 1000.0,
    priceOld: 99.0,
    url: 'http://mysite.com',
    picture: 'http://mysite.com/products/sku.jpg'
  }
});

"cartUpdate" - обновление состава корзины

При любом изменении состава товаров (вариантов) в корзине необходимо отсылать данные на сервер. Это может быть добавление товара в корзину или изменение количества одного из товаров, удаление товара из корзины, очистка корзины.

Обязательные поля в массиве offers: sku, qnt, price

difflex('track', 'cartUpdate', {
  offers: [
    {
      sku: 'sku',
      name: 'My product',
      qnt: 1,
      price: 1000.0,
      priceOld: 99.0,
      url: 'http://mysite.com',
      picture: 'http://mysite.com/products/sku.jpg'
    }
  ]
});

"orderCreate" - создание нового заказа

Событие создания нового заказа наступает, когда посетитель заполнил форму заказа и нажал "подтвердить заказ". Как правило, после завершения оформления заказ создается в базе сайта и ему присваивается уникальный номер. После этого покупателю отображают страницу оплаты и/или последующую страницу "Спасибо за покупку".

Если покупатель всегда попадает на страницу "Спасибо за покупку", то удобнее всего размещать код создания заказа на этой странице.

Если покупатель отправляется в платежный шлюз и не имеет возможности вернуться на сайт после оплаты, то отправка события заказа не может быть гарантирована. В таких случаях рекомендуется отправлять событие с backend сайта (с сервера). Это можно сделать с помощью php библиотеки или сделать реализацию на другом языке.

Обязательные поля: number, total

Обязательные поля в массиве offers: sku, qnt, price

difflex('track', 'orderCreate', {
  number: '123',
  total: 200.0,
  state: 'new',
  cancelled: false,
  paid: false,
  offers: [
    {
      sku: 'sku',
      name: 'My product',
      qnt: 1,
      price: 1000.0,
      priceOld: 99.0,
      url: 'http://mysite.com',
      picture: 'http://mysite.com/products/sku.jpg'
    }
  ]
});

Описание полей:

"visitorUpdate" - обновление контактов посетителя

Если данные о посетителе изменились, то необходимо их передать на сервер. Как правило, это может быть нужно при заполнении какой-либо формы на сайте.

difflex('track', 'visitorUpdate', {
  firstName: 'Agent',
  lastName: 'Smith',
  email: 'mail@example.net'
});

Дополнительные события

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

Передача дополнительного события записывается по шаблону:

difflex('track', eventName, properies, callbackFunction);

Где eventName - название события (записывается с заглавной буквы в стиле CamelCase); properties - необязательные поля, которые можно использовать в рассылках и виджетах для передачи каких-либо данных.

Готовы начать?