Sourcebuster JS: скрипт определения
источников посетителей сайта

Скрипт определяет, откуда пришёл посетитель сайта: с рекламы, органического поиска или другого источника. Вот что можно дальше делать с этим данными:

Указывать источник в тексте заявок и заказов с сайта.

Модуль сохранит данные в cookies, технолог добавит их вывод в заявку.

Генерировать промокод, который можно выводить на сайте, отправлять в Google Analytics и др. системы.

Промокод также сохранится в cookies, технолог добавит его вывод на сайте.

Подменять номера телефонов в зависимости от источника перехода.

Подмена реализуется отдельным модулем SB Placer на основании данных Sourcebuster JS.

Подменять заголовки и другой контент в зависимости от источника перехода.

Реализуется аналогично подмене номеров телефонов через SB Placer.

Вот что определил модуль для вас

Первый визит

Текущий визит

Личные данные

Данные о текущей сессии

Тестовые ссылки

UTM-разметка

При переходе по ссылке, размеченной utm-метками, посетителю будет присвоен тип трафика utm и значения utm-меток сохранятся в куки посетителя.

Органическая выдача

После клика на одну из ссылок вы попадете на страницу органической выдачи поисковой системы, где будет ссылка на тестовую страницу модуля: sbjs.rocks/

Переходите по ссылке из выдачи и смотрите что определил для вас модуль.

Реферальные переходы

Это переходы со сторонних сайтов. После клика на тестовую ссылку вы увидите, что модуль определил ваш визит как реферальный, который был совершен со страницы сайта it-agency.ru

Открывайте эту ссылку в режиме Incognito / Private, поскольку если у вас открыта текущая сессия, то источник не перезапишется.

Дистрибутив

Забрать из NPM:
npm install --save sourcebuster
Bower:
bower install --save sourcebuster

Или скачать репозиторий с GitHub и использовать sourcebuster.min.js из папки /dist

Установка

Для установки скрипта на HTML-страницу, просто добавьте в <head>:
<script src="/path/to/sourcebuster.min.js"></script>
Также Sourcebuster доступен как CommonJS / AMD модуль:
var sbjs = require('sourcebuster');

После подключения библиотеки становится доступен объект sbjs. Он имеет 2 метода: init & get. Первый  — запускает скрипт, второй — отдаёт данные.

Запускаем:

<script src="/path/to/sourcebuster.min.js"></script>
<script>

	sbjs.init();

</script>

После инициализации:

  • проставятся куки скрипта
  • будут доступны данные через метод sbjs.get

Настройка

Метод sbjs.init принимает один аргумент: объект с настройками. Все они опциональны и обычно это будет выглядеть примерно так:

sbjs.init({
	domain: 'it-agency.ru',
	lifetime: 3,
	callback: doSmth
});

