JavaScript 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
. Объект параметров состоит из следующих полей:
Название |
Тип |
Опциональность |
Описание |
По умолчанию |
id |
number |
required |
Идентификатор виджета. Где узнать id-номер виджета, Вы можете узнать в этой статье. |
|
elements |
array<object> |
optional |
Массив элементов на странице для подстановки номера. |
[] |
> selector |
string |
optional |
Селектор элемента, например '#elem' или '.cls'. (Один из параметров обязателен.) |
|
> numberText |
string |
optional |
Номер телефона для изменения на сайте в формате 79990001122. (Один из параметров обязателен.) |
|
region |
string |
optional |
Код Iso региона (например для Москвы 'MOW'), показ номеров из определенного региона. |
|
onReady |
function(object) |
optional |
Коллбэк, вызываемый в момент получения номера. |
|
formatNumber |
function(string) |
optional |
Функция для специфического форматирования номера, может возвращать HTML. |
|
visitEvents |
boolean |
optional |
Определяет нужно ли отправлять в Google Analytics события о выделении номеров (dynamic visit и т.п.). |
false |
customParam |
string |
optional |
Дополнительный параметр, который передаётся в выгрузку звонков и в вебхуки (ограничение по длине 100 символов) |
|
domain |
string |
optional |
Параметр, означающий на какой домен назначать куки. Регулирует работу коллтрекинга на кроссдоменных сайтах |
|
Как использовать объект-функцию?
Использовать его можно тремя способами.Объявить виджет. Возможные варианты
calltracking: { /* widget params */ }
});
Примеры:
calltracking: {
id: 12345,
elements: [{selector: '#some-element'}],
}
});
1.2 Подстановка номера в два элемента
calltracking: {
id: 12345,
elements: [
{selector: '#some-element'},
{selector: '.some-other-element'}
],
}
});
1.3 Ручное форматирование номера
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:.
calltracking: {
id: 12345,
elements: [{selector: '#mango-calltracking'}],
onReady: function(event) {
$('#mango-calltracking').attr('href', 'tel:' + event.number);
},
}
}) ;
При этом
html
код номера должен быть таким:1.5 Добавление кастомного параметра
calltracking: {
id: 12345,
elements: [{selector: '#some-element'}],
customParam: 'my_user_id=123,my_project_id=456'
}
});
1.6 Добавление региона показа номера
calltracking: {
id: 12345,
elements: [{selector: '#some-element'}],
region: 'MOW'
}
});
1.7 Изменение текстового номера на сайте
calltracking: {
id: 12345,
elements: [{numberText: '79990001122'}]
}
});
1.8 Кроссдоменное использование виджета коллтрекинга
calltracking: {
id: 12345,
elements: [{selector: '#some-element'}],
domain: 'romasha.ru'
}
});
Будет одинаково работать на всех поддоменах вида romasha.ru, msk.romasha.ru, spb.romasha.ru и т.п.
2. Вызов методов API:
mgo.someMethod();
});
Методы JS API
Вы можете использовать следующие методы JS API:1. getNumber() - выделяет номер ДКТ по запросу. Выделенные номера принадлежат региону по умолчанию, заданному в настройках коллтрекинга.
Параметры метода:
Название | Тип данных | Опциональность | Описание |
---|---|---|---|
options | IOptions | string | optional | Параметры или идентификатор запроса (должен быть постоянным хотя бы в рамках сессии) |
callback | function | optional | Функция обратного вызова, в которую передается результат выделения номера |
Название | Тип | Описание |
number |
string |
номер, выделенный для пользователя, в формате DID |
type |
number |
тип номера: 1 - динамический, 2 - статический, 3 - по умолчанию |
hash |
string |
хеш номера, если не был указан, то пустая строка |
hash?: string; // идентификатор запроса
redirectNumber?: string; // номер на который будет переведён звонок
regionCode?: string; // код региона в ISO формате, например для Татарстана 'TA'
}
Параметры объекта передаваемого в options:
Название | Тип | Описание |
hash |
string |
Идентификатор запроса |
redirectNumber |
string |
Номер на который будет переведён звонок |
regionCode |
string |
Код региона в ISO формате, например для Татарстана 'TA' |
console.log(e);
});
mgo.getNumber({
hash: 'test',
redirectNumber: '79876543210'
}, function(e) {
console.log(e);
});
Пример ответа
2. getNumberByRegion() - выделяет номер ДКТ по запросу для конкретного региона. Для выделения номера для определенного региона, в настройках виджета должна быть включена услуга Mультирегиональность.
Параметры метода:
Название | Тип данных | Опциональность | Описание |
---|---|---|---|
regionCode | string | optional | Код региона в ISO формате (например, для Татарстана 'TA') |
hash | string | optional | Идентификатор запроса (должен быть постоянным хотя бы в рамках сессии) |
callback | function | optional | Функция обратного вызова, в которую передается результат выделения номера |
Пример ответа
3. getExistsNumbers() - метод возвращает список номеров, закрепленных за посетителем сайта (сессией)
Параметры метода:
Название | Тип данных | Опциональность | Описание |
---|---|---|---|
callback | function | optional | Функция обратного вызова, в которую передается результат выделения номера |
Пример ответа
4. postForm() - передача данных из формы на сайте в отчёты коллтрекинга. Этот метод рекомендуется вызывать при отправке формы в событии onsubmit.
Параметры метода: в качестве параметра принимает объект формы со следующими полями
Название | Тип данных | Опциональность | Описание |
---|---|---|---|
name | string | optional | Имя пользователя |
number | string | optional | Номер телефона пользователя (в формате 79451112233) |
string | optional | Электронный адрес пользователя | |
customParam | string | optional | Произвольный параметр, который будет передаваться в выгрузку заявок |
Пример формы с полями
<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>