@qlean/analytics-client

Qlean аналитика

Библиотека для инетграции с аналитической платформы. После инициализации, все a.href будут вести на аналитическую платформу.

Подключение

Для подключения аналитики, на страницу нужно добавить следующий код.

<script>
(function (options) {
 window.$qat={options:options,buffer:[],emit:function(t){this.buffer.push(t)}};
 var parent=document.getElementsByTagName("script")[0],script=document.createElement("script");
 script.async=!0,script.src=options.script,parent.parentNode.insertBefore(script,parent);
})({
 script: 'https://storage.googleapis.com/pltf-analytics-dp-clfn-storage/public/bundle.js',
 url: 'https://anlt.cloud.qlean.ru/collect',
 timeout: 5000,
 wrapLink: true
});
</script>

Опции инициализации:

• script - ссылка на бандл с клиентским приложением
• url - путь до апи, куда отправляются точки
• timeout - таймаут между отправкой точек
• wrapLink - признак того, что необходимо обернуть все ссылки на редиректы аналитики (для отслеживания переходов)
• normalize - функция которая нормализует именя ключей

Тонкая настройка wrapLink

Опция wrapLink может принимать как булевое значение (true/false) в этом случае все сылки (a.href) будут переделаны на редиректы. Иногда этого не достаточно и для более тонкой настройки вы можете передать в качестве значения объект следующего формата:

wrapLink: {
  pattern: /^.*\.qlean\.ru\/app/i
}

После чего все ссылки, которые удовлетворяют этому условию будут проигнорированы. Например, это можно использовать когда часть ссылку у вас обрабатывается роутером в вашем SPA приложении.

Нормализация ключей

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

Пример приведение event_category к принятому виду eventCategory:

 normalize: function (key) {

      if (key === 'event_category') {
        key = 'eventCategory';
      }
    
      return key;
  }

Отправка события

Для отправки события в clickstream нужно выполнить следующий код.

<script>
  $qat.emit({
    eventId: '1234',
    eventAction: 'autorization',
    eventCategory: 'page_view',
    phone: '89686421141',
    user_id: 'fffff',
    device_id: 'asfljsfdaklsdfj',
    label: 'hello world'
  });
</script>

Следующие поля будут разложены по колонкам в clickstream:

• eventId
• eventAction
• eventCategory
• eventLabel
• phone
• user_id
• device_id
• deviceType
• appId
• environment

Все остальные поля будут упакованы в виде json объекта в поле eventProperties.

Использование библиотеки как модуля

Для начал ее необходимо установить

npm i @qleanlabs/analytics-client

После этого ее можно подключить и использовать

import { Qat } from '@qleanlabs/analytics-client';

const client = new Qat({
    buffer: [], // события которые произошли до инициализации модуля 
    options: {
      url: 'https://anlt.cloud.qlean.ru/collect',
      timeout: 5000,
      wrapLink: {
        pattern: /^.*\.qlean\.ru\/app/i
      },
      normalize: function (key) {
      
         if (key === 'event_category') {
           key = 'eventCategory';
         }
       
         return key;
      }
    }
});


client.emit({
    eventId: '1234',
    eventAction: 'autorization',
    eventCategory: 'page_view',
    phone: '89686421141',
    user_id: 'fffff',
    device_id: 'asfljsfdaklsdfj',
    label: 'hello world'
});

Статичная установка пикселя или ссылки

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

// просто пиксель 
<img hidden="hidden" src="//anlt.cloud.qlean.ru/collect?eid0=123&ea0=page_view&ec0=load&el0=ok"/>

Все параметры события передаются в качестве параметров querystring:

• eid0 - eventId
• ds0 - deviceType
• ai0 - appId
• ea0 - eventAction
• ec0 - eventCategory
• el0 - eventLabel
• ph0 - phone
• uid0 - user_id
• dvid0 - device_id
• env0 - окружение (production/stage и тд), нужно для того чтобы отличать тестовые точки в базе аналитики
• dl0 - ссылка с какой странице пришло события url, должна быть заэкножена через encodeURIComponent
• rul - ссылка, куда пользователя нужно редиректнуть, используется для переходов. Должна быть заэкножена через encodeURIComponent

Обратите вниманание, в одном пикселе может быть передано одно или более событие. Для их идексации используется цифра после имени параметра, например eid0 - это идентификатор первого события

Трекинг переходов

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

// трекинг переходов
<a href="http://anlt.cloud.qlean.ru/collect?rul=https%3A%2F%2Fqlean.ru%2F%3Futm_source%3D1%26utm_medium%3D2%26utm_campaign%3D3"/>

Где в параметре rul передается ссылка куда нужно перейти в заэкножена через encodeURIComponent.

Сылки

• Основные соглашения по аналитике - https://qleanru.atlassian.net/wiki/spaces/DOCS/pages/1244381621