Параметры

  • lifetime: 6
    Устанавливаем срок жизни кук. По умолчанию 6 месяцев.
  • session_length: 30
    Устанавливаем продолжительность сессии пользователя в минутах. В рамках данного модуля это показатель влияет только на перезапись / не-перезапись реферального источника.
  • 
    domain: {
    	host: 'it-agency.ru',
    	isolate: false
    }
    Настраиваем домены.

    Прежде всего давайте поговорим о том, как скрипт ведет себя при отсутствии этого параметра: если мы не передаём ему никакого значения, куки будут поставлены для текущего домена и всех его поддоменов.

    Почему это работает именно так. Предположим сайт не имеет поддоменов и сейчас это не важно: шарит ли главный домен печеньки с поддоменами или нет. Но что будет, если однажды поддомены всплывут? Если куки были не расшарены, то поддменам они будут недоступны. Это означает, что переход с основного домена на поддомен (и наоборот) будет считаться реферальным трафиком.

    Поэтому по умолчанию печеньки шарятся. Так или иначе, если вы не хотите делиться куками  — используйте опцию isolate: true для того, чтобы изолировать их.

    Давайте посмотрим на примеры.

    Предположим у вас есть сайт: site.com. На вашем сайте есть блог: blog.site.com. И вы хотите, чтобы переходы с сайта на блог и обратно считались внутренним трафиком: то есть источник blog.site.com не фиксировался как referral и не перезаписывал другие источники при новой сессии. Для этого нужно на страницах сайта и блога добавить строчку:

    domain: 'site.com'

    При такой настройке, если пользователь перешел с blog.site.com на site.com (а также с alex.blog.site.com на site.com), источник не перезапишется и такой переход будет равноценен переходу с site.com/about на site.com/contacts.

    Теперь рассмотрим противоположенный сценарий: когда вы хотите разделять трафик между поддоменами и считать его реферальным. Есть основной сайт (site.com) и есть блог (blog.site.com), на котором есть поддомены для юзеров (alex.blog.site.com). Вы хотите переходы между blog.site.com и alex.blog.site.com считать внутренним трафиком, а переходы между этими поддоменами и основным сайтом — реферальным. Для этого:

    
    // на страницах основного сайта
    domain: {
    	host: 'site.com',
    	isolate: true
    }
    
    // на страницах поддоменов blog.site.com и alex.blog.site.com
    domain: 'blog.site.com'

    Обратите особое внимание на параметр isolate в параметрах для основного сайта. Он имеет значение true тогда и только тогда, когда не-реферальным трафик должен быть исключительно в рамках указанного домена. Весь остальной трафик, включая переходы с поддоменов в этом же домене, будет считаться реферальным.

    В нашем примере при такой настройке все переходы между основным сайтом и блогами будут считаться реферальным трафиком. И если пользователь в первый раз перешёл на основной сайт, кликнув по ссылке из блога пользователя, то его источник будет: alex.blog.site.com (тип трафика: referral).

    Не изменяйте значение параметра isolate после выкатки скрипта на боевой сервер. Иначе посетители получат дублирующиеся куки и начнут происходить странные вещи.

    Опция, которая позволит принудительно обновлять домен у печенек при смене настроек, в списке работ, но пока она не реализована.

    Проверьте ещё раз, что вы правильно поняли, когда использовать этот параметр.

    Домен страницы, на которой установлена настройка isolate с параметром true должен совпадать с хостом, указанным в этой настройке:

    
    // ВЕРНО: на страницах site.com
    domain: {
    	host: 'site.com',
    	isolate: true
    }
    
    // НЕ ИМЕЕТ СМЫСЛА: на страницах blog.site.com
    	domain: {
    	host: 'site.com',
    	isolate: true
    } 
    Указанный хост не имеет поддоменов, трафик с которых вы хотите считать не-реферальным:
    
    domain: {
    	host: 'site.com',
    	isolate: true
    }
    // трафик со ВСЕХ поддоменов на site.com будет реферальным 
  • 
    referrals: [
    	{
    		host: 't.co', // Это хост Twitter'а из `http referer`
    		medium: 'social', // Это настраиваемый `utm_medium`, если не указать - будет `referral`
    		display: 'twitter.com' // Так оно сохранится в куку
    	},
    	{
    		host: 'plus.url.google.com',
    		display: 'plus.google.com'
    	}
    ]

    Добавляем источник реферального трафика. Вобще, если вас устраивает, что utm_medium при переходе например с facebook.com будет иметь значение referral, то ничего настраивать не надо. Но если вы хотите присваивать таким переходам кастомный канал (например, utm_medium=social), то вы можете добавить такую настройку через referrals. Первый параметр host — это хост из http-реферера, второй — medium — желаемое значение utm_medium.

    Кроме того у некоторых ресурсов реферер отличается от основного домена (например, у Twitter хост реферера — t.co). В таких случаях вы можете присваивать алиас источникам через опциональный параметр display. Через него же вы можете группировать несколько сайтов с разными реферерами в один виртуальный источник.

    Скрипт по умолчанию распознает переходы из Twitter и Google+:
    
    referrals: [
    	{
    		host: 't.co',
    		display: 'twitter.com'
    	},
    	{
    		host: 'plus.url.google.com',
    		display: 'plus.google.com'
    	}
    ]

    Вы всё ещё можете переопределить эти переходы через свою настройку (например если хотите изменить отображаемые названия источника или сменить канал на social).

  • В скрипте уже есть ряд предустановленных органических источников:

    Source Alias
    google.all google
    yandex.all yandex
    bing.com bing
    yahoo.com yahoo
    about.com about
    aol.com aol
    ask.com ask
    globososo.com globo
    go.mail.ru go.mail.ru
    rambler.ru rambler
    tut.by tut.by
    
    organics: [
    	{
    		host: 'bing.com',
    		param: 'q',
    		display: 'my_bing_alias'
    	}
    ]

    Допустим вы хотите, чтобы система считала переходы с поиска bing.com — органическим трафиком. И алиас для этого источника должен быть my_bing_alias. Для этого вам нужно добавить параметр host: 'bing.com', и параметр ключевого слова param: 'q'. Оба параметра обязательны. Для переопределения алиаса укажите опциональный третий параметр display: 'my_bing_alias'.

    Для получения параметра ключевого слова, нужно зайти на bing.com и вбить в поисковую строку запрос (например, «apple»). После этого вы попадёте на страницу выдачи с адресом вида: http://www.bing.com/search? q=apple &go=&qs=n&form=QBLH&pq=apple&sc=8-5&sp=-1&sk=&cvid=718ad07527244c319ecebf44aa261f64

    Параметр ключевого слова — 'q' — это символ между «?» (или «&» если параметр идёт не первым после знака вопроса) и «=apple» в урле страницы поисковой выдачи.

  • 
    typein_attributes: {
    	source: '(direct)',
    	medium: '(none)'
    }

    Устанавливаем пользовательские значения source и medium для typein трафика. По умолчанию значения этих параметров — (direct) & (none). Вы можете переопределить их с помощью параметра typein_attributes.

  • timezone_offset: 3

    Устанавливаем часовой пояс. По умолчанию используется часовой пояс пользователя.

    Пример. Посетитель из Лондона (UTC +00:00) зашел на сайт в 03:00 AM (местное время посетителя). Если предустановки нет, то в куку сохранится 03:00 AM. Другой посетитель в то же самое время заходит из Берлина (UTC +01:00). Его местное время 04:00 AM. Время в его куке будет 04:00 AM.

    Если вы хотите нормировать время всех посетителей (например по Москве UTC +03:00), нужно выставить настройку timezone_offset: 3. Тогда время в куках обоих посетителей будет 06:00 AM.

  • campaign_param: 'my_adwords_campaign'

    Устанавливаем GET-параметр, значение которого будет сохранено в качестве utm_campaign (если в запросе нет оригинального параметра utm_campaign). Эта настройка была добавлена в основном из-за метки Google AdWords gclid.

    Пример использования
    Если у вас есть трафик с Google AdWords, и вы используете метку gclid, вы можете сократить урлы, убрав utm-разметку. Sourcebuster всё равно определит, что это utm-трафик с Google AdWords.

    Если в урле присутствует только метка gclid: http://site.com/sourcebuster-js/? gclid=sMtH

    Это даст следующий результат:

    • Traffic type: utm
    • utm_source: google
    • utm_medium: cpc
    • utm_campaign: google_cpc
    • utm_content: (none)
    • utm_term: (none)

    Вы можете изменить значение utm_campaign через campaign_param: http://site.com/sourcebuster-js/? gclid=sMtH&custom_campaign=test_custom

    Тогда результат будет такой:

    • Traffic type: utm
    • utm_source: google
    • utm_medium: cpc
    • utm_campaign: test_custom
    • utm_content: (none)
    • utm_term: (none)

    ВАЖНО

    • Если в урле присутсвуют оригинальные utm-метки (utm_source, utm_medium, utm_campaign), то метка gclid и параметр, заданный через campaign_param, будут проигнорированы.
    • Если в урле присутствует только параметр, заданный через campaign_param, Sourcebuster будет считать этот переход utm-трафиком.
  • user_ip: <%= request.remote_ip %>

    По умолчанию скрипт не сохраняет ip-адрес посетителя (потому что JS не умеет его определять). Если вы хотите сохранять его в пользовательской куке, можете добавить его через параметр user_ip, получив на бэке. В примере показано, как это сделать на Ruby.

  • 
    promocode: true
    
    // или
    promocode: {
    min: 100000,
    max: 999999
    }

    Устанавливаем промокод.

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

    Нижняя и верхняя границы диапазона значений промокода задаются через параметры min & max параметры. Они, кстати, необязательные. Если их не указать, то будут генерироваться промокоды в диапазоне от 100 000 до 999 999.

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

  • callback: doSmth

    Callback. Передайте параметру имя функции, и скрипт исполнит её сразу после того, как куки будут проставлены. В качестве аргумента функция получит объект с результирующими данными:

    
    sbjs.init({ callback: go });
    
    	function go(sb) {
    	console.log('Cookies are set! Your current source is: ' + sb.current.src);
    }
    							

