Sourcebuster JS

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. Через него же вы можете группировать несколько сайтов с разными реферерами в один виртуальный источник.

referrals: [
	{
		host: 't.co',
		display: 'twitter.com'
	},
	{
		host: 'plus.url.google.com',
		display: 'plus.google.com'
	}
]

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

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

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
}

Устанавливаем промокод. Он сохраняется в cookies и действует всё время их жизни (устанавливается параметром lifetime).

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

Нижняя и верхняя границы диапазона значений промокода задаются через параметры 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);
}