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-плагина.

Установка

Для установки скрипта на 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-элемента, в который скрипт подставит телефон. Этот шаг — единственное отличие в настройке 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 основных варианта размещения элементов:

Сначала загрузится узел, потом скрипт проставит в него значение:
<head>
  <script src="/path/to/sb-placer.jquery.min.js"></script>
</head>

<body>
  <div class="sb-phone"></div>
  <script>
	$('.sb-phone').sbPlacer({ /* логика */ });
  </script>
</body>
Мы говорим браузеру, чтобы он запустил функцию подмены по событию 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>

Ссылки

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