Yandex Metrica Tag

https://github.com/yandex/metrica-tag
Admin
Metrica tag is a JavaScript library for web pages that gathers analytics information about page...
Tokens:51,679
Snippets:365
Trust Score:8.5
License:Apache-2.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Link Tracking Usage Examples

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/counter-methods.md

Examples of tracking external links, file downloads, adding custom extensions, and enabling automatic link tracking.

```js
counter.extLink('https://example.com', { callback: () => {} });
counter.file('/docs/manual.pdf', { title: 'Manual' });
counter.addFileExtension(['dmg', 'pkg']);
counter.trackLinks(true);
```

--------------------------------

### clickmap method usage example

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/counter-methods.md

JavaScript example showing how to enable click tracking with a quota of 500 clicks and ignoring 'A' and 'BUTTON' tags.

```JavaScript
counter.clickmap({ quota: 500, ignoreTags: ['A', 'BUTTON'] });
```

--------------------------------

### Install dependencies with npm ci

Source: https://github.com/yandex/metrica-tag/blob/main/README.md

Installs project dependencies. Use this after setting up the correct Node.js version.

```bash
npm ci
```

--------------------------------

### Install Node.js version with nvm

Source: https://github.com/yandex/metrica-tag/blob/main/README.md

Installs and uses the required Node.js version when nvm is installed. Run this before installing dependencies.

```bash
nvm install
```

--------------------------------

### reachGoal usage examples

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/counter-methods.md

Usage examples for the `reachGoal` counter method. The first sends a simple goal, the second includes raw parameters and a callback.

```js
counter.reachGoal('signup');
counter.reachGoal('purchase', { sum: 1000 }, (goalReached) => { /* ... */ });
```

--------------------------------

### Using getGlobalStorage to set and get values

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/storage.md

Shows how to use the memoized getGlobalStorage accessor to set and get a value in global storage. The example sets 'myKey' to { a: 1 } and retrieves it with a default of {}.

```js
import { getGlobalStorage } from 'src/storage/global/getGlobal';

const gs = getGlobalStorage(window);
gs.setVal('myKey', { a: 1 });
const v = gs.getVal('myKey', {}); // { a: 1 }
```

--------------------------------

### Example call to Ya.Metrika.counters()

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/counter-constructor.md

Shows how to call the static `counters` method, returning an array of counter info objects. The example output includes fields like `id`, `type`, `clickmap`, and `trackHash`.

```javascript
Ya.Metrika.counters(); // [{ id: 123456, type: 0, clickmap: true, trackHash: true, ... }]
```

--------------------------------

### Basic usage examples

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/counter-constructor.md

Shows three ways to initialize a Metrika counter: classic ym init, constructor with object, and direct constructor with defer flag for manual hit.

```javascript
// Classic initialization
ym(123456, 'init', {
    clickmap: true,
    trackLinks: true,
    accurateTrackBounce: true,
    webvisor: true,
});

// Constructor form
new Ya.Metrika({
    id: 123456,
    params: window.yaParams || {},
});

// Direct constructor; counterDefer lets you call .hit() manually later
const counter = new Ya.Metrika(123456, {}, 0, true);
counter.hit('/virtual/page', 'Virtual page');
```

--------------------------------

### getSender usage example

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/sender.md

Shows how to obtain a sender using getSender with HIT_PROVIDER and counterOptions, then invoke it with browser info and URL parameters.

```typescript
import { getSender } from 'src/sender';
import { HIT_PROVIDER } from 'src/providers';
import { browserInfo } from 'src/utils/browserInfo/browserInfo';

// In a custom provider
const sender = getSender(ctx, HIT_PROVIDER, counterOptions);
const result = await sender(
    {
        brInfo: browserInfo({ pv: 1 }),
        urlParams: { 'page-url': ctx.location.href },
    },
    counterOptions,
);
```

--------------------------------

### destruct method usage example

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/counter-methods.md

JavaScript example showing how to call the destruct method. After this call, the counter no longer accepts calls due to the destructingDecorator guard.

```JavaScript
counter.destruct(); // counter no longer accepts calls (destructingDecorator guard)
```

--------------------------------

### notBounce and accurateTrackBounce usage examples

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/counter-methods.md

Usage examples for `notBounce` and `accurateTrackBounce`. The first sends a technical not-bounce hit with context and callback. The second defers the not-bounce hit by 20 seconds.

