databuddy getting started

Databuddy je privacy-first webová a produktová analytická platforma, ktorá funguje bez cookies, fingerprintingu alebo perzistentných identifikátorov. Postavená na Next.js a Tailwind CSS na frontende, poháňaná Elysia a tRPC pre API vrstvu, používa Neon Postgres pre metadáta a ClickHouse pre vysokovýkonné analytické dotazy. Platforma poskytuje presné webové a produktové analytiky pri rešpektovaní súkromia používateľov od návrhu.

Táto príručka pokrýva všetko, čo potrebujete na nasadenie Databuddy, jeho integráciu do vášho webu a začatie zbierania akčných analytických dát bez consent bannerov alebo compliance starostí.

Prečo Databuddy?

Tradičné analytické platformy ako Google Analytics čelia rastúcim výzvam: klesajúca presnosť dát kvôli odmietaniu súhlasu, blokovačom cookies a prísnejším reguláciám súkromia. Databuddy rieši tieto problémy tým, že nikdy nevyžaduje cookies ani zber osobných údajov.

Kľúčové výhody

Žiadne prekážky so súhlasom: Nie sú potrebné cookie bannery, keďže sa nezbierajú osobné údaje
100% zachytenie dát: Sledujte všetkých návštevníkov, nielen tých, ktorí akceptujú cookies (typicky 50-70%)
Minimálna stopa: ~3KB veľkosť skriptu (247x menší ako Google Analytics), zanedbateľný dopad na Core Web Vitals
GDPR/CCPA kompatibilný od návrhu: Žiadne spracovanie osobných údajov znamená žiadne požiadavky na súhlas
Plné vlastníctvo dát: Self-hosting alebo managed služba s kompletnou kontrolou nad vašimi dátami
Open source: Licencovaný pod AGPL-3.0; skontrolujte kód, prispievajte a prispôsobte podľa vašich potrieb
All-in-one platforma: Analytika, feature flags, sledovanie chýb a Web Vitals monitoring v jednom nástroji
Ekologický: Až 10x energeticky efektívnejší ako tradičné analytické riešenia

Možnosti nasadenia

Databuddy je možné nasadiť niekoľkými spôsobmi v závislosti od vašich infraštruktúrnych preferencií a požiadaviek na škálovanie.

Možnosť 1: Managed Cloud (najrýchlejší štart)

Najrýchlejší spôsob ako začať je použiť managed cloud službu Databuddy na databuddy.cc. Zaregistrujte sa, pridajte svoju doménu a vložte tracking skript.

<!-- Pridajte do head sekcie vášho HTML -->
<script
  src="https://cdn.databuddy.cc/databuddy.js"
  data-client-id="VAS_CLIENT_ID"
  async>
</script>

Managed služba zahŕňa:

Free tier s až 10,000 mesačnými eventami
Real-time analytický dashboard
Automatické aktualizácie a údržbu
CDN-delivered tracking skript
Feature flags s milisekundovými globálnymi deploymentmi
Sledovanie chýb a Web Vitals monitoring

Možnosť 2: Self-Hosted

Pre organizácie vyžadujúce kompletnú kontrolu nad dátami je self-hosting dostupný. Databuddy používa Bun ako runtime a vyžaduje Postgres (alebo Neon) aj ClickHouse pre optimálny výkon.

Predpoklady

Bun 1.3.4+ alebo Node.js 20+
Docker a Docker Compose (pre kontajnerizované nasadenie)
Postgres databáza (alebo Neon Postgres pre serverless)
ClickHouse inštancia pre analytické dáta
Minimum 2GB RAM (odporúčané 4GB)
Doménové meno so SSL certifikátom

Konfigurácia prostredia

# .env konfigurácia
DATABASE_URL="postgres://databuddy:password@localhost:5432/databuddy"
CLICKHOUSE_URL="http://default:@localhost:8123/databuddy_analytics"
SECRET_KEY=$(openssl rand -hex 32)

Docker Compose Setup

Naklonujte repozitár a použite dodaný docker-compose.yaml:

