Методы JS API

В JS API счетчика имеются следующие методы:

Метод Описание
pageView отправка хита просмотра страницы
reachGoal отправка достижения цели
sendEvent отправка произвольного события
itemView отправка параметров динамического ретаргетинга
onready вызов callback-функции по окончанию инициализации кода счетчика
setUserParams установка произвольных параметров пользователя
deleteUserParams очистка произвольных параметров пользователя
getUserParams получение установленных произвольных параметров пользователя
setUserID установка идентификатора посетителя на сайте
deleteUserID удаление идентификатора посетителя на сайте
getUserID получение идентификатора посетителя на сайте
getClientID получение встроенного идентификатора посетителя на сайте

Большинство методов можно вызывать двумя способами:

  • через метод _tmr.push. Методу передается javascript-объект с обязательным указанием типа метода, например, _tmr.push({ type: "pageView", ... });
  • через вызов метода объекта _tmr, например, _tmr.pageView({...});

Второй способ вызова метода работает только если основной (асинхронный) код счетчика уже загружен. Если нет уверенности, что в конкретный момент счетчик уже доступен, рекомендуется использовать первый способ следующим образом:

var _tmr = window._tmr || (window._tmr = []);
_tmr.push({ type: "pageView", ... });

При вызове метода указывается javascript-объект с обязательными и дополнительными параметрами. При отсутствии обязательных параметров вызов будет проигнорирован.

Общие поля для методов

Данные поля могут передаваться в методах отправки хитов типа pageView, reachGoal, sendEvent, itemView.

Название поля Тип значения Описание Значение по умолчанию Примечание
id число ID счетчика, на который отсылается хит. Может быть опущен, если ранее указывался ID в другом хите. Первое указанное значение идентификатора в любом из хитов. Обязателен к указанию хотя бы в одном из хитов. Тогда это значение будет считаться значением по умолчанию в случаях когда ID счетчика не указан.
url строка URL страницы. location.href Применяется для указания корректного URL для AJAX-страниц или формирования “виртуальных” просмотров.
referrer строка Referrer страницы. document.referrer
title строка Заголовок страницы. document.title
device строка (без управляющих символов) Идентификатор устройства (device id) посетителя (android id, idfa, …)
userid строка (без управляющих символов) Идентификатор посетителя (profile id) на сайте, если у сайта есть собственная идентификация посетителей. Ранее назывался pid.
gender 1 = мужчины, 2 = женщины Пол посетителя. В случае указания будет иметь приоритет при подсчете статистики над данными Мэйл.ру
age число от 1 до 127 Возраст посетителя. В случае указания будет иметь приоритет при подсчете статистики над данными Мэйл.ру
params javascript-объект (соответствующий JSON-формату) или ссылка на него Произвольные параметры хита.
version строка Версия сайта.

Методы

pageView (просмотр страницы)

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

_tmr.pageView({ id: "ВАШ ID" });

_tmr.push({ id: "ВАШ ID", type: "pageView" });

reachGoal (достижение цели)

Дополнительные поля

Название поля Тип значения Описание Примечание
Обязательные поля
goal строка Название цели, которая была достигнута.
Опциональные поля
value число Ценность достигнутой цели. Параметр value будет просуммирован для каждой уникальной цели.

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

_tmr.reachGoal({ id: "ВАШ ID", goal: "addProduct", value: 2 });

_tmr.push({ id: "ВАШ ID", type: "reachGoal", goal: "addProduct", value: 2 });

sendEvent (произвольное событие)

Дополнительные поля

Название поля Тип значения Описание Примечание
Обязательные поля
category строка Категория события. Категории начинающиеся с символа подчеркивания зарезервированы для нужд сервиса и отображаться в статистике не будут
action строка Действие.
Опциональные поля
label строка Дополнительная информация о событии.
value число Ценность собятия. Параметр value будет просуммирован для каждой уникальной комбинации category + action + label.

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

_tmr.sendEvent({ id: "ВАШ ID", category: "userflow", action: "readArticle", label: "about" });

_tmr.push({ id: "ВАШ ID", type: "sendEvent", category: "userflow", action: "readArticle", label: "about" });

itemView (динамический ретаргетинг)

Дополнительные поля

Название поля Тип значения Описание
Опциональные поля
list число Идентификатор фида.
productid число Идентификатор товара.
pagetype строка Тип страницы.
totalvalue число Сумма.

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

_tmr.itemView({ id: "ВАШ ID", list: 1, productid: 105, pagetype: "detail", totalvalue: 3400 });

_tmr.push({ id: "ВАШ ID", type: "itemView", list: 1, productid: 105, pagetype: "detail", totalvalue: 3400 });

onready (callback-функция готовности кода счетчика)

Задание callback-функции возможно только через метод _tmr.push, т.к. именно этот метод дает возможность выполнения действия в момент времени, когда код счетчика загружен и гарантированно проинициализирован, после чего становятся доступны методы, недоступные через _tmr.push.

Дополнительные поля

Название поля Тип значения Описание
Обязательные поля
callback javascript-функция или ссылка на неё Функция, которая будет выполнена после того, как завершится инициализация кода счетчика.
Опциональные поля
context javascript-объект или ссылка на него Контекст выполнения callback-функции, который будет доступен в коде этой функции через служебное слово this.

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

