rybbit-ts

Kdo nasazuje analytiku Rybbit na víc webů než jeden, řeší pokaždé totéž. Skript se načítá asynchronně, takže kliknutí v prvních vteřinách se ztratí. E-shop chce měřit nákupy a košík, ale každý vývojář pojmenuje událost jinak. Marketing má události nastavené v Google Tag Manageru a nechce je zakládat podruhé. rybbit-ts je tenká vrstva v TypeScriptu nad sledovacím skriptem Rybbitu, která tyhle tři věci řeší jednou a stejně pro všechny weby.

Co přidává k samotnému skriptu Rybbitu

Rybbit sám dodává skript script.js, který servíruje každá jeho instance, a balíček @rybbit/js pro sestavované aplikace. rybbit-ts žádný z nich nenahrazuje a vlastní data neposílá: použije jeden z nich a přidá nad něj frontu, typované události a napojení na Tag Manager. Co Rybbit do skriptu doplní na serveru, třeba skóre detekce robotů ve verzi 2.5, tak funguje beze změny kódu.

Výhody v praxi

Nic se neztratí, než se skript načte

Volání před dokončením inicializace jdou do fronty a po spuštění se přehrají ve stejném pořadí. Web tedy může volat event() hned při startu a nemusí čekat na načtení analytiky. Fronta drží až 100 volání, při přetečení zahodí nejstarší. Když vložený skript nenaběhne do pěti sekund, inicializace skončí chybou místo tichého čekání; lhůtu mění loadTimeout.

Tři způsoby načtení, jedno API

Strategie script vloží skript Rybbitu do stránky, sdk použije balíček @rybbit/js a výchozí detect pozná, co už stránka má. Stejný kód tak funguje na klasickém webu se šablonami i v aplikaci postavené ve Vite nebo webpacku a při přechodu z jednoho na druhé se volání událostí nemění.

Události s jednotnými názvy

Typované metody pokrývají e-shop (trackViewItem, trackAddToCart, trackPurchase, trackRefund), účty, formuláře, hledání, stahování souborů, hloubku posunu stránky nebo hodnocení. Názvy a vlastnosti odpovídají událostem GA4, takže kdo přechází z Google Analytics, nemusí přejmenovávat. TypeScript ohlídá povinné parametry ještě při psaní kódu.

Události z Tag Manageru bez zakládání znovu

Most k Google Tag Manageru převezme události, které už v dataLayer jsou, a zachytí každý další push. Seznam gtmEvents určí, které z nich do Rybbitu projdou. Weby, které měří přes GTM, tak dostanou data do Rybbitu bez úpravy značek.

Měření kliknutí přímo v HTML

Prvek s atributem data-nhr-event se při kliknutí zaznamená sám a další atributy data-nhr-* se stanou vlastnostmi události; data-nhr-button-type se pošle jako button_type. Kodér šablony tak přidá měření bez jediného řádku JavaScriptu. Podobně si SDK přečte identifikátor přihlášeného uživatele, který server vypíše do stránky: ve výchozím stavu z prvku s atributem data-nhr-user-id, jiný prvek určí volba identitySelector.

Testy, které nezanesou statistiky

Režim dryRun skript Rybbitu vůbec nenačte a každé volání jen vypíše do konzole. Má to i druhý důvod: od verze 2.5 Rybbit tiše zahazuje provoz z Playwrightu, Puppeteeru a dalších automatů. Server přitom odpoví 200 se zprávou „bot detected“ a v prohlížeči se žádná chyba neukáže, takže bez dryRun by E2E testy marně hledaly, proč události nedorazily.

Jak se používá

import nksRybbit from '@nks-hub/rybbit-ts';

await nksRybbit.boot({
  host: 'https://demo.rybbit.com',
  siteId: 'your-site-id',
  loadStrategy: 'detect',
  gtmBridge: true,
  gtmEvents: ['purchase'],
  dryRun: process.env.NODE_ENV === 'test',
});

nksRybbit.trackPurchase({ transactionId: 'TX-001', value: 1299, currency: 'CZK' });

Bez sestavovacího nástroje se načte verze IIFE značkou <script> a SDK je pak dostupné jako NksRybbit.default. Balíček nemá žádné závislosti za běhu. Vychází ve čtyřech podobách: ESM pro bundlery (asi 24 kB), CommonJS (25 kB), IIFE pro vývoj (26 kB) a minifikovaná IIFE pro produkci (13 kB), k tomu typové definice. Dál umí globální vlastnosti přidávané ke všem událostem, nahrávání relace spouštěné a zastavované z kódu, odchozí odkazy, chyby a zpětné volání na každou odeslanou událost. Samo nezapisuje žádné cookies.

Kde se hodí

• Agentura nebo firma s několika weby na Rybbitu, která chce stejné názvy událostí všude a jedno místo, kde se mění.
• E-shop, který přechází z Google Analytics a chce zachovat události GA4 i nastavení v Tag Manageru.
• Web se serverovými šablonami, kde měření kliknutí přidává kodér atributy v HTML místo psaní skriptů.
• Projekt se sadou E2E testů, které nesmějí zkreslit statistiky ani skončit v tichém filtru robotů.

Pro aplikace ve Flutteru existuje sesterská knihovna rybbit-flutter-sdk se stejnými událostmi ve stylu GA4, takže web i mobilní aplikace posílají do Rybbitu data stejného tvaru.

Stav projektu

Na npm je verze 0.1.0 z 24. února 2026. V repozitáři je o krok dál verze 0.1.1 s opravou serializace trackPurchase z března 2026 a dokumentací k detekci robotů v Rybbitu 2.5; na npm zatím nevyšla. Testy ve Vitestu pokrývají frontu, automatické měření kliknutí a hlavní API. Balíček dřív vycházel pod jménem @nks-hub/rybbit, který je na npm označený jako zastaralý s odkazem na nové jméno.

Jak začít

npm install @nks-hub/rybbit-ts

Návod k instalaci a strategiím načtení, katalog událostí, popis mostu k Tag Manageru a reference API jsou v adresáři docs/ repozitáře. Potřeba je prohlížeč s ES6 a u projektů v TypeScriptu verze 5.0 nebo novější.

Zdrojový kód

Kód je na GitHubu v repozitáři nks-hub/rybbit-ts pod licencí MIT. Balíček je na npm jako @nks-hub/rybbit-ts, poslední verze 0.1.0.