# Naklonujte repozitár
git clone https://github.com/databuddy-analytics/Databuddy.git
cd Databuddy

# Nakonfigurujte prostredie
cp .env.example .env
# Upravte .env s vašimi nastaveniami

# Spustite všetky služby
docker compose up -d

# Skontrolujte logy
docker compose logs -f

Pre detailné inštrukcie k self-hostingu pozrite oficiálnu dokumentáciu na databuddy.cc/docs.

Integračná príručka

Keď Databuddy beží, integrujte tracking skript do vášho webu alebo aplikácie.

Základná HTML integrácia

<!DOCTYPE html>
<html>
<head>
  <!-- Pridajte Databuddy tracking skript -->
  <script
    src="https://cdn.databuddy.cc/databuddy.js"
    data-client-id="VAS_CLIENT_ID"
    data-track-screen-views="true"
    data-track-attributes="true"
    data-track-errors="true"
    async>
  </script>
</head>
<body>
  <!-- Váš obsah -->
</body>
</html>

Next.js integrácia (App Router)

// app/layout.tsx
import { Databuddy } from '@databuddy/sdk/react';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="sk">
      <body>
        <Databuddy
          clientId={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID!}
          trackScreenViews={true}
          trackPerformance
          trackWebVitals={true}
          trackErrors={true}
        />
        {children}
      </body>
    </html>
  );
}

Next.js integrácia (Pages Router)

// pages/_app.tsx
import type { AppProps } from 'next/app';
import { Databuddy } from '@databuddy/sdk/react';
import { useRouter } from 'next/router';
import { useEffect } from 'react';
import { track } from '@databuddy/sdk';

function MyApp({ Component, pageProps }: AppProps) {
  const router = useRouter();

  useEffect(() => {
    const handleRouteChange = (url: string) => {
      track('screen_view', {
        screen_name: url,
        screen_class: 'Next.js'
      });
    };

    router.events.on('routeChangeComplete', handleRouteChange);
    return () => {
      router.events.off('routeChangeComplete', handleRouteChange);
    };
  }, [router.events]);

  return (
    <>
      <Databuddy
        clientId={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID!}
        trackScreenViews={true}
        trackAttributes={true}
      />
      <Component {...pageProps} />
    </>
  );
}

export default MyApp;

React SPA integrácia

# Nainštalujte SDK
bun add @databuddy/sdk
# alebo
npm install @databuddy/sdk

// App.tsx
import { Databuddy } from '@databuddy/sdk/react';

function App() {
  return (
    <>
      <Databuddy
        clientId="VAS_CLIENT_ID"
        trackScreenViews
        trackHashChanges
        trackAttributes
      />
      {/* Vaše komponenty aplikácie */}
    </>
  );
}

WordPress integrácia

Pridajte skript pomocou pluginu ako "Insert Headers and Footers" alebo priamo vo vašej téme:

<script
  src="https://cdn.databuddy.cc/databuddy.js"
  data-client-id="VAS_CLIENT_ID"
  data-track-screen-views="true"
  data-track-attributes="true"
  data-track-outgoing-links="true"
  async>
</script>

Shopify integrácia

Pridajte do vášho theme.liquid súboru pred uzatváraciu značku </head>:

<script
  src="https://cdn.databuddy.cc/databuddy.js"
  data-client-id="VAS_CLIENT_ID"
  data-track-screen-views="true"
  data-track-attributes="true"
  data-track-outgoing-links="true"
  async>
</script>

Custom Event Tracking

Okrem automatického pageview trackingu Databuddy podporuje custom eventy pre sledovanie špecifických akcií používateľov.

Základný Event Tracking

import { track } from '@databuddy/sdk';

// Trackujte custom event
track('signup_clicked', {
  plan: 'pro',
  source: 'pricing_page'
});

// Trackujte odoslanie formulárov
document.querySelector('#contact-form').addEventListener('submit', (e) => {
  track('form_submit', {
    form_name: 'contact',
    has_message: e.target.message.value.length > 0
  });
});