```js
counter.notBounce({ ctx: this, callback: () => console.log('nb sent') });
counter.accurateTrackBounce(20000); // 20 s
```

--------------------------------

### Error handling example

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/counter-constructor.md

Shows that the constructor never throws for known-error conditions; falsy ids produce an uncatchable error object with message 'Invalid Metrika id: 0'.

```javascript
// The constructor never throws for known-error conditions — it logs to the
// debug bus / swallows. Falsy ids produce an uncatchable error object:
try {
    new Ya.Metrika(0); // 'Invalid Metrika id: 0' (error.unk === true)
} catch (e) {
    // e.message === 'Invalid Metrika id: 0'
}
```

--------------------------------

### Export initProvider in provider index.ts

Source: https://github.com/yandex/metrica-tag/blob/main/README.md

The index.ts of a new provider must export an initProvider function. The code inside the feature flag is removed by rollup if the feature is not included in the build, and the empty function is also removed. Use this to push the provider and perform optional setup.

```typescript
export const initProvider = () => {
    /* The code is wrapped by a feature flag.
       If the feature is not included into a build, the code is cut off by rollup.
       The resultant empty function is cut off as well */
    if (flags.SOME_NEW_FEATURE) {
        // Required code
        providersSync.push(someNewProvider);

        // Optional code for any additional setup
        addMiddlewareForProvider(SOME_NEW_PROVIDER, watchSyncFlags(), 1);
        providerMap[SOME_NEW_PROVIDER] = useSenderWatch;
        nameMap[SOME_NEW_PROVIDER] = fullList;
    }
};
```

--------------------------------

### Enable trackHash

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/counter-methods.md

Call trackHash(true) to start listening for hashchange events (or a 200 ms interval fallback for old browsers). Enabled by default when the constructor option trackHash: true is set. Each hash change sends a hit with wh=1, pv=1, current URL (or forceUrl), and the previous page URL as referrer.

```js
counter.trackHash(true);
```

--------------------------------

### userParams: type, signature, and usage example

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/counter-methods.md

Defines the type and signature for the userParams handler. The data is wrapped as { __ymu: data } and forwarded to params() with optional callback and callbackCtx. Warnings are logged when the counter instance or a valid object is missing.

```ts
export type UserParamsHandler<T = any> = (...a: any[]) => T;
```

```ts
(data: any, callback?: (...args: any[]) => any, callbackCtx?: Window) => void
```

```js
counter.userParams({ UserID: '123', Level: 7 });
```

--------------------------------

### firstPartyParams Usage Example

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/counter-methods.md

Calls to counter.firstPartyParams and counter.firstPartyParamsHashed. The first method hashes string values with SHA-256; the second expects already-hashed values. Both send results via the params method.

```js
counter.firstPartyParams({ email: 'user@example.com', phone_number: '+7 123 456 78 90' });
counter.firstPartyParamsHashed({ email: 'sha256hex...' });
```

--------------------------------

### Initialization flow chart

Source: https://github.com/yandex/metrica-tag/blob/main/DIAGRAM.md

Flow diagram of the initialization phase. The code runs automatically when the script is parsed approximates. Use to understand the global storage and its relationships.

```mermaid
flowchart TB
    subgraph GlobalStorage
      GS[Creates an empty storage and fills in some basic info. <br>The global storage is shared by all counter on a page. <br>It contains common data and allows intercounter communication, <br>e.g. register semaphores for actions that should be performed once for all counters.]
    end

    subgraph Mappings
      direction LR

      subgraph MD[Create mappings that define which sender/middleware/transport combination to use with each provider.]
      end

      subgraph ProviderMaps
        direction LR

        ProviderMap --> Sender
        ProviderMap --> ProviderMiddlewares
        ProviderMap --> Transports
      end

      subgraph SenderMaps
        direction LR
        
        SenderMap --> SenderMiddlewares
      end
    end

    subgraph CounterConstructor
      CC[The constructor function that starts a counter]
    end

    subgraph StaticMethods
      SM[Static counter methods not ties to a particular counter instance]
    end

    subgraph StackProxy
      SP[A handler of events from the proxy stack]
    end

    GlobalStorage --> Mappings
    Mappings --> CounterConstructor
    CounterConstructor --> StaticMethods
    StaticMethods --> StackProxy
```

--------------------------------

### Typical custom middleware with addMiddlewareForProvider

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/middleware.md

