Yandex Metrica Tag

The async module provides several utilities for managing asynchronous execution:

• async.ts: Provides runAsync for deferred execution in the next tick.
• executor.ts: Provides executeIterator to add tasks to a shared queue.
• helpers.ts: Provides iterateTaskWithConstraints, which wraps executeIterator.
• iterator.ts: A collection of iterators.
• task.ts: Defines the core task interface and logic.

The Metrica tag architecture relies on a global lifecycle:

• GlobalStorage: Created automatically when the script is parsed. It is shared by all counters on a page, contains common data, and facilitates inter-counter communication (e.g., via semaphores for actions that should only run once per page).
• Mappings: Define the relationship between providers and their execution chain. Specifically, they map which Sender, Middleware, and Transport combination should be used with each Provider.

The api folder defines the communication layer with the server. The architecture is organized by routes, where each subfolder (excluding common) represents a specific server route.

Key architectural rules:

• Route Isolation: Code outside the api folder should import variables from the specific route folder they need to interact with, rather than from common.
• Common Definitions: The common folder is reserved for shared parameters used by multiple routes. Only route folders should import from common.
• Exceptions: Very common constants (e.g., TRANSPORT_ID_BR_KEY) may be used by the transport layer regardless of the specific route being called.

The API uses internal key-value storages that are serialized into single strings to be sent as URL parameters. This minimizes the number of parameters in a request.

• browserInfo: Serialized into the browser-info URL parameter. It stores data related to the page, user, and visit.
• telemetry: Serialized into the t URL parameter. It stores logging and debugging information.

When a request is made, it follows a specific pipeline through four main stages:

1. Provider: Gathers basic information from the page/browser, subscribes to user or DOM events, parses event data, and triggers a sender.
2. Sender: Sets basic request information, defines the backend endpoint, and establishes common parameters.
3. Middlewares: Appends additional useful information to the request data.
4. Transport: Iterates through available transports until the request is successfully delivered to the backend.

A task is the fundamental unit of execution in this module, acting as a functional alternative to a Promise. Unlike standard Promise objects which reside in the MicroTaskQueue (potentially blocking UI rendering and user events), tasks are executed using setDefer. This places them in the MacroTaskQueue, allowing them to run alongside other browser events and ensuring they do not degrade the website's responsiveness or interface performance.

A task is initialized with an execution function of the type: (reject, resolve) => void.

To use Metrica tag, you must first install the dependencies and build the script. The project requires Node.js. The build output is a single file located at _build/public/watch.js.

# Install Node.js version if using nvm
nvm install

# Install dependencies
npm ci

# Build the production script (uglified)
npm run build

# Build the raw script (for debugging, no uglification)
npm run build:raw

A Metrica counter can be initialized in two ways:

1. Direct Constructor Call: Using the new keyword with the counter ID.
2. Proxy Stack Call: Using the ym function with the init command.

Upon initialization, the system parses options, runs prioritized providers, executes the first hit (pageview) to retrieve counter settings, registers JS API methods, and finally runs asynchronous providers.

// Method 1: Direct constructor
new Ya.Metrika2(XXXXXX);

// Method 2: Via proxy stack
ym(XXXXXX, "init", {});

The project uses mocha for the test runner, sinon for stubs, and chai for assertions. When using sinon to stub functions, it is recommended to use a sandbox and provide proper TypeScript types for the stubs to ensure a good developer experience.

import * as sinon from 'sinon';
import defer from 'src/utils/defer/defer';

describe('test', () => {
    const sandbox = sinon.createSandbox();
    let setDeferStub: sinon.SinonStub<
        Parameters<typeof defer.setDefer>,
        ReturnType<typeof defer.setDefer>
    >

    beforeEach(() => {
        setDeferStub = sandbox.stub(defer, 'setDefer');
    });
});