SB-Placer: модуль подмены контента в зависимости от источника

Модуль подменяет телефонные номера, заголовки и контент в зависимости от источника или тематики рекламной кампании. Вы можете подменять любой контент по любым заданным вами критериям:

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

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

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

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

Модуль, который можно настроить без помощи программиста.

Достаточно изменить параметры в текстовом редакторе.

Как работает модуль

Вы пришли с

Специальное предложение для посетителей с

Отправьте смс с текстом «SB-free» на номер 4242 и получите код модуля подмены :-D

// определяем текущий источник посетителя
var source = sbjs.get.current.src;

// магия!
$('.sb-replace').sbPlacer({
	default_value: 'неизвестного источника',
		conditions: [
			{
				check: source,
				when: 'yandex',
				place: 'Яндекса'
			},
			{
				check: source,
				when: 'google',
				place: 'Google'
			},
			{
				check: source,
				when: 'adv',
				place: 'рекламной кампании'
			},
			{
				check: source,
				when: 'mail',
				place: 'рассылки'
			}
		]
});

Посмотрите, как работает на примере других источников: Яндекс, Google, рекламная кампания, email-рассылка, источник по умолчанию.

Параметры подмены

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

Что нужно знать технологу

Дистрибутив

Забрать из NPM:

npm install --save sb-placer

Bower:

bower install --save sb-placer

Или скачать репозиторий с GitHub и использовать один из файлов из папки /dist:

sb-placer.min.js — если нужна версия без зависимостей;
sb-placer.jquery.min.js — если нужно в формате jQuery-плагина.

Скачать с Github

Установка

Для установки скрипта на HTML-страницу, просто добавьте в <head>:


<script src="/path/to/sb-placer.min.js"></script>

<!-- jQuery -->
<script src="/path/to/jquery.min.js"></script>
<script src="/path/to/sb-placer.jquery.min.js"></script>

Также SB-Placer доступен как CommonJS / AMD модуль:

// Stand-alone
var sbPlacer = require('sb-placer');

// jQuery
var $ = require('jquery');
require('sb-placer/jquery');

После подключения библиотеки можно запускать подмену:

// Stand-alone
sbPlacer({
	/* настройки */
});

// jQuery
$('.sb-phone').sbPlacer({
	/* настройки */
});

Настройка

Рассмотрим процесс настройки на примере подмены телефонного номера в зависимости от рекламного источника посетителя.

Что нужно сделать, чтобы подмена произошла:

указать место в теле страницы (DOM-элемент) куда мы поместим подменяемый телефонный номер;
DOM-элемент
Первый этап — это указание DOM-элемента, в который скрипт подставит телефон. Этот шаг — единственное отличие в настройке jQuery-версии модуля от версии без зависимостей:
```
// Stand-alone
sbPlacer({
	/* настройки */
});

// jQuery
$('.sb-phone').sbPlacer({
	/* настройки */
});
```
В stand-alone версии DOM-элемент указывается через обязательный параметр targets. Значение этого параметра —.sb-phone — это обычный css-селектор. Он выбирает все DOM-элементы, у которых атрибут class=«sb-phone».

В jQuery-версии для указания элемента мы используем старый добрый jQuery-объект: $('.sb-phone'). В него поместим подменяемый телефон.

Проставьте элементу (или ряду элементов) класс sb-phone (или любой другой) и скрипт проставит телефоны во всех блоках с данным классом. Чтобы выбрать ряд разных элементов, укажите css-селекторы через запятую: '#phone,.sb-phone'.

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

Остальные параметры у двух версий модуля идентичны, поэтому дальше смотрим на примере jQuery-версии.
описать условия подмены и указать значение по умолчанию (которое подставим, если ни одно из условий подмены не выполнилось);
Условия подмены
Следующий шаг — передать скрипту условия подмены и значение по умолчанию, которое проставим, если ни одно из условий подмены не выполнилось:
```
// определяем текущий источник посетителя
var source = sbjs.get.current.src;

// магия!
$('.sb-phone').sbPlacer({
	default_value: '8-800-DEFAULT-PHONE',
		conditions: [
		  {
			  check: source,
			  when: 'yandex',
			  place: '8-800-YANDEX-PHONE'
		  },
		  {
			  check: source,
			  when: 'google',
			  place: '8-800-GOOGLE-PHONE'
		}
	]
});
```
default_value — String (может содержать html-теги)
Значение по умолчанию, которое проставится в том случае, если ни одного совпадения не было найдено.
Наличие обязательно.

