Skip to main content

​
Quick Start

The Tinybird web analytics tracker (@tinybirdco/flock.js) is a lightweight JavaScript library that tracks page views, custom events, and web vitals on your website.

​
Script Installation

Add the following script tag within your site’s <head> section: 
<script
  defer
  src="https://unpkg.com/@tinybirdco/flock.js"
  data-token="YOUR_TRACKER_TOKEN"
></script>
Get your tracker token from Tinybird Cloud under “Manage Auth Tokens”.

​
Verification

Once the script is installed, you should immediately start receiving page_hit events as visitors view and interact with your website. You can verify this in your Tinybird workspace by checking the analytics_events data source.

​
Configuration Parameters

The tracker script supports several configuration parameters that can be added as data attributes to the script tag.

​
Required Parameters

​
data-token
string
required
Your Tinybird tracker token. Find it in the Tinybird UI under “Manage Auth Tokens”.
<script
  src="https://unpkg.com/@tinybirdco/flock.js"
  data-token="p.eyJ1IjogImFiY2QxMjM0In0..."
></script>

​
Optional Parameters

​
data-host
string
Tinybird host URL. Defaults to https://api.tinybird.co/.Use this if you’re on a different region or a dedicated cluster:
  • US East: https://api.us-east.tinybird.co
  • EU: https://api.tinybird.co (default)
<script
  src="https://unpkg.com/@tinybirdco/flock.js"
  data-token="YOUR_TOKEN"
  data-host="https://api.us-east.tinybird.co"
></script>
​
data-datasource
string
Override the default landing data source name. Defaults to analytics_events.Use this if you’ve customized your data source or want to ingest events into a different one.
<script
  src="https://unpkg.com/@tinybirdco/flock.js"
  data-token="YOUR_TOKEN"
  data-datasource="custom_analytics"
></script>
​
data-proxy
string
Your domain URL to proxy tracking requests. Cannot be used together with data-proxy-url.The tracker will automatically append /api/tracking to the domain.
<script
  src="https://unpkg.com/@tinybirdco/flock.js"
  data-token="YOUR_TOKEN"
  data-proxy="https://yourdomain.com"
></script>
Do not use both data-proxy and data-proxy-url together. The script will throw an error.
​
data-proxy-url
string
A complete proxy URL endpoint for tracking requests. Cannot be used together with data-proxy.Use this when you need to specify a custom tracking endpoint beyond just the domain.
<script
  src="https://unpkg.com/@tinybirdco/flock.js"
  data-token="YOUR_TOKEN"
  data-proxy-url="https://yourdomain.com/custom/tracking/endpoint"
></script>
​
web-vitals
boolean
default:"false"
Enable Web Vitals tracking. Set to true to track Core Web Vitals metrics.
<script
  src="https://unpkg.com/@tinybirdco/flock.js"
  data-token="YOUR_TOKEN"
  web-vitals="true"
></script>
See Web Vitals for more details.
​
data-storage
string
default:"cookie"
Storage method for session management. Options: cookie, localStorage, sessionStorage.
<script
  src="https://unpkg.com/@tinybirdco/flock.js"
  data-token="YOUR_TOKEN"
  data-storage="localStorage"
></script>
​
data-stringify-payload
boolean
default:"true"
Whether to stringify the payload. Set to false to send the payload as an object.
<script
  src="https://unpkg.com/@tinybirdco/flock.js"
  data-token="YOUR_TOKEN"
  data-stringify-payload="false"
></script>

​
Multi-tenancy and Multi-domain

The tracker supports collecting data from multiple tenants and domains in a single data source.
​
data-domain
string
Domain identifier for multi-domain tracking.
<script
  src="https://unpkg.com/@tinybirdco/flock.js"
  data-token="YOUR_TOKEN"
  data-domain="project_domain"
></script>
​
data-tenant-id
string
Tenant identifier for multi-tenancy support.
<script
  src="https://unpkg.com/@tinybirdco/flock.js"
  data-token="YOUR_TOKEN"
  data-tenant-id="project_tenant_id"
></script>

​
Filtering by Tenant

All endpoints can be filtered by tenant_id and domain. You can also use JWT tokens with fixed params: 
{
  "fixed_params": {
    "tenant_id": "your-tenant-id"
  }
}
Learn more about JWT tokens in Tinybird.

​
Complete Example

Here’s a full example with multiple configuration options: 
<!DOCTYPE html>
<html>
  <head>
    <title>My Website</title>
    <!-- Tinybird Analytics -->
    <script
      defer
      src="https://unpkg.com/@tinybirdco/flock.js"
      data-token="p.eyJ1IjogImFiY2QxMjM0In0..."
      data-host="https://api.tinybird.co"
      data-domain="mywebsite.com"
      data-tenant-id="tenant-123"
      web-vitals="true"
      data-storage="localStorage"
    ></script>
  </head>
  <body>
    <h1>Welcome to my website</h1>
  </body>
</html>

​
Next Steps

Page Views

Learn how page view tracking works

Custom Events

Track custom events on your website

Web Vitals

Monitor Core Web Vitals metrics

Configuration

Advanced configuration options

Build docs developers (and LLMs) love

Get started for freeTalk to us