var _tmr = window._tmr || (window._tmr = []);
_tmr.push({
    type: 'onready',
    callback: function() {
        // здесь ваш код работы callback-функции
    }
});

Параметры пользователя (User params)

В качестве параметров пользователя (USER_PARAMS) служит javascript-объект (соответствующий JSON-формату, т.е. значениями полей являются примитивные значения или такие же JSON-подобные вложенные объекты, а так же массивы примитивных значений, JSON-объектов и вложенных массивов). При установке или получении параметров пользователя javascript-объект будет скопирован по значению, а не по ссылке. Т.е. при изменении объекта через ссылку параметры пользователя изменены не будут.

setUserParams (установка)

_tmr.setUserParams(USER_PARAMS);
аргумент USER_PARAMS - javascript-объект, обязательный аргумент при установке параметров пользователя; при его отсутствии параметры пользователя будут удалены
_tmr.push({ type: "setUserParams", params: USER_PARAMS });
поле params - обязательное поле при вызове установки параметров пользователя через метод _tmr.push
поле USER_PARAMS - javascript-объект

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

_tmr.setUserParams({ group: "reader", since: "24.03.2019" });

_tmr.push({ type: "setUserParams", params: { group: "editor", since: "13.08.2017", posts: 37 } });

deleteUserParams (удаление)

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

_tmr.deleteUserParams();

_tmr.push({ type: "deleteUserParams" });

Так же удаление параметров пользователя произойдет если не передавать их при вызове методов установки или передать вместо них null, false или undefined (Важно. При вызове метода через _tmr.push поле params обязательное, т.о. при его отсутствии вызов будет проигнорирован):

_tmr.setUserParams();

_tmr.setUserParams(null);

_tmr.setUserParams(false);

_tmr.setUserParams(undefined);

_tmr.push({ type: "setUserParams", params: null });

_tmr.push({ type: "setUserParams", params: false });

_tmr.push({ type: "setUserParams", params: undefined });

getUserParams (получение)

Т.к. результатом вызова является получаемое значение, то вызов через метод _tmr.push не доступен. Следовательно, получить параметры пользователя можно только тогда, когда вы уверены что код счетчика уже готов к работе (например, использовать для этого callback-функцию onready).

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

var USER_PARAMS = _tmr.getUserParams();

var _tmr = window._tmr || (window._tmr = []);
_tmr.push({ type: "onready", callback: function() {
    var USER_PARAMS = _tmr.getUserParams();
    // здесь ваш код работы с User params
} });

USER_PARAMS - javascript-объект (или undefined если параметры пользователя не были установлены или были удалены)

Идентификатор пользователя

В качестве идентификатора пользователя (USER_ID) служит строка или число.

setUserID (установка)

_tmr.setUserID(USER_ID);
аргумент USER_ID - строка или число, обязательный аргумент при установке идентификатора пользователя; при его отсутствии идентификатор пользователя будет удален

_tmr.push({ type: "setUserID", userid: USER_ID });
поле userid - обязательное поле при вызове установки идентификатора пользователя через метод _tmr.push
поле USER_ID - строка или число

deleteUserID (удаление)

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

_tmr.deleteUserID();

_tmr.push({ type: "deleteUserID" });

Так же удаление идентификатора пользователя произойдет если не передавать его при вызове методов установки или передать вместо него null, false или undefined (Важно. При вызове метода через _tmr.push поле userid обязательное, т.о. при его отсутствии вызов будет проигнорирован):

_tmr.setUserID();

_tmr.setUserID(null);

_tmr.setUserID(false);

_tmr.setUserID(undefined);

_tmr.push({ type: "setUserID", userid: null });

_tmr.push({ type: "setUserID", userid: false });

_tmr.push({ type: "setUserID", userid: undefined });

getUserID (получение)

Т.к. результатом вызова является получаемое значение, то вызов через метод _tmr.push не доступен. Следовательно, получить идентификатор пользователя можно только тогда, когда вы уверены что код счетчика уже готов к работе (например, использовать для этого callback-функцию onready).

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

var USER_ID = _tmr.getUserID();

var _tmr = window._tmr || (window._tmr = []);
_tmr.push({ type: "onready", callback: function() {
    var USER_ID = _tmr.getUserID();
    // здесь ваш код работы с UserID
} });

USER_ID - строка или число (или undefined если идентификатор пользователя не был установлен или был удален)

Встроенный идентификатор пользователя

Код счетчика сам автоматически создает и устанавливает встроенный идентификатор пользователя (ClientID, строка) для каждого посетителя вашего сайта.

getClientID (получение)

Т.к. результатом вызова является получаемое значение, а так же тот факт, что встроенный идентификатор пользователя создается и устанавливается кодом счетчика, то вызов через метод _tmr.push не доступен. Следовательно, получить встроенный идентификатор пользователя можно только тогда, когда вы уверены что код счетчика уже готов к работе (например, использовать для этого callback-функцию onready).

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

var CLIENT_ID = _tmr.getClientID();

var _tmr = window._tmr || (window._tmr = []);
_tmr.push({ type: "onready", callback: function() {
    var CLIENT_ID = _tmr.getClientID();
    // здесь ваш код работы с ClientID
} });

CLIENT_ID - строка