@astral/yandex-metrika

Библиотека для взаимодействия с Яндекс.Метрикой

Table of contents

• Installation
• Добавление скрипта в html
• Basic usage
  • init
  • reachGoal
  • addUserInfo
  • addParams
  • hit
  • [getCurrentSessionVisorListUrl](#getCurrentSessionVisorListUrl]
• Custom reachGoal

Installation

npm i --save @astral/yandex-metrika

yarn add @astral/yandex-metrika

Добавление скрипта в html

(function(m,e,t,r,i,k,a){m[i]=m[i]||function(){(m[i].a=m[i].a||[]).push(arguments)};
m[i].l=1*new Date();k=e.createElement(t),a=e.getElementsByTagName(t)[0],k.async=1,k.src=r,a.parentNode.insertBefore(k,a)})
(window, document, "script", "https://mc.yandex.ru/metrika/tag.js", "ym");

Methods

init

Инициализация сервиса метрики.

import { YandexMetrika } from '@astral/yandex-metrika';

const yandexMetrika = new YandexMetrika();

yandexMetrika.init({ 
  enabled: process.env.IS_PRODUCTION,
  counterID: 'XXXXXX',
  onError: sentry.captureException
})

По-умолчанию установлены параметры:

clickmap: true;
trackLinks: true;
accurateTrackBounce: true;
webvisor: true;

reachGoal

Метод достижения цели.

yandexMetrika.reachGoal({ 
  extra: { customParam: 'value' },
  target: 'XXXXXX',
  onSuccess: () => console.info('success') 
})

addUserInfo

Метод, позволяющий к счетчику добавить произвольные пользовательские данные.

yandexMetrika.addUserInfo({ 
  userID: 'id',
  email: '[email protected]',
  ...
})

addParams

Метод, позволяющий передать произвольные параметры визита.

yandexMetrika.addParams({ 
  param1: 'value1',
  param2: 'value2',
  ...
})

hit

Метод, позволяющий передать событие посещения страницы.

Может использоваться в случаях, когда Яндекс.Метрика по каким-то причинам не отправляет событие о посещении страниц в автоматическом режиме.

Предполагается использование при каждом обновлении pathname в URL вашего приложения

getCurrentSessionVisorListUrl

Возвращает ссылку на записи Вебвизора текущего пользователя на текущую дату.

Можно передавать в UXFeedback для быстрого перехода на запись Вебвизор.

Пример:

yandexMetrika.init({
  enabled: process.env.IS_PRODUCTION,
  counterID: '111',
  onError: sentry.captureException
})

const url = await yandexMetrika.getCurrentSessionVisorListUrl();

window.UXS.addProperties({
  yandexWebvisorUrl: url,
});

Пример ссылки: https://metrika.yandex.ru/stat/visor?period=2025-06-22:2025-06-22&filter=(EXISTS+ym:u:userID+WITH+(ym:u:clientID==%27222%27))&id=111

Если сервис не быд включен (enabled), то метод вернет пустую строку.

Событие о посещении текущей страницы

yandexMetrika.hit()

Событие о посещении текущей страницы с параметрами

yandexMetrika.hit('', {
  callback: () => ({}),
  ...
})

Событие о посещении любой страницы

yandexMetrika.hit('https://example.com/test')

Custom reachGoal

type SuccessSignGoalParams = {
  signID: string;
  status: string;
};

class Metrics extends YandexMetrics {
  constructor() {
    super();
  }

  /**
   * @description Цель, указывающее на успешное подписание
   */
  successSignGoal = (params: SuccessSignGoalParams) => {
    this.reachGoal('sign-target', params);
  };
}

const metrics = new Metrics();

metrics.successSignGoal({ signID: '123', status: 'success' });