conditions — Array of Objects
Условия, по которым происходит подмена.

Объект условия

check — String / Array of Strings
Параметр, который мы проверяем на соответствие. Например, источник посетителя.

when — String / Array of Strings / RegExp
Значения, по которым идет проверка. Например, источник 'yandex'. Чуть ниже рассмотрим применение разных типов значений.

place — String (может содержать html-теги)
То, что мы помещаем в элементы при условии найденного совпадения (check с when).

Все параметры обязательны.

В примере выше в первом объекте условий мы проверяем: если utm_source посетителя — yandex, то подставляем 8-800-YANDEX-PHONE.
Теперь пример интереснее:
```
$('.sb-phone').sbPlacer({
default_value: '8-800-DEFAULT-PHONE',
	conditions: [
		{
			check: source,
			when: ['yandex', 'begun'],
			place: '8-800-YANDEX-BEGUN-PHONE'
		},
		{
			check: source,
			when: 'google',
			place: '8-800-GOOGLE-PHONE'
		}
	]
});
```
Обратите внимание на первый объект: если source посетителя либо yandex, либо begun, то скрипт подставит 8-800-YANDEX-BEGUN-PHONE.
Ещё интереснее:
```
var source = sbjs.get.current.src,
	medium = sbjs.get.current.mdm;

$('.sb-phone').sbPlacer({
	default_value: '8-800-DEFAULT-PHONE',
		conditions: [
		{
			check: [source, medium],
			when: [['yandex', 'begun'], 'cpc'],
			place: '8-800-YANDEX-BEGUN-PHONE'
		},
		{
			check: [source, medium],
			when: ['google', 'cpc'],
			place: '8-800-GOOGLE-PHONE'
		}
	]
});
```
Значение check теперь массив [source, medium]. Это значит, что проверка будет идти по двум параметрам: source и medium. И только при совпадении обоих будет подставлено значение из place. С чем же будем сравнивать? С массивом when.

Кол-во объектов в массиве check должно совпадать с кол-вом объектов в массиве when!

Итак, скрипт сначала проверяет длины массивов check & when. Если они не совпадают, то условие пропускается. Если совпадают, то смотрим входит ли значение source в первый объект массива when — ['yandex', 'begun'], если да, то идет проверка является ли значение medium — cpc. Если оба условия выполнены, то подставляется значение 8-800-YANDEX-BEGUN-PHONE. Если хотя бы одно из условий не выполняется, то скрипт данное значение не подставляет и переходит к следующему объекту с условием.
И, наконец, RegExp:
```
var source   = sbjs.get.current.src,
	medium   = sbjs.get.current.mdm,
	campaign = sbjs.get.current.cmp;

$('.sb-phone').sbPlacer({
  default_value: '8-800-DEFAULT-PHONE',
  conditions: [
	{
	  check: [source, medium, campaign],
	  when: [['yandex', 'begun'], 'cpc', /^y_.*_poisk$/i],
	  place: '8-800-YANDEX-BEGUN-PHONE'
	},
	{
	  check: [source, medium, campaign],
	  when: [['google', 'facebook'], 'cpc', /^g_.*_poisk$/i],
	  place: '8-800-GOOGLE-FACEBOOK-PHONE'
	}
  ]
});
```
Всё работает так же, как в примере выше, но 3 объект в массиве when — это RegExp. Если campaign соответствует данному регулярному выражению, то подставляется значение из place.

Расположение на странице

SB-Placer взаимодействует с узлами DOM-дерева, поэтому расположение скрипта на странице относительно html-элементов имеет значение. Неважно где вы подключаете библиотеки и инициализируете скрипт — в <head> или <body> — важно как вы располагаете элементы относительно друг друга.

Самая распространённая ошибка — запустить функцию подмены раньше, чем в дереве страницы появится целевой DOM-элемент, в который должно подставиться значение:



<head>
  <script src="/path/to/sb-placer.jquery.min.js"></script>
  <script>
	// элемента с классом `sb-phone` ещё не существует
	$('.sb-phone').sbPlacer({ /* логика */ });
  </script>
</head>

<body>
  <!-- элемент появился, когда скрипт уже отработал -->  
  <div class="sb-phone"></div>
</body>

Есть 2 основных варианта размещения элементов:

1. Запустить подмену после появления целевого DOM-узла

Сначала загрузится узел, потом скрипт проставит в него значение:

<head>
  <script src="/path/to/sb-placer.jquery.min.js"></script>
</head>

<body>
  <div class="sb-phone"></div>
  <script>
	$('.sb-phone').sbPlacer({ /* логика */ });
  </script>
</body>

2. Регистрируем функцию подмены в качестве обработчика события

Мы говорим браузеру, чтобы он запустил функцию подмены по событию document.ready (то есть сразу после того, как всё DOM-дерево будет загружено):

<head>
  <script src="/path/to/sb-placer.jquery.min.js"></script>
  <script>
	$(document).ready(function() {
	  $('.sb-phone').sbPlacer({ /* логика */ });
	});
  </script>
</head>

<body>
  <div class="sb-phone"></div>
</body>

Необязательно вываливать настройки подмены в тело html-страницы. Можно поместить функцию во внешний js-файл и подключить его через <script>:

<head>
  <script src="/path/to/sb-placer.jquery.min.js"></script>
  <script src="/path/to/sb-placer-settings.js" ></script>
</head>

<body>
  <div class="sb-phone"></div>
</body>

jQuery версия

Теперь посмотрим на особенности использования jQuery-версии и версии без зависимостей:

<head>
  <!-- если мы будем использовать Sourcebuster - подключаем его -->
  <script src="/path/to/sourcebuster.min.js"></script>
  <script> sbjs.init(); </script>

  <!-- скрипт использует библиотеку jQuery - подключаем -->
  <script src="/path/to/jquery.min.js"></script>

  <!-- библиотека sbPlacer -->
  <script src="/path/to/sb-placer.jquery.min.js"></script>

  <!-- регистрируем функцию подмены в качестве обработчика события 
  `document.ready` -->
  <script>
	$(document).ready(function() {
	  $('.sb-phone').sbPlacer({ /* логика */ });
	});
  </script>
</head>

<body>
  <!-- целевой контейнер -->
  <div class="sb-phone"></div>
</body>

Версия без зависимостей

Поскольку метод $(document).ready принадлежит библиотеке jQuery, в stand-alone-версии мы либо располагаем функцию подмены после целевого контейнера, либо воспроизводим аналог $(document).ready на нативном JavaScript.

1. Располагаем функцию подмены после целевого элемента:

<head>
  <script src="/path/to/sourcebuster.min.js"></script>
  <script> sbjs.init(); </script>

  
  <script src="/path/to/sb-placer.min.js"></script>
</head>

<body>
  <!-- целевой контейнер -->
  <div class="sb-phone"></div>

  <!-- функция подмены -->
  <script>
	sbPlacer({
	  targets: '.sb-phone'
	  /* логика */ 
	});
  </script>
</body>

2. Используем аналог $(document).ready:

<head>
  <!-- если мы будем использовать Sourcebuster - подключаем его -->
  <script src="/path/to/sourcebuster.min.js"></script>
  <script> sbjs.init(); </script>

<!-- подключаем sbPlacer -->
  <script src="/path/to/sb-placer.min.js"></script>
</head>

<!-- функция подмены -->
  <script>

	// аналог `$(document).ready`
	function onDocumentReady(exec) {
	  if (document.readyState != 'loading') {
		exec();
	  } else if (document.addEventListener) {
		document.addEventListener('DOMContentLoaded', exec);
	  } else {
		document.attachEvent('onreadystatechange', function() {
		  if (document.readyState != 'loading') exec();
		});
	  }
	}

	// объявляем функцию подмены
	var place = function() {
	  sbPlacer({
		targets: '.sb-phone'
		/* логика */ 
	  });
	};

	// регистрируем обработчик
	onDocumentReady(place);

  </script>
</head>

<body>
  <!-- целевой контейнер -->
  <div class="sb-phone"></div>
</body>

Ссылки

Github

Скачать с Github

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