Использование данных

Данные доступны через метод sbjs.get (отдается объект).

Ниже список того, что вы можете получить.

Текущий источник посетителя

Параметры самого крайнего источника посетителя. Если у него было несколько источников, то это самый последний из них:


sbjs.get.current.typ
// тип трафика
// возможные значения: `utm`, `organic`, `referral`, `typein`

sbjs.get.current.src
// источник (utm_source)

sbjs.get.current.mdm
// канал (utm_medium)

sbjs.get.current.cmp
// кампания (utm_campaign)

sbjs.get.current.cnt
// контент (utm_content)

sbjs.get.current.trm
// ключевое слово (utm_term)
				

Дополнительные данные о текущем источнике

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


sbjs.get.current_add.fd
// дата и время визита
// формат: `yyyy-mm-dd hh:mm:ss`

sbjs.get.current_add.ep
// точка входа

sbjs.get.current_add.rf
// реферер

Первый источник посетителя

Объекты: sbjs.get.first & sbjs.get.first_add

Всё тоже самое, что и sbjs.get.current & sbjs.get.current_add, но относится к самому первому визиту посетителя. Фиксируется один раз, никогда не перезаписывается.

Активная сессия

Информация о текущей открытой сессии посетителя:


sbjs.get.session.pgs
// сколько страниц сайта посмотрел посетитель

sbjs.get.session.cpg
// URL текущей страницы посетителя
				

Информация о пользователе

Дополнительная информация о пользователе: кол-во визитов, ip & браузер:


sbjs.get.udata.vst
// сколько раз пользователь посещал сайт

sbjs.get.udata.uip
// текущий ip-адрес

sbjs.get.udata.uag
// текущий браузер
				

Промокод

sbjs.get.promo.code // промокод

Ограничения

По стандарту при переходе с протокола https на http в реквесте нет реферера, и такие переходы будут определяться модулем как typein (то есть прямые заходы).

Ссылки

Следить за обновлениями скрипта на sbjs.rocks и на alexfedoseev.com