Shows how to create a custom middleware getter and register it for a provider. The middleware sets a custom flag in brInfo before the request is sent. The addMiddlewareForProvider call places it after watchSyncFlags and before pageTitle.

```typescript
// Typical custom middleware
import { addMiddlewareForProvider } from 'src/middleware';
import type { MiddlewareGetter } from 'src/middleware/types';

const myFlag: MiddlewareGetter = (ctx, opt) => ({
    beforeRequest: (senderParams, next) => {
        if (senderParams.brInfo) {
            senderParams.brInfo.setVal('myFlag', '1');
        }
        next();
    },
});

addMiddlewareForProvider('h', myFlag, 5); // after watchSyncFlags, before pageTitle
```

--------------------------------

### getClientID: type, signature, and usage example

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/counter-methods.md

Defines the type and signature for the getClientID handler. Returns the uid generated/persisted by getUid; if a callback is given it is called as callback(uid).

```ts
export type GetClientIDHandler = (...args: any[]) => string;
```

```ts
(callback?: (...args: any[]) => any) => string
```

```js
const uid = counter.getClientID();
counter.getClientID(function (id) { console.log('uid', id); });
```

--------------------------------

### Build the tag with npm run build

Source: https://github.com/yandex/metrica-tag/blob/main/README.md

Builds the tag into `_build/public/watch.js`. The default build is uglified for smaller size.

```sh
npm run build
```

--------------------------------

### Build without uglification using npm run build:raw

Source: https://github.com/yandex/metrica-tag/blob/main/README.md

Builds the tag without uglification, useful for debugging. Output goes to `_build/public/watch.js`.

```sh
npm run build:raw
```

--------------------------------

### useMiddlewareSender: returnFullHost function

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/sender.md

Constructs a full host URL by prepending the protocol and host to the resource. Used in the core request pipeline of useMiddlewareSender.

```typescript
export const returnFullHost = (resource: string, argHost?: string) =>
    `${cProtocol}//${argHost || host}/${resource}`;
```

--------------------------------

### Stub with sinon in tests

Source: https://github.com/yandex/metrica-tag/blob/main/README.md

Preferred style for stubbing with sinon in tests. Assign proper types to stubs without over-specifying details. This example creates a sandbox and stubs defer.setDefer in beforeEach.

```typescript
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');
    });
```

--------------------------------

### addFileExtension(ext)

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/counter-methods.md

Registers one or more custom download file extensions to be recognized by the `file` method for link tracking.

```APIDOC
## addFileExtension(ext)

### Description
Registers custom download file extensions. After registration, the `file` method will treat URLs ending with these extensions as download links. Accepts a single extension string or an array of extension strings.

### Parameters
- **ext** (string | string[]) - Required - A file extension (e.g., 'dmg') or an array of extensions (e.g., ['dmg', 'pkg']).

### Request Example
```js
counter.addFileExtension(['dmg', 'pkg']);
```

### Response
No return value (void).

```

--------------------------------

### file(url, options?)

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/counter-methods.md

Sends a download-link click hit to Yandex Metrica. The hit includes flags `dl=1` and `dwl=1` when the URL matches a registered download extension.

```APIDOC
## file(url, options?)

### Description
Sends a download-link click hit to Yandex Metrica. The URL is matched against a set of download extensions. The hit includes `dl=1` and `dwl=1` flags.

### Parameters
#### Path Parameters
- No path parameters - this is a JavaScript method.

#### Body Parameters
- **url** (string) - Required - The URL of the file to track.
- **options** (UserOptions) - Optional - An object with the following properties:
  - **ctx** (any) - Optional - Callback context.
  - **callback** (function) - Optional - Function called after sending the hit.
  - **params** (Record<string, any>) - Optional - Visit parameters to send with the hit.
  - **title** (string) - Optional - Link title.

### Request Example
```js
counter.file('/docs/manual.pdf', { title: 'Manual' });
```

### Response
No return value (void or a Promise).

