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. Объект параметров состоит из следующих полей:

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

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	Параметр, означающий на какой домен назначать куки. Регулирует работу коллтрекинга на кроссдоменных сайтах

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

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

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

При помощи 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 код номера должен быть таким:

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:
1. getNumber() - выделяет номер ДКТ по запросу. Выделенные номера принадлежат региону по умолчанию, заданному в настройках коллтрекинга.

function getNumber(options, callback)

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

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

options	IOptions \| string	optional	Параметры или идентификатор запроса (должен быть постоянным хотя бы в рамках сессии)
callback	function	optional	Функция обратного вызова, в которую передается результат выделения номера

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

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

number	string	номер, выделенный для пользователя, в формате DID
type	number	тип номера: 1 - динамический, 2 - статический, 3 - по умолчанию
hash	string	хеш номера, если не был указан, то пустая строка

Пример использования объекта IOptions:

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

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

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

hash	string	Идентификатор запроса
redirectNumber	string	Номер на который будет переведён звонок
regionCode	string	Код региона в ISO формате, например для Татарстана 'TA'

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

mgo.getNumber('test', function(e) {
    console.log(e);
});

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

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

{number: '79158888888', type: 1, hash: 'test'}

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

function getNumberByRegion(regionCode, hash, callback)

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

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

regionCode	string	optional	Код региона в ISO формате (например, для Татарстана 'TA')
hash	string	optional	Идентификатор запроса (должен быть постоянным хотя бы в рамках сессии)
callback	function	optional	Функция обратного вызова, в которую передается результат выделения номера

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

mgo.getNumberByRegion('TA', 'test', function(e) { console.log(e); });

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

{number: '79158888888'}

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

function getExistsNumbers(callback)

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

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

callback	function	optional	Функция обратного вызова, в которую передается результат выделения номера

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

mgo.getExistsNumbers(function(e) { console.log(e); });

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

[{number: '79158888888'}, {hash: 'test', number: '79158888887'}]

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

function postForm(form)

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

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

name	string	optional	Имя пользователя
number	string	optional	Номер телефона пользователя (в формате 79451112233)
email	string	optional	Электронный адрес пользователя
customParam	string	optional	Произвольный параметр, который будет передаваться в выгрузку заявок

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

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>