// Trackujte kliknutia na tlačidlá
document.querySelector('.cta-button').addEventListener('click', () => {
  track('cta_click', {
    button_text: 'Začať',
    page: window.location.pathname
  });
});

E-commerce Event Tracking

import { track } from '@databuddy/sdk';

// Trackujte zobrazenia produktov
track('product_view', {
  product_id: 'SKU123',
  product_name: 'Premium Widget',
  category: 'widgets',
  price: 99.99,
  currency: 'EUR'
});

// Trackujte pridanie do košíka
track('add_to_cart', {
  product_id: 'SKU123',
  quantity: 2,
  cart_value: 199.98
});

// Trackujte nákupy (agregované, bez PII)
track('purchase_completed', {
  order_value: 199.98,
  item_count: 2,
  payment_method: 'card',
  currency: 'EUR'
});

Conversion Funnel Tracking

import { track } from '@databuddy/sdk';

// Trackujte kroky funnelu
const trackFunnelStep = (step, data = {}) => {
  track('funnel_step', {
    funnel_name: 'onboarding',
    step_number: step,
    step_name: data.name,
    ...data
  });
};

// Použitie
trackFunnelStep(1, { name: 'signup_started' });
trackFunnelStep(2, { name: 'email_verified' });
trackFunnelStep(3, { name: 'profile_completed' });
trackFunnelStep(4, { name: 'first_action' });

Feature Flags

Databuddy obsahuje vstavané feature flags, čím eliminuje potrebu samostatnej služby.

import { useFlags } from '@databuddy/sdk/react';

function MyComponent() {
  const { isEnabled } = useFlags();
  const newDashboard = isEnabled('new-dashboard');

  return (
    <div>
      {newDashboard.isReady && newDashboard.enabled && (
        <NewDashboard />
      )}
    </div>
  );
}

Sledovanie chýb

Automaticky zachytávajte a sledujte chyby vo vašej aplikácii:

import { trackError } from '@databuddy/sdk';

// Automatické sledovanie chýb je povolené s trackErrors={true}
// Manuálne sledovanie chýb:
trackError('API požiadavka zlyhala', {
  endpoint: '/api/products',
  error_type: 'network_error'
});

Dashboard a Reporting

Databuddy poskytuje real-time analytický dashboard s kľúčovými metrikami a vizualizáciami.

Dostupné metriky

Návštevníci: Unikátne a celkové počty návštevníkov (session-based, nie user-based)
Page Views: Celkové zobrazenia stránok s rozpisom podľa URL
Bounce Rate: Percento single-page sessions
Trvanie session: Priemerný čas strávený na stránke
Zdroje návštevnosti: Rozpis referrerov bez osobného sledovania
Geografia: Krajina/región na základe anonymizovanej IP geolokácie
Zariadenia: Distribúcia prehliadačov a typov zariadení
Custom Eventy: Všetky sledované eventy s rozpisom properties
Feature Flags: Metriky použitia a adopcie
Chyby: Sledovanie chýb s kontextom

Web Vitals Monitoring

Databuddy automaticky sleduje Core Web Vitals pre monitoring výkonu:

LCP (Largest Contentful Paint): Výkon načítania
FID (First Input Delay): Responzívnosť interaktivity
CLS (Cumulative Layout Shift): Vizuálna stabilita
TTFB (Time to First Byte): Čas odpovede servera
FCP (First Contentful Paint): Čas prvého renderingu

API prístup

Pristupujte k vašim analytickým dátam programovo cez Databuddy API.

Autentifikácia

# Vygenerujte API kľúč v nastaveniach dashboardu
export DATABUDDY_API_KEY="vas-api-kluc"

# Všetky API požiadavky vyžadujú kľúč v hlavičkách
curl -H "Authorization: Bearer $DATABUDDY_API_KEY" \
  https://basket.databuddy.cc/api/v1/stats

Načítanie štatistík

