@artginzburg/next-ym
v1.2.1
Published
Yandex Metrica integration for Next.js v14
Downloads
70
Maintainers
Readme
Next.js Yandex Metrica
Yandex Metrica integration for Next.js v14 (App Router)
Fork reasoning
The original repo had:
- Only v13 (Pages Router) supported
- No E-commerce support
- Lack of focus on TypeScript autosuggestions and JSDoc comments
Usage
Add the provider
To enable analytics, include YandexMetricaProvider
in the custom _app
component.
// pages/_app.tsx
import { YandexMetricaProvider } from 'next-yandex-metrica';
export default function MyApp({ Component, pageProps }) {
return (
<YandexMetricaProvider
tagID={12345678}
initParameters={{ clickmap: true, trackLinks: true, accurateTrackBounce: true }}
>
<Component {...pageProps} />
</YandexMetricaProvider>
);
}
YandexMetricaProvider
Props
| Name | Description |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| tagID
| Yandex.Metrica tag ID. |
| strategy
| next/script loading strategy. Defaults to afterInteractive
. |
| initParameters
| Yandex.Metrica tag initialization parameters. |
| shouldUseAlternativeCDN
| Use the alternative CDN to load Yandex.Metrica. |
Yandex.Metrica tag ID is read from the tagID
property and the NEXT_PUBLIC_YANDEX_METRICA_ID
environment variable. If both are set, the provider property takes priority.
Send events
next/router
pageviews are tracked automatically.
The package provides useMetrica
hook for sending custom analytics events.
import { useMetrica } from 'next-yandex-metrica';
export function ActionButton() {
const { reachGoal } = useMetrica();
return (
<button type="button" onClick={() => reachGoal('cta-click')}>
CTA
</button>
);
}
The returned functions accept the same parameters as those found in the Yandex.Metrica object methods.
All functions are automatically provided with the tag ID that is supplied to the provider or the environment variable. useMetrica
hook exposes functions for calling notBounce
, reachGoal
, setUserID
, and userParams
without specifying the event name. Other methods can be called using the ymEvent
function, with the event name as the first argument. In both cases, all event parameters are type-checked.
import { useMetrica } from 'next-yandex-metrica';
export function ActionButton() {
const { ymEvent } = useMetrica();
const handleExternalLinkClick = () => {
ymEvent('extLink', 'https://www.google.com');
};
// ...
}
In case if you need to use the Yandex.Metrica object directly, you can access it using the ym
property.
import { ym } from 'next-yandex-metrica';
export function ActionButton() {
return (
<button type="button" onClick={() => ym(12345678, 'reachGoal', 'cta-click')}>
CTA
</button>
);
}
Contributing
Things that are necessary in order to call it the Next.js Yandex Metrica integration are listed in TODO.md
If your use-case is not supported, please create an Issue. You'll be implementing it anyway if it's your real use-case, might as well support the community or accidentally find other adopters of that use-case.