```

--------------------------------

### setUserID: type, signature, and usage example

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/counter-methods.md

Defines the type and signature for the setUserID handler. Non-string/non-number ids log WRONG_USER_ID_CONSOLE_MESSAGE. The id is sent as the internal param path __ym.user_id.<id> via params().

```ts
export type SetUserIDHandler<T = any> = (...args: any[]) => T;
```

```ts
(id: unknown, callback?: AnyFunc, callbackCtx?: Window) => void
```

```js
counter.setUserID('user-42');
```

--------------------------------

### Queued window.ym() calls before script load

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/counter-constructor.md

Shows how to queue `window.ym` calls before the script loads. The calls are stored in an array and processed by the stack proxy after initialization.

```javascript
// Queued before the script loads still works:
window.ym = window.ym || [];
window.ym(123456, 'init', { trackLinks: true });
window.ym(123456, 'reachGoal', 'signup');
```

--------------------------------

### hit method usage examples

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/counter-methods.md

Shows two forms of calling `counter.hit`: positional arguments and an object form. The object form allows setting title, referrer, params, and callback. The method returns a promise and invokes the callback after sending.

```javascript
counter.hit('/page/2.html', 'Page 2', document.referrer, { key: 'value' }, callback);
// object form
counter.hit('/page/3.html', {
    title: 'Page 3',
    referrer: 'https://example.com/',
    params: { source: 'banner' },
    callback: () => console.log('sent'),
});
```

--------------------------------

### Provider middleware registration (providerMiddlewares.ts)

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/middleware.md

Defines the common middleware chain for hit providers, with a fixed ordering by weight. The first middleware (prepareUrlMiddleware) is always first and not included in the parameters list. Provides functions to add common middleware, add middleware for a specific provider, and retrieve the middleware chain.

```TypeScript
export const commonMiddlewares: MiddlewareWeightTuple[] = [
    // This one should be always first
    // and shouldn't get into the params middlewares list.
    [prepareUrlMiddleware, -100],
    [prerender, 1],
    [counterFirstHit, 2],
    [watchSyncFlags(), 3],
    [pageTitle, 4],
];

export const hitMiddlewares = commonMiddlewares.slice();

/** Always executed irrespective of the provider */
export const universalMiddlewares: MiddlewareGetter[] = [];

export const addCommonMiddleware = bindArg(
    commonMiddlewares,
    addMiddlewareToTheList,
);

/** Mapping between providers and corresponding middleware chains */
export const providerMiddlewareList: Partial<
    ProvidersMap<MiddlewareWeightTuple[]>
> = {
    [HIT_PROVIDER]: hitMiddlewares,
};

export const addMiddlewareForProvider: (
    providerName: Provider,
    middleware?: MiddlewareGetter,
    weight?: number,
) => void = bindArg(providerMiddlewareList, addMiddlewareFor);

