trackItemClick(item)}>
{item.title}
));
```
--------------------------------
### Configure Next.js with Metrica Proxy
Source: https://github.com/artginzburg/next-ym/blob/main/README.md
Configures the Next.js application to use a Metrica proxy for Safari ITP compatibility. This involves wrapping the Next.js config with `withMetricaProxy`.
```ts
import { withMetricaProxy } from '@artginzburg/next-ym/config';
const nextConfig = {
/* your config */
};
export default withMetricaProxy(nextConfig);
```
--------------------------------
### Configure Yandex Metrica Tag ID via Environment Variables
Source: https://context7.com/artginzburg/next-ym/llms.txt
Set the Yandex Metrica tag ID using environment variables to avoid hardcoding values. When using `withMetricaProxy`, the `NEXT_PUBLIC_YM_PROXY_PATH` is automatically set.
```bash
# .env.local
NEXT_PUBLIC_YANDEX_METRICA_ID=12345678
# When using withMetricaProxy, this is automatically set:
# NEXT_PUBLIC_YM_PROXY_PATH=/metrika-proxy.js
```
--------------------------------
### YandexMetricaProvider Component
Source: https://context7.com/artginzburg/next-ym/llms.txt
The root provider component used to initialize Yandex Metrica and enable automatic pageview tracking across the application.
```APIDOC
## YandexMetricaProvider
### Description
Wraps the application root to initialize Yandex Metrica. It handles automatic SPA navigation tracking and provides the context for tracking hooks.
### Parameters
- **tagID** (number) - Optional - The Yandex Metrica counter ID. Defaults to NEXT_PUBLIC_YANDEX_METRICA_ID env var.
- **initParameters** (object) - Optional - Configuration object for Yandex Metrica (e.g., clickmap, webvisor, ecommerce).
- **strategy** (string) - Optional - next/script loading strategy (e.g., 'afterInteractive').
- **shouldUseAlternativeCDN** (boolean) - Optional - Toggle to use an alternative CDN for the script.
### Request Example
trackItemClick(item)}>
{item.title}
));
```
--------------------------------
### YandexMetricaProvider Component
Source: https://github.com/artginzburg/next-ym/blob/main/README.md
The YandexMetricaProvider component is used to initialize Yandex Metrica. It supports conditional rendering for GDPR compliance and accepts various configuration props.
```APIDOC
## YandexMetricaProvider
### Description
A React provider component that initializes Yandex Metrica. It defers network requests until mounted, making it suitable for consent-based tracking.
### Parameters
#### Props
- **tagID** (number) - Optional - Yandex Metrica tag ID. Can also be set via NEXT_PUBLIC_YANDEX_METRICA_ID env var.
- **initParameters** (InitParameters) - Required - Initialization parameters. Use standardYMInitParameters for recommended defaults.
- **strategy** (ScriptProps['strategy']) - Optional - next/script strategy. Default: afterInteractive.
- **shouldUseAlternativeCDN** (boolean) - Optional - Whether to use the alternative CDN for loading the script.
```
--------------------------------
### useEcommerce Hook
Source: https://context7.com/artginzburg/next-ym/llms.txt
React hook for tracking ecommerce events following Yandex Metrica's enhanced ecommerce specification.
```APIDOC
## useEcommerce Hook
### Description
A React hook that provides methods to track ecommerce events such as product impressions, clicks, views, cart actions, and purchases. Requires `ecommerce: true` or `ecommerce: 'dataLayer'` in init parameters.
### Methods
- **trackImpressionsProduct**: Tracks product list impressions.
- **trackClickProduct**: Tracks a product click.
- **trackViewProduct**: Tracks a product detail view.
- **trackAddItemToBasket**: Tracks adding an item to the cart.
- **trackRemoveItemFromBasket**: Tracks removing an item from the cart.
- **trackPurchase**: Tracks a completed purchase.
- **trackPromoView**: Tracks promo banner impressions.
- **trackPromoClick**: Tracks a promo banner click.
- **pushToDataLayer**: Pushes custom data to the data layer.
```
--------------------------------
### Define typed goal parameters
Source: https://github.com/artginzburg/next-ym/blob/main/docs/advanced.md
Create a map of goal names to their expected payloads to ensure compile-time safety.
```tsx
type GoalParams = {
// Conversions
purchase: { itemId: string; type: string; category: string; price: number };
item_created_free: { itemId: string; type: string };
item_downloaded: { itemId: string };
// Payments
top_up: { amount: number };
top_up_started: { amountCents: number };
// Auth
signup: undefined;
login: undefined;
// Engagement
review_submitted: { itemId: string; rating: number };
referral_link_copied: undefined;
guidelines_uploaded: { fileName: string };
};
type Goal = keyof GoalParams;
```
--------------------------------
### Execute Yandex Metrica Commands with ym Function
Source: https://context7.com/artginzburg/next-ym/llms.txt
Enables direct interaction with the global ym function for goals, page hits, and user parameters. Requires the tag ID as the first argument.
```ts
import { ym } from '@artginzburg/next-ym';
const TAG_ID = 12345678;
// Track a goal
ym(TAG_ID, 'reachGoal', 'cta-click');
// Track goal with parameters
ym(TAG_ID, 'reachGoal', 'purchase', { order_price: 99.99, currency: 'USD' });
// Track page hit manually
ym(TAG_ID, 'hit', '/virtual-page', {
title: 'Virtual Page Title',
referer: 'https://example.com/previous-page',
});
// Set user ID
ym(TAG_ID, 'setUserID', 'user_12345');
// Send user parameters
ym(TAG_ID, 'userParams', { UserID: 12345, subscription: 'premium' });
// Mark as not bounce
ym(TAG_ID, 'notBounce');
// Track external link click
ym(TAG_ID, 'extLink', 'https://external-site.com');
// Track file download
ym(TAG_ID, 'file', 'https://example.com/files/document.pdf');
// Get client ID
ym(TAG_ID, 'getClientID', (clientID) => {
console.log('Metrica Client ID:', clientID);
});
// Send first-party params for cross-device tracking
ym(TAG_ID, 'firstPartyParams', {
email: 'user@example.com',
phone_number: '+1234567890',
});
```
--------------------------------
### Domain-to-Product Mapping for Yandex Metrica Ecommerce
Source: https://context7.com/artginzburg/next-ym/llms.txt
Convert your application's domain objects to Yandex Metrica's ecommerce product format using a centralized converter function. This pattern helps in tracking e-commerce events like purchases, product views, and clicks accurately.
```tsx
'use client';
import { useEcommerce, useMetrica } from '@artginzburg/next-ym';
import { useCallback, useEffect } from 'react';
// Your domain model
interface AppProduct {
id: string;
title: string;
priceCents: number;
type: 'PREMIUM' | 'BASIC';
category: string;
}
// Convert to Metrica format
function toMetricaProduct(item: AppProduct) {
return {
id: item.id,
name: `${item.type === 'PREMIUM' ? 'Premium' : 'Basic'}: ${item.title}`,
price: item.priceCents / 100,
category: item.category,
variant: item.type,
quantity: 1,
};
}
export function useAnalytics() {
const { reachGoal } = useMetrica();
const { trackPurchase, trackViewProduct, trackClickProduct, trackImpressionsProduct } =
useEcommerce({ currencyCode: 'USD' });
const trackItemPurchase = useCallback(
(item: AppProduct) => {
const product = toMetricaProduct(item);
trackPurchase({
actionField: { id: `order_${Date.now()}`, revenue: product.price },
products: [product],
});
reachGoal('purchase', { itemId: item.id, price: product.price });
},
[trackPurchase, reachGoal],
);
const trackItemView = useCallback(
(item: AppProduct) => trackViewProduct({ product: toMetricaProduct(item) }),
[trackViewProduct],
);
const trackItemClick = useCallback(
(item: AppProduct) => trackClickProduct({ product: toMetricaProduct(item) }),
[trackClickProduct],
);
const trackItemImpressions = useCallback(
(items: AppProduct[]) => {
if (items.length === 0) return;
trackImpressionsProduct({ products: items.map(toMetricaProduct) });
},
[trackImpressionsProduct],
);
return { trackItemPurchase, trackItemView, trackItemClick, trackItemImpressions };
}
// Usage in components
function ProductList({ products }: { products: AppProduct[] }) {
const { trackItemImpressions, trackItemClick } = useAnalytics();
useEffect(() => {
trackItemImpressions(products);
}, [products.length, trackItemImpressions]);
return (
{products.map((product) => (
);
}
function ProductDetail({ product }: { product: AppProduct }) {
const { trackItemView } = useAnalytics();
useEffect(() => {
trackItemView(product);
}, [product.id, trackItemView]);
return trackItemClick(product)}>
{product.title} - ${product.priceCents / 100}
))}
{product.title}
;
}
```
--------------------------------
### Configure Yandex Metrica ID
Source: https://github.com/artginzburg/next-ym/blob/main/README.md
Set your Yandex Metrica counter ID using the NEXT_PUBLIC_YANDEX_METRICA_ID environment variable. This is the recommended method for configuration.
```env
NEXT_PUBLIC_YANDEX_METRICA_ID=12345678
```
--------------------------------
### Map domain objects to product format
Source: https://github.com/artginzburg/next-ym/blob/main/docs/advanced.md
Define a converter function to transform domain-specific item objects into the format expected by Yandex Metrica.
```tsx
interface ItemProduct {
id: string;
title: string;
type: 'PREMIUM' | 'BASIC';
category: string;
optionCount: number;
/** Price in cents as stored in your DB. */
priceCents: number;
}
function toProduct(item: ItemProduct) {
return {
id: item.id,
name: `${item.type === 'PREMIUM' ? 'Premium' : 'Basic'}: ${item.title}`,
price: item.priceCents / 100, // Metrica expects the display currency
category: item.category,
variant: `${item.optionCount} options`,
quantity: 1,
};
}
```
--------------------------------
### Noscript Tracking Pixel
Source: https://github.com/artginzburg/next-ym/blob/main/README.md
Provides a fallback tracking pixel for users with JavaScript disabled. This ensures basic visit counts are registered in Metrica.
```html