Skip to main content
Build your own privacy-first web analytics platform using Tinybird’s Events API and Endpoints. This guide will help you deploy the data project, add tracking to your website, and access real-time analytics.

​
Prerequisites

Before you begin, make sure you have:
  • A Tinybird account and workspace
  • Node.js 22 or higher installed
  • Git installed on your machine
1
Clone the repository
2
First, clone the Web Analytics Starter Kit repository to your local machine:
3
git clone https://github.com/tinybirdco/web-analytics-starter-kit
cd web-analytics-starter-kit
4
Deploy the Tinybird data project
5
Navigate to the tinybird directory and install dependencies:
6
npm
cd tinybird
npm install
pnpm
cd tinybird
pnpm install
yarn
cd tinybird
yarn install
7
Login to your Tinybird account and deploy the project:
8
npx tinybird login
npx tinybird deploy
9
This command will:
10
  • Create the analytics_events datasource to store your web events
  • Deploy materialized views for aggregated metrics
  • Set up API endpoints for querying your analytics data
  • Create two authentication tokens: dashboard (for reading data) and tracker (for sending events)
    • 11
    The deployment process creates all necessary resources including datasources, pipes, materializations, and endpoints defined in the /tinybird/src directory.
    12
    Get your authentication tokens
    13
    After deployment, you’ll need two tokens:
    14
  • Tracker token - For sending events from your website
  • Dashboard token - For reading analytics data in the dashboard
    • 15
    You can find these tokens in your Tinybird dashboard under Manage Auth Tokens.
    16
    Keep your tokens secure! The tracker token will be public (embedded in your website), while the dashboard token should remain private.
    17
    Add tracking to your website
    18
    Add the following script within your website’s <head> section, replacing YOUR_TRACKER_TOKEN with your actual tracker token:
    19
    <script
  defer
  src="https://unpkg.com/@tinybirdco/flock.js"
  data-token="YOUR_TRACKER_TOKEN"
></script>
    20
    Once the script is loaded, you’ll automatically start receiving page_hit events as visitors view and interact with your website.
    21
    The defer attribute ensures the script doesn’t block page rendering, improving your site’s performance.
    22
    Optional tracking parameters
    23
    You can customize the tracking behavior with these optional parameters:
    24
    <script
  defer
  src="https://unpkg.com/@tinybirdco/flock.js"
  data-token="YOUR_TRACKER_TOKEN"
  data-host="https://api.tinybird.co"
  data-domain="example.com"
  data-tenant-id="my-tenant"
  web-vitals="true"
></script>
    25
    ParameterDescriptiondata-tokenYour tracker token (required)data-hostTinybird host URL. Defaults to https://api.tinybird.co/data-domainYour domain for multi-domain trackingdata-tenant-idTenant identifier for multi-tenancy supportweb-vitalsSet to "true" to track Core Web Vitals metricsdata-datasourceCustom datasource name if different from defaultdata-proxyYour domain URL to proxy requests (for GDPR compliance)
    26
    Access the dashboard
    27
    You have two options to view your analytics:
    28
    Option 1: Use the hosted dashboard
    29
    Visit https://analytics.tinybird.live and enter your dashboard token to access your analytics immediately.
    30
    Option 2: Deploy your own dashboard
    31
    For full customization, deploy the dashboard to Vercel:
    32
    npm
    cd dashboard
npm install
npm run dev
    pnpm
    cd dashboard
pnpm install
pnpm dev
    yarn
    cd dashboard
yarn install
yarn dev
    33
    Create a .env.local file in the dashboard directory:
    34
    # Tinybird Configuration (server-only, required)
TINYBIRD_TOKEN=your-dashboard-token
TINYBIRD_HOST=https://api.tinybird.co

# Dashboard URL (public)
NEXT_PUBLIC_TINYBIRD_DASHBOARD_URL=http://localhost:3000

# Tracker token for analytics (public, optional)
NEXT_PUBLIC_TINYBIRD_TRACKER_TOKEN=your-tracker-token

# Dashboard Basic Auth (server-only, defaults to admin/admin if not set)
DASHBOARD_USERNAME=admin
DASHBOARD_PASSWORD=changeme

# Optional: Set to "true" to disable auth during development
DISABLE_AUTH=false
    35
    Open http://localhost:3000 to view your analytics dashboard.
    36
    The dashboard includes built-in authentication with default credentials admin/admin. Customize these by setting DASHBOARD_USERNAME and DASHBOARD_PASSWORD environment variables.

    ​
    Track custom events

    Beyond automatic page views, you can track custom events for eCommerce, conversions, or any user interaction: 
    Tinybird.trackEvent('add_to_cart', {
  partnumber: 'A1708 (EMC 3164)',
  quantity: 1,
  price: 1299.99
})

    Tinybird.trackEvent('purchase', {
  order_id: 'ORD-12345',
  total: 2599.98,
  items: 2
})
    Custom events are stored in the payload column of the analytics_events datasource and can be queried through the Tinybird API.

    ​
    Track Web Vitals

    Monitor Core Web Vitals (LCP, FCP, TTFB, INP, CLS) by enabling the web-vitals parameter: 
    <script
  defer
  src="https://unpkg.com/@tinybirdco/flock.js"
  data-token="YOUR_TRACKER_TOKEN"
  web-vitals="true"
></script>
    Web Vitals events are automatically tracked with details about performance metrics: 
    {"name":"LCP","value":68,"delta":68,"id":"v3-1752067824029-4726354841567","pathname":"/","href":"http://localhost:8081/"}
{"name":"TTFB","value":41.1,"delta":41.1,"id":"v3-1752067821037-7353415626830","pathname":"/","href":"http://localhost:8081/"}

    ​
    Next steps

    Multi-tenancy

    Set up multi-tenant tracking for SaaS applications

    Custom attributes

    Add custom data attributes to every event

    GDPR compliance

    Implement privacy-first analytics with proxy tracking

    API reference

    Query your analytics data programmatically

    ​
    Verify your setup

    To confirm everything is working:
    1. Visit a page on your website with the tracking script installed
    2. Open your dashboard (hosted or local)
    3. Check the Current Visitors widget for real-time data
    4. Navigate through the dashboard to see page views, traffic sources, and device breakdowns
    It may take a few seconds for events to appear in your dashboard. Tinybird processes events in real-time, but your browser may cache dashboard data.

    ​
    Troubleshooting

    • Verify your tracker token is correct in the script tag
    • Check the browser console for any errors
    • Ensure the script is loaded (check Network tab in DevTools)
    • Confirm your dashboard token has read access to the endpoints
    • Ensure you’re logged in with npx tinybird login
    • Check that your admin token has deployment permissions
    • Verify Node.js version is 22 or higher
    • Try running pnpm install again to ensure dependencies are installed
    • Default credentials are admin/admin
    • Set custom credentials in .env.local using DASHBOARD_USERNAME and DASHBOARD_PASSWORD
    • For local development, you can disable auth with DISABLE_AUTH=true
    Need more help? Join the Tinybird Community Slack or check the Tinybird Documentation.

    Build docs developers (and LLMs) love

    Get started for freeTalk to us