JavaScript API. Описание методов

JavaScript API - это методы программного интерфейса, предназначенные для динамического взаимодействия клиента с кодом приложения. Ниже мы рассмотрим все методы JS API, реализованные на данный момент, с примерами кода. Если Вам интересно узнать о типичных случаях использования JS API, читайте эту статью.

Загрузка скрипта mango.js

Прежде чем использовать API коллтрекинга, необходимо загрузить JS-скрипт. Это осуществляется асинхронным образом с помощью следующего кода. Код лучше вставлять в конце страницы внутри тега <script> перед закрывающим тегом </body>:

(function(w, d, u, i, o, s, p) {
   if (d.getElementById(i)) { return; } w['MangoObject'] = o;
   w[o] = w[o] || function() { (w[o].q = w[o].q || []).push(arguments) };
   w[o].u = u; w[o].t = 1 * new Date();
   s = d.createElement('script'); s.async = 1; s.id = i; s.src = u;
   p = d.getElementsByTagName('script')[0]; p.parentNode.insertBefore(s, p);
}(window, document, '//widgets.mango-office.ru/widgets/mango.js', 'mango-js', 'mgo'));

Последний параметр в последней строке задаёт название для основного объекта API. Название можно поменять, если оно конфликтует с другими объектами на сайте.

Основной объект mgo

После выполнения представленного кода становится доступным объект-функция mgo, который является центральной точной для обращения к API.

Название виджета: calltracking. Объект параметров состоит из следующих полей:

Название	Тип	Опциональность	Описание	По умолчанию

Как использовать объект-функцию?

Использовать его можно тремя способами.

Объявить виджет. Возможные варианты

При помощи mgo Вы можете объявить некоторый виджет. Обобщенный пример

mgo({
calltracking: { /* widget params */ }
});

Примеры:
1.1 Простой виджет

mgo({
calltracking: {
id: 12345,
elements: [{selector: '#some-element'}],
}
});

1.2 Подстановка номера в два элемента mgo({
calltracking: {
id: 12345,
elements: [
{selector: '#some-element'},
{selector: '.some-other-element'}
],
}
});

1.3 Ручное форматирование номера mgo({
calltracking: {
id: 12345,
elements: [{selector: '#some-element'}],
formatNumber: function(number) {
// '74951112233' => '7<span>495</span>111-22-33'
return number.substr(0, 1) + '<span>' + number.substr(1, 3) + '</span>' + number.substr(4, 3) + '-' + number.substr(7, 2) + '-' + number.substr(9, 2);
},
}
});

1.4 Ручная обработка номераУстановка атрибута tel:.
mgo({
calltracking: {
id: 12345,
elements: [{selector: '#mango-calltracking'}],
onReady: function(event) {
$('#mango-calltracking').attr('href', 'tel:' + event.number);
},
}
}) ;

При этом html код номера должен быть таким:
<a id="mango-calltracking" href="tel:79990001122">8 (999) 000-11-22</a>

1.5 Добавление кастомного параметра mgo({
calltracking: {
id: 12345,
elements: [{selector: '#some-element'}],
customParam: 'my_user_id=123,my_project_id=456'
}
});

1.6 Добавление региона показа номера mgo({
calltracking: {
id: 12345,
elements: [{selector: '#some-element'}],
region: 'MOW'
}
});

1.7 Изменение текстового номера на сайте mgo({
calltracking: {
id: 12345,
elements: [{numberText: '79990001122'}]
}
});

1.8 Кроссдоменное использование виджета коллтрекинга
mgo({
calltracking: {
id: 12345,
elements: [{selector: '#some-element'}],
domain: 'romasha.ru'
}
});

Будет одинаково работать на всех поддоменах вида romasha.ru, msk.romasha.ru, spb.romasha.ru и т.п.

2. Вызов методов API:
mgo(function(mgo) {
mgo.someMethod();
});

Методы JS API

Вы можете использовать следующие методы JS API:

getNumber() - выделяет номер ДКТ по запросу. Выделенные номера принадлежат региону по умолчанию, заданному в настройках коллтрекинга.
function getNumber(options, callback)

Параметры метода:

Название	Тип данных	Опциональность	Описание

Параметры объекта передаваемого в callback:

Название	Тип	Описание

Пример использования объекта IOptions: {
hash?: string; // идентификатор запроса
redirectNumber?: string; // номер на который будет переведён звонок
regionCode?: string; // код региона в ISO формате, например для Татарстана 'TA'
}

Параметры объекта передаваемого в options:

Название	Тип	Описание

Пример вызова метода mgo.getNumber('test', function(e) {
console.log(e);
});

mgo.getNumber({
hash: 'test',
redirectNumber: '79876543210'
}, function(e) {
console.log(e);
});

Пример ответа

getNumberByRegion() - выделяет номер ДКТ по запросу для конкретного региона. Для выделения номера для определенного региона, в настройках виджета должна быть включена услуга Mультирегиональность.
function getNumberByRegion(regionCode, hash, callback)

Параметры метода:

Название	Тип данных	Опциональность	Описание

Пример вызова метода mgo.getNumberByRegion('TA', 'test', function(e) { console.log(e); });

Пример ответа

getExistsNumbers() - метод возвращает список номеров, закрепленных за посетителем сайта (сессией) function getExistsNumbers(callback)

Параметры метода:

Название	Тип данных	Опциональность	Описание

Пример вызова метода mgo.getExistsNumbers(function(e) { console.log(e); });

Пример ответа [{number: '79158888888'}, {hash: 'test', number: '79158888887'}]

postForm() - передача данных из формы на сайте в отчёты коллтрекинга. Этот метод рекомендуется вызывать при отправке формы в событии onsubmit. function postForm(form)

Параметры метода: в качестве параметра принимает объект формы со следующими полями

Название	Тип данных	Опциональность	Описание

Пример вызова метода:

mgo.postForm({name: 'Иван', email: '<ivan@mail.ru>'});

Пример формы с полями:

<form onsubmit="submitHandler()">
  <input id="username" type="text">
  <input id="email" type="text">
  <input value="Оставить заявку" type="submit">
</form>

<script>
  function submitHandler() {
    mgo.postForm({
      name: document.getElementById('username').value
      email: document.getElementById('email').value
    });
  }
</script>