lilbird
v0.2.19
Published
A Tinybird Event API helper library in the style of Analytics.js
Downloads
7
Maintainers
Readme
LilBird
Tinybird Event API helper library.
Adds routine Analytics.js style tracking to Tinybird with as little setup as possible.
Tinybird Signup & Setup
- Head to https://www.tinybird.co/
- Create a new account
- Put your data into the EU region when prompted
- Create a new Auth Token. This is your
WRITE_KEY
.- You should only select:
DATA SOURCES SCOPES
- Create new Data Sources or append data to existing ones (ENABLED)
- This will allow your key to be used to send events to Tinybird, create Data Sources (tables) on the fly, and not much else.
- You should only select:
You should create a write-only key for your Tinybird instance. They'll give you a key with lots of permissions when you sign up. For security reasons, don't use this one.
Setup
Inline (HTML)
<script>window.TINYBIRD_CONFIGURATION = { WRITE_KEY: 'p.YOURTINYBIRDWRITEKEY' }</script>
<script src="https://cdn.jsdelivr.net/npm/lilbird@latest"></script>
You should create a write-only key for your Tinybird instance. See instructions above.
NPM
npm i -s lilbird
Then, in your project:
import * as Lilbird from 'lilbird';
Lilbird.init({ WRITE_KEY: 'p.YOURTINYBIRDWRITEKEY' });
Usage
Like most event analytics platforms, Lilbird exposes a track()
and an identify()
method.
Identify is used to set properties on your current user, which describes the user. For example, you could identify whether the user is a paying customer, or on a free trial, with identify({ trial: false })
Track sends an event to Tinybird, which includes every property identified for this user. For example, you could track('new_project_created')
to later visualize the number of new projects created over time.
If you wanted to track new projects created by type, you could send that like this; track('new_project_created', { type: 'IT' '})
.
It is recommended that you enforce types and set a default value for every column (user or event property) you send to Tinybird. See "Enforce Types" and "Default Values" below.
Event properties that are added automatically, if not defined
- A timestamp is appended to each event under the namespace
ts
- This is formatted as an ISOString (ISO 8601)
- A unique session identifier is stored in sessionStorage and appended to each event under the namespace
session_id
- An anonymous device identifier is appended to each event under the namespace
anonymous_device_id
- If your requirements are minimal, you can use this as your unique user identifier. Otherwise, send a
uid
oruuid
to whatever namespace you like, and use this as your fallback identifier for anonymous users.
- If your requirements are minimal, you can use this as your unique user identifier. Otherwise, send a
Disabling Automatic Event Properties
Each of these can be disabled by sending the appropriate configuration:
Lilbird.init({
WRITE_KEY: 'p.YOURTINYBIRDWRITEKEY',
ADD_ANONYMOUS_DEVICE_ID: false,
ADD_SESSION_ID: false,
ADD_TS: false,
});
Identifying users (Optional)
You can identify users before sending a track()
event. This appends data to the user, which will be sent alongside each track()
event.
Example:
var uid = '123456';
Lilbird.identify(uid, {
user: true,
age: 32,
admin: false,
beta: false,
name: 'John Doe',
});
UID is optional. You can omit it, or even include it in the body:
Lilbird.identify({
user: true,
age: 32,
admin: false,
beta: false,
name: 'John Doe',
});
Tracking Events
Events are tracked using the track()
method. This tracks an event by adding a row to a Data Source in Tinybird.
Event names can be letters, numbers, dashes, underscores, but no spaces or special characters.
Example:
var event_name = 'signed_up';
Lilbird.track(event_name, {
username: 'bob'
});
The payload is optional, and describes the event you are tracking. Be aware, namespaces conflict with values sent via the Identify method, and should be unique. If you have previously sent a value, it must be of the same type each time it is sent.
You can also track an event without a payload.
Lilbird.track('login');
Default Values
Tinybird enforces strict checks on each ingested row, and quarantines any row with a missing column. Therefore, it's a good idea to provide default values for every column that isn't nullable.
Keep in mind, sometimes rejected data is what you really want. Instead of allowing Tinybird to ingest bad data (like in our example below, login events without a username), you may want to skip defaults, and allow the invalid rows to be rejected. Otherwise, you're going to be writing SQL later to filter out the invalid data.
Here's an example of how you can set defaults with the DEFAULTS
configuration namespace:
Lilbird.init({
WRITE_KEY: 'p.YOURTINYBIRDWRITEKEY',
DEFAULTS: {
"*": {
"created_at": 0
},
"login": {
"username": "-"
}
}
});
In this example, if we sent a login
event with no body, it would get a default value for both created_at
and username
, preventing any related insertion errors.
Enforce Types
Tinybird enforces strict type checks on each ingested row, and rows with any column that doesn't match your schema will be quarantined and permanently rejected.
So, you can enforce types for your incoming data, via configuration, to prevent this from occurring.
Available types are:
- boolean
- integer
- string
- float
Here's an example:
Lilbird.init({
WRITE_KEY: 'p.YOURTINYBIRDWRITEKEY',
ENFORCE_TYPES: {
"*": {
"created_at": 'integer'
},
"login": {
"username": "string",
"company": "string",
"age": "integer",
"is_registered": "boolean",
"pixel_ratio": "float"
}
}
});
Custom Body Transformation (Advanced)
Tinybird has strict type checking and enforcement, so you may need to do data transformation on events before they're sent, to prevent validation errors.
You can do that with a BODY_TRANSFORMATION
function, which modifies the body before Tinybird ingestion.
Note: this is a synchronous function, which must return the body once it is modified.
Example:
Lilbird.init({
WRITE_KEY: 'p.YOURTINYBIRDWRITEKEY',
BODY_TRANSFORMATION: function(body, event_name) {
if (event_name === 'pageview') {
// Do something
if (typeof body.ts === 'string') body.ts = parseInt(body.ts);
}
return body;
}
});
Transform all numbers to strings
The configuration option TRANSFORM_NUMBERS_TO_STRINGS
transforms all properties which are numbers into strings.
Lilbird.init({
WRITE_KEY: 'p.YOURTINYBIRDWRITEKEY',
TRANSFORM_NUMBERS_TO_STRINGS: true
});