Skip to main content

Tracker Script

Installation​

To track website events, you just need inject a simple script(< 2 KB) into your website.

the script look like below:

<script async defer src="https://<your-self-hosted-domain>/tracker.js" data-website-id="xxxxxxxxxxxxx"></script>

you can get this script code from your Tianji website list

Operating System Version​

The tracker records osVersion when the browser provides it through User-Agent Client Hints. The server also reads Android and iOS versions from user agents that expose them. Windows client hints are mapped to Windows 10 or 11; reduced user agents such as Windows NT 10.0 and Android 10; K are not treated as reliable versions.

Switch the OS table to OS Version to see the distribution. Browsers that hide this information and historical records without a version are shown as unknown. Deploy the updated tracker and server migrations to start collecting this field.

Script Attributes​

The tracker script supports the following data-* attributes on the <script> tag:

AttributeRequiredDefaultDescription
data-website-idYes—The unique website ID for associating tracking data. The tracker will not initialize without this.
data-host-urlNoScript src originThe backend server URL. If omitted, it is automatically derived from the script's src path.
data-auto-trackNotrueAutomatically track page views and route changes. Set to "false" to disable.
data-do-not-trackNo—When set, respects the browser's Do Not Track (DNT) setting and disables tracking if DNT is enabled.
data-domainsNo—A comma-separated list of domains to track (e.g. "example.com,www.example.com"). Tracking is only active when the current hostname matches one of these domains.

Full Example​

<script
async
defer
src="https://example.com/tracker.js"
data-website-id="clxxxxxxxxxxxxxxxxxx"
data-host-url="https://analytics.example.com"
data-auto-track="true"
data-do-not-track="true"
data-domains="example.com,www.example.com"
></script>

Disable Tracking via localStorage​

You can also disable tracking at runtime by setting a localStorage flag:

localStorage.setItem('tianji.disabled', '1');

Report Event​

Tianji provide a simple way to report user click event, its easy to help you track which action user like and often to use.

This is a very common method in website analysis. You can use it quickly get it by using Tianji.

Basic Usage​

After you inject script code into your website, you just need add a data-tianji-event in dom attribute.

for example:

<button data-tianji-event="submit-login-form">Login</button>

Now, when user click this button, your dashboard will receive new event

Attach Event Data​

You can attach additional data to your events by using data-tianji-event-{key} attributes. Any attribute matching this pattern will be collected and sent with the event.

<button 
data-tianji-event="purchase"
data-tianji-event-product="Premium Plan"
data-tianji-event-price="99"
data-tianji-event-currency="USD">
Buy Now
</button>

This will send an event named purchase with the following data:

{
"product": "Premium Plan",
"price": "99",
"currency": "USD"
}

When using data-tianji-event on anchor (<a>) tags, Tianji handles them specially to ensure the event is tracked before navigation:

<a href="/pricing" data-tianji-event="view-pricing">Check Pricing</a>

For internal links (not opening in new tab), the tracker will:

  1. Prevent the default navigation
  2. Send the tracking event
  3. Navigate to the target URL after tracking completes

For external links or links with target="_blank", the event is tracked without blocking the navigation.

JavaScript API​

After the tracker script is loaded, you can also track events programmatically using the window.tianji object.

Track Custom Events​

// Simple event tracking
window.tianji.track('button-clicked');

// Event with custom data
window.tianji.track('purchase', {
product: 'Premium Plan',
price: 99,
currency: 'USD'
});

// Track with custom payload object
window.tianji.track({
website: 'your-website-id',
name: 'custom-event',
data: { key: 'value' }
});

// Track using a function (receives current page info)
window.tianji.track((payload) => ({
...payload,
name: 'dynamic-event',
data: { timestamp: Date.now() }
}));

Identify Users​

You can attach user information to tracking sessions:

window.tianji.identify({
userId: 'user-123',
email: 'user@example.com',
plan: 'premium'
});

This information will be associated with subsequent events from this user.

Modify default script name​

This feature available on v1.7.4+

You can use environment CUSTOM_TRACKER_SCRIPT_NAME when you start it

for example:

CUSTOM_TRACKER_SCRIPT_NAME="my-tracker.js"

then you can visit your tracker script with "https://<your-self-hosted-domain>/my-tracker.js"

This is to help you avoid some ad-blockers.

You do not need the .js suffix. It can be any path you choose, even you can use as CUSTOM_TRACKER_SCRIPT_NAME="this/is/very/long/path"

Tracking Specified Domains Only​

Generally the tracker will report all events wherever your site is running. But sometimes we need to ignore events like localhost.

Tianji provides an attribute of the tracker script to do that.

You can add data-domains into your script. The value should be your root domains to track. Use , to separate multiple domains.

<script async defer src="https://<your-self-hosted-domain>/tracker.js" data-website-id="xxxxxxxxxxxxx" data-domains="website.com,www.website.com"></script>

Then you can just see the events from these domains.