// Načítanie štatistík návštevníkov za posledných 30 dní
const response = await fetch('https://basket.databuddy.cc/api/v1/stats', {
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  method: 'POST',
  body: JSON.stringify({
    site_id: 'vas-site-id',
    period: '30d',
    metrics: ['visitors', 'pageviews', 'bounce_rate'],
    dimensions: ['page', 'source']
  })
});

const data = await response.json();
console.log(data);

Privacy architektúra

Pochopenie ako Databuddy dosahuje privacy-first analytiku pomáha zabezpečiť správne nasadenie.

Čo Databuddy NEZBIERA

IP adresy (okamžite anonymizované, nikdy uložené v pôvodnej forme)
Identifikátory používateľov alebo cookies
Device fingerprints
Cross-site tracking dáta
Osobné informácie akéhokoľvek druhu
Mená, emailové adresy alebo akékoľvek PII od návštevníkov webu

Čo Databuddy ZBIERA

URL stránky a referrer
Rozmery viewportu a typ zariadenia
Prehliadač a OS (z user agent, agregované)
Krajina/región (z anonymizovanej IP geolokácie)
Session-level engagement metriky
Custom eventy, ktoré explicitne trackujete
Web Vitals výkonnostné dáta

Session Management bez Cookies

Databuddy používa kombináciu neidentifikujúcich signálov na detekciu sessions bez perzistentného úložiska. Session hash sa mení denne a nemôže identifikovať vracajúcich sa používateľov naprieč dňami alebo sessions—len zoskupuje pageviews v rámci jednej návštevy.

Kľúčové princípy súkromia:

Všetky dáta sú agregované a anonymizované
Žiadna schopnosť cross-site trackingu
Nevytvárajú sa používateľské profily
Dáta sa nikdy nepredávajú ani nezdieľajú s tretími stranami
GDPR právny základ: Oprávnené záujmy (nevyžaduje sa súhlas)

Možnosti konfigurácie skriptu

Prispôsobte správanie sledovania pomocou data atribútov:

<script
  src="https://cdn.databuddy.cc/databuddy.js"
  data-client-id="VAS_CLIENT_ID"
  data-track-screen-views="true"
  data-track-attributes="true"
  data-track-outgoing-links="true"
  data-track-interactions="true"
  data-track-performance="true"
  data-track-web-vitals="true"
  data-track-errors="true"
  data-track-scroll-depth="true"
  data-track-hash-changes="true"
  data-debug="false"
  async>
</script>

Riešenie problémov

Skript sa nenačítava

Skontrolujte konzolu prehliadača pre chyby
Overte, že data-client-id zodpovedá vášmu nakonfigurovanému site ID
Uistite sa, že URL skriptu je správna a prístupná
Skontrolujte ad blockery (niektoré môžu blokovať analytické skripty)
Vymažte cache prehliadača a testujte v inkognito režime

Eventy sa nezobrazujú

Overte, že window.databuddy je definovaný pred trackovaním
Uistite sa, že názvy eventov dodržiavajú konvenciu (preferovaný snake_case)
Skontrolujte dashboard—eventy sa zobrazujú v real-time
Povoľte debug režim s data-debug="true" pre logovania v konzole

React/Next.js problémy

Uistite sa, že SDK je nainštalované: bun add @databuddy/sdk
Overte, že environment variable je nastavená: NEXT_PUBLIC_DATABUDDY_CLIENT_ID
Skontrolujte, že Databuddy komponent je renderovaný vo vašom layoute

Zdroje a podpora

Dokumentácia: databuddy.cc/docs
GitHub Repozitár: github.com/databuddy-analytics/Databuddy
Discord Komunita: discord.gg/JTk7a38tCZ
Twitter: @trydatabuddy
Email Podpora: support@databuddy.cc

Databuddy poskytuje moderný prístup k webovej analytike, ktorý uprednostňuje súkromie aj presnosť. Eliminovaním cookies a zberu osobných údajov získate 100% viditeľnosť návštevníkov pri zachovaní plnej regulačnej compliance. Začnite s managed službou pre rýchle nasadenie, alebo preskúmajte self-hosting pre kompletnú dátovú suverenitu.

Začíname s Databuddy bezcookies analytikou