export const getProviderMiddlewares = (
    ctx: Window,
    providerOrMiddlewares: Provider | MiddlewareWeightTuple[],
    opt: CounterOptions,
) => Middleware[];
```

--------------------------------

### params method usage examples

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/counter-methods.md

Three call forms for the params method: a single object, multiple arguments with path segments and a value, and an object with a callback. Params are serialized to JSON and sent as site-info for pageview hits or as POST body for non-pageview hits. Params longer than 2048 (512 for IE) chars on a pageview are queued and replayed after the hit.

```js
counter.params({ level1: { level2: 'value' } });
counter.params('errors', 'url', '/error/404', 'browser', 'Chrome');
counter.params({ currency: 'USD' }, function () { /* sent */ });
```

--------------------------------

### Run window-level providers

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/providers.md

Executes all window-level providers registered in `windowProviderInitializers` by calling each with the window object. Used in `src/index.ts:170`.

```typescript
cForEach(curry2SwapArgs(call)(window), windowProviderInitializers);
```

--------------------------------

### Counter settings API: setSettingsRaw, setSettings, getCounterSettings

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/utils.md

Exports three functions for managing counter settings: setSettingsRaw stores raw settings by counter key, setSettings normalizes and stores settings while recording timing and dispatching a debugger event, and getCounterSettings retrieves settings asynchronously. Settings are stored per counter key in an async map and the CounterSettings interface is augmented by features like button_goals, hittoken, ecommerce, and phhide.

```typescript
export const setSettingsRaw = (counterKey: string, settings: CounterSettings) => Promise;
export const setSettings = (
    ctx: Window,
    counterOptions: CounterOptions,
    rawSettings: CounterSettings,
) => Promise<...>;
export const getCounterSettings = <R>(
    counterOptions: CounterOptions,
    callBack: (opt: CounterSettings) => R,
): Promise<R>;
```

--------------------------------

### Provider execution order in MetrikaCounter constructor

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/README.md

Shows the fixed order in which provider functions are executed during counter initialization, including the first pageview hit and error logging wrappers.

```typescript
// src/index.ts
cForEach((provider) => { provider(ctx, counterOptions); }, prioritizedProviders);
cForEach(callProvider, beforeHitProviders);  // wrapped in errorLogger 'c.i.bh'
callProvider(useHitProvider);                // first pageview hit
cForEach(callProvider, providersSync);       // wrapped in errorLogger 'c.i.ps'
```

--------------------------------

### Inject build-time flags and args from environment

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/configuration.md

Injected build-time constants from environment variables. `getVersion()` falls back to `'25'` when `VERSION` is unset.

```typescript
export const flags: BuildFlags = process.env.BUILD_FLAGS as any;
export const argOptions: Args = process.env.ARG_OPTIONS as any;
export const resourceId = process.env.JS_NAME as string;
export const getVersion: () => string = () => process.env.VERSION! || '25';
```

--------------------------------

### CookieStorage methods (delVal, getVal, setVal)

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/storage.md

Describes the `CookieStorage` interface returned by `cookieStorage`. Method names are prefixed with `_ym_` and suffixed with `_<namespace>`. The default domain is the root domain (discovered via `checkCookie` probing, prefixed with `.`) and the default path is `/`.

```ts
{
    delVal(name: string, clientDomain?: string, path?: string): CookieStorage;
    getVal(name: string, multi?: boolean): string | string[] | null;
    setVal(name: string, val: string, minutes?: number, clientDomain?: string, path?: string): CookieStorage;
}
```

--------------------------------

### Create and test HTTP errors (http.)

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/errors.md

Creates and identifies HTTP errors with the `http.` prefix. Produced by fetch/XHR when `returnRawResponse` is set and the response is non-OK. `handleError` drops them with 90% probability (keeps 10%).

```ts
export const makeHttpError = (ctx: { status: number; statusText: string; responseText?: string }) => {
    // text = `http.<status>.st.<statusText>.rt.<responseText[0..50]>`
};
export const isHTTPError = bindThisForMethodTest(new RegExp(`^http.`));
```

--------------------------------

### Catching errors in consumer code

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/errors.md

Shows how to catch errors in consumer code. The constructor throws uncatchable errors for invalid ids (e.g., new Ya.Metrika(0)) with an 'unk' property. Counter methods return promises that reject with known errors (err.kn...). Regular errors are swallowed internally and reported to ON_ERROR_CALLBACKS.

```js
// 1. Uncatchable constructor errors (invalid id)
try {
    new Ya.Metrika(0);
} catch (e) {
    if (e && e.unk) {
        // 'Invalid Metrika id: 0' — created with createError(msg, true)
    }
}

// 2. Promises returned by counter methods (hit, reachGoal, firstPartyParams...)
counter.firstPartyParams({ email: 'a@b.c' }).catch((e) => {
    // known errors: err.kn(<version>)fpm.o / fpm.l / fpm.i
    if (/^err\.kn/.test(e.message)) {
        // retry later or ignore
    }
});

// 3. Global monitoring is internal: all regular errors are swallowed by the error
// logger and reported to the module-level ON_ERROR_CALLBACKS array
// (src/utils/errorLogger/onError.ts) via runOnErrorCallbacks('jserrs', message, scope, stack).
// Observable side channels for app code are the error telemetry (flags 'mc', 'mtb')
// and the _ym_debug debugger events bus ('error' events, src/utils/debugEvents).
```

--------------------------------

### extLink(url, options)

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/counter-methods.md

Sends an external-link click hit to Yandex Metrica. The hit includes the flag `ln=1`.

```APIDOC
## extLink(url, options)

### Description
Sends an external-link click hit to Yandex Metrica. The hit includes the flag `ln=1`.

### Parameters
#### Body Parameters
- **url** (string) - Required - The URL of the external link.
- **options** (UserOptions) - Required - An object with the following properties:
  - **ctx** (any) - Optional - Callback context.
  - **callback** (function) - Optional - Function called after sending the hit.
  - **params** (Record<string, any>) - Optional - Visit parameters to send with the hit.
  - **title** (string) - Optional - Link title.

### Request Example
```js
counter.extLink('https://example.com', { callback: () => {} });
```

### Response
No return value (void or a Promise).

