Библиотека для API динамического коллтрекинга от MANGO OFFICE

Установка

npm install mango-dct

Требования

NodeJS версии 8 или более

Токен

Токен можно задать через переменную process.env.TOKEN

Или передать первый аргумент в конструктор new MangoDct('your-token-here', 'your-widget-id');

ID виджета

ID виджета можно задать через переменную process.env.WID

Или передать второй аргумент в конструктор new MangoDct('your-token-here', 'your-widget-id');

Пример использования

const MangoDct = require('mango-dct');
const dct = new MangoDct();

async function main() {
    const parameters = {
        lastDays: 31,
        utmSource: 'yandex.ru',
        utmMedium: 'cpc',
        utmCampaign: 'skidka50'
    };

    const calls = await dct.calls(parameters);
    console.log('выгруженные звонки', calls);
}
main();

Все примеры

класс MangoDct

Создание нового экземпляра

new MangoDct('your-token-here', 'your-widget-id');

| Аргумент | Тип | Описание| | ------------ | ------------ |------------ | | token | string | токен | | wid | string | идентификатор виджета |

метод calls

Данный метод возвращает список звонков на все подменные номера (включая номера статических каналов) за определенный промежуток времени. Список отсортирован по убыванию.

MangoDct.calls(options); // => Promise<any[]>

| Аргумент | Тип | Описание| | ------------ | ------------ |------------ | | options | object | Объект содержит фильтры выгрузки |

Период выгрузки можно задать несколькими способами:

// за последний 31 день
MangoDct.calls({ lastDays: '31' });

или

// с 01 июня 2016 по 30 июня 2016
MangoDct.calls({ dateStart: '2017-06-01T00:00', dateEnd: '2017-06-30T00:00Z' });

или

// за вчера
MangoDct.calls({ yesterday: true })

или

// за сегодня
MangoDct.calls({ today: true })

Возможные фильтры:

| Название| Обязательность | Тип | Описание | Значение по умолчанию| | ------------ | ------------ | ------------ | ------------ | ------------ | | dateStart | required | string | дата и время в формате ISO 8601| | | dateEnd | required | string | дата и время формате ISO 8601 | | | callType | optional | number | Тип звонка: 0 - динамические и статические, 1 - динамические, 2 - статические, 3 - дефолтные | 0 | | isNew | optional | number | Флаг нового звонка: 0 - все звонки, 1 - только новые | 0 | | isQuality | optional | number | Флаг качественного звонка: 0 - все звонки, 1 - только качественные | 0 | | utmSource | optional | string | Источник | | | utmMedium | optional | string | Канал | | | utmCampaign | optional | string | Кампания | | | utmContent | optional | string | Содержание | | | utmTerm | optional | string | Ключевое слово | | |

По-умолчанию для выгрузки используется формат json. Для записи звонков в csv файл небходимо задать свойство options.csv :

MangoDct.calls({ today: true, csv: 'C:/mango-dct/downloads/calls.csv' });

метод createWebhook

Создает вебхук для прослушивания событий

MangoDct.createWebhook(url); // => Webhooks

| Аргумент | Тип | Описание| | ------------ | ------------ |------------ | | url | string | url адрес вебхука |

Пример использования:

const MangoDct = require('mango-dct');
const app = require('express')();
const dct = new MangoDct();

// создание  вебхуков
const webhook1 = dct.createWebhook('/mango-dct/webhook1');
const webhook2 = dct.createWebhook('/mango-dct/webhook2');
const webhook3 = dct.createWebhook('/mango-dct/webhook3');

// прослушивание вебхуков
webhook1.on('data', e => console.log('on webhook1', e));
webhook2.on('data', e => console.log('on webhook2', e));
webhook3.on('data', e => console.log('on webhook3', e));

// прослушивание событий от всех вебхуков
dct.allHooks.on('data', e => console.log('on any webhook', e));

// регистрация обработчиков
app.use(webhook1.handler);
app.use(webhook2.handler);
app.use(webhook3.handler);

app.use((req, res) => res.status(404).send({ error: 'not found' }));
app.listen(8080);

Класс Webhooks наследуется от EventEmmitter

свойство allHooks

Слушает события от всех созданных вебхуков

MangoDct.allHooks;  // => EventEmmitter<any>

Пример:

dct.allHooks.on('data', e => console.log('on any webhook', e));

метод transform

Настраивает параметры для преобразования получаемых данных. Преобразование будет использоваться для метода calls и вебхуков.

MangoDct.transform(options);  // => void

| Аргумент | Тип | Описание| | ------------ | ------------ |------------ | | options | object | объект с параметрами |

Пример использования:

dct.transform({ callStatus: true });

Возможные преобразования:

| Аргумент | Тип | Описание| | ------------ | ------------ |------------ | | callStatus | boolean | добавляет свойство callTextStatus - текстовое значение статуса завершения звонка (callStatus). Например, при наличии свойства callStatus: 1110 будет добавлено свойство callTextStatus: 'Вызов завершен вызывающим абонентом' |

класс Webhooks

Класс для создания обработчика вебхука

const webhook = new Webhooks(pathname, dct);

| Аргумент | Тип | Описание| | ------------ | ------------ |------------ | | pathname | string | адрес для прослушивания вебхука | | dct | MangoDct | экземпляр класса MangoDct |

свойство handler

Создает и возвращает функцию-обработчик для express

webhook.handler // => Function

метод hear

Слушает события вебхука по заданному фильтру

webhook.hear(filter, handler);

| Аргумент | Тип | Описание| | ------------ | ------------ |------------ | | filter | object | объект с параметрами для фильтра событий | | handler | function | колбэк функция |

Пример использования:

webhook.hear({ callType: 1 }, e => console.log('on callType 1', e));
webhook.hear({ device: /tablet|desktop/i }, e => console.log('on  tablet or desktop device', e));
webhook.hear({ callerNumber: /^7495/  }, e => console.log('on 7495 mask phone number', e));
webhook.hear({ duration: /^[1-9]\d+/, utmMedium: 'cpc'  }, e => console.log('on duration >= 10 seconds and  utmMedium=cpc ', e));

Отладка

Для логирования запросов calls необходимо задать переменную process.env.DEBUG=mango-dct:calls

Пример лога:

mango-dct:calls <- GET https://widgets-api.mango-office.ru/v1/calltracking/224/calls?utmSource=yandex.ru&utmMedium=cpc&utmCampaign=skidka50&dateStart=2017-12-08T19:44Z&dateEnd=2018-01-08T19:44Z +0ms

Для логирования вебхуков необходимо задать переменную process.env.DEBUG=mango-dct:webhooks

Пример лога:

mango-dct:webhooks -> GET /mango-dct/webhook3?utm_source=yandex +15s

Для логирования запросов calls и вебхуков необходимо задать переменную process.env.DEBUG=mango-dct:*