```

--------------------------------

### Provider implementation options (ProviderResult)

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/providers.md

Three alternative implementations of a provider function: returning an unsubscribe function, returning counter methods, or returning a promise of either. Each option is shown as a separate code block.

```typescript
// (a) return an unsubscribe function
const myProvider: ProviderFunction = (ctx, counterOpt) => {
    const un = subscribeSomething(ctx);
    return un;
};
```

```typescript
// (b) return counter methods
const myProvider: ProviderFunction = (ctx, counterOpt) => ({
    myMethod: (arg) => { /* ... */ },
});
```

```typescript
// (c) return a promise of either
const myAsyncProvider: ProviderFunction = async (ctx, counterOpt) => ({
    myMethod: () => {},
});
```

--------------------------------

### normalizeOriginalOptions function

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/api-reference/counter-constructor.md

Builds raw options from constructor arguments. If the first argument is an object, it is used as-is; otherwise, it creates an object with id, type, defer, and params keys.

```typescript
export const normalizeOriginalOptions = (
    counterId: RawCounterOptions | number,
    counterParams?: Record<string, unknown>,
    counterType?: number,
    counterDefer?: boolean,
): RawCounterOptions =>
    isObject(counterId)
        ? counterId
        : {
              ['id']: counterId,
              ['type']: counterType,
              ['defer']: counterDefer,
              ['params']: counterParams,
          };
```

--------------------------------

### Constructor call forms for Ya.Metrika and ym()

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/configuration.md

Three supported ways to pass counter options to the Metrika tag: positional arguments, an options object with raw keys, and the ym() stack proxy. The first form passes the counter id, options, and two additional positional arguments (0 and false). The second uses raw option keys like 'id' and 'clickmap'. The third uses the ym() function with the counter id, the 'init' action, and an options object.

```javascript
// 1. Positional
new Ya.Metrika(123456, { clickmap: true }, 0, false);
```

```javascript
// 2. Options object (raw keys)
new Ya.Metrika({ id: 123456, clickmap: true, accurateTrackBounce: true });
```

```javascript
// 3. Stack proxy: ym(counterId, 'init', options)
ym(123456, 'init', { clickmap: true, trackLinks: true });
```

--------------------------------

### Generate feature set with npm run features

Source: https://github.com/yandex/metrica-tag/blob/main/README.md

Run this command to generate the new feature set after adding a feature to features.json.

```sh
npm run features
```

--------------------------------

### Module graph of src/index.ts

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/README.md

Shows the main module-level exports and their source locations, including providers, sender, transport, middleware, and storage helpers.

```text
src/index.ts
├── useHitProvider          (src/providers/hit)         — automatic first hit
├── stackProxy              (src/providers/stackProxy)  — window.ym() data layer
├── callbackInit            (src/providers/callbackInit) — user callbacks
├── destruct                (src/providers/destruct)    — `destruct` method
├── initImports             (generated/init)            — initProvider() calls for each feature
├── getSender               (src/sender)
├── getTransportList        (src/transport)
├── getProviderMiddlewares  (src/middleware)
├── counterOptions          (normalize*, optionsKeysMap, addCounterOptions)
└── global storage helpers  (src/storage/global)
```

--------------------------------

### Base URL configuration (src/config.ts)

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/endpoints.md

Defines the default host and protocol for the tag. Production builds override host to 'mc.yandex.ru' with https; local/test builds use http and localhost:3030.

```TypeScript
// src/config.ts
export const host = argOptions.host || 'localhost:3030';
export const cProtocol = isTestBuild ? 'http:' : 'https:';
```

--------------------------------

### Page-level globals and contract constants (src/const.ts, src/config.ts)

Source: https://github.com/yandex/metrica-tag/blob/main/_autodocs/configuration.md

Defines page-level globals and contract constants used across the tag: the global namespace (`Ya`), the async provider execution budget, the counter constructor name, host, protocol, build version, and the `NOINDEX` constant. The constructor name defaults to `Metr${argOptions.version}` and the host to `localhost:3030`; the protocol is `https:` in production builds.

```ts
export const yaNamespace = 'Ya';                    // window.Ya
export const ASYNC_PROVIDERS_MAX_EXEC_TIME = 1;     // ms budget for async providers

export const constructorName: Constructor = argOptions.construct || `Metr${argOptions.version}`;
export const host = argOptions.host || 'localhost:3030';
export const cProtocol = isTestBuild ? 'http:' : 'https:';  // 'https:' in production
export const buildVersion = getVersion();
export const NOINDEX = 'noindex';
```
Tokens:
Raw