Installation

Agentic setup

Install the Trodo AI skill to let your coding agent install Trodo automatically. It detects your frontend framework, backend runtime, and auth provider, then wires Trodo.init, identify, groups, sessions, and a starter custom-event set — using the user identifier your app already keys on.

Ask your coding agent
Manual installation

Point your agent at the skill repository and ask it to install events. Replace YOUR_SITE_ID with the value from app.trodo.ai → Settings → Sites:

Install the Trodo AI skill from https://github.com/trodoai/skills and use it to enable tracking and events to this application, with siteId YOUR_SITE_ID.

The skill works with Cursor, Claude Code, Windsurf, and any other assistant that can read files in your repo or fetch from GitHub. For agent analytics (LLM and tool spans), use the Agent Analytics Quickstart — the same skill repo handles both tracks.

Install the entire Trodo skill swarm via the skills CLI:

npx skills add trodoai/skills --all

Then prompt your agent:

Use the Trodo AI skill to enable tracking and events to this application, with siteId YOUR_SITE_ID.

Prefer to do it by hand? The manual instructions below cover every surface.

Overview

Trodo ships three browser install methods (CDN script, Google Tag Manager, npm) and two server SDKs (Node.js, Python). Pick one per surface; you can mix them in the same project against the same Site ID.

Browser vs. server. The browser SDK is stateful — after Trodo.identify(...) the distinct id lives in session/localStorage and every subsequent call uses it automatically. The server SDKs are stateless — distinctId (Node) or distinct_id (Python) is required as the first argument on every call. See Server SDKs below.

Client SDK

CDN (Recommended)
npm Package
Google Tag Manager

CDN Installation

The fastest way to get started. Add this script to your HTML <head>:

<script>
  var script = document.createElement('script');
  script.src = 'https://cdn.trodo.ai/scripts/analytics/trodo.script.min.js';  
  script.setAttribute('site-id', 'YOUR_SITE_ID');
  script.setAttribute('auto-events', 'true');
  document.head.appendChild(script);
</script>

Configuration Attributes

Attribute	Type	Default	Description
`site-id`	string	required	Your unique site identifier
`auto-events`	string	omitted (= off)	Set to `true` to enable automatic event tracking; any other value leaves auto-events disabled
`auto-events-disabled-paths`	string	`''`	Comma-separated paths to exclude
`auto-events-disabled-events`	string	`''`	Comma-separated auto event names to disable (see Auto-Events)

Full Configuration Example

<script>
  var script = document.createElement('script');
  script.src = 'https://cdn.trodo.ai/scripts/analytics/trodo.script.min.js';  
  script.setAttribute('site-id', 'myapp-com-42');
  script.setAttribute('auto-events', 'true');
  script.setAttribute('auto-events-disabled-paths', '/admin,/internal');
  script.setAttribute('auto-events-disabled-events', 'text_selection,copy_action');
  document.head.appendChild(script);
</script>

Complete HTML Example

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>My App</title>
  
  <!-- Trodo - load early for complete tracking -->
  <script>
    var script = document.createElement('script');
    script.src = 'https://cdn.trodo.ai/scripts/analytics/trodo.script.min.js';  
    script.setAttribute('site-id', 'YOUR_SITE_ID');
    script.setAttribute('auto-events', 'true');
    document.head.appendChild(script);
  </script>
</head>
<body>
  <!-- Your content -->
</body>
</html>

After loading via CDN, the global Trodo object is available:

// Track events
Trodo.track('button_clicked', { button_name: 'signup' });

// Identify users
Trodo.identify('user_123');

// Set user properties
Trodo.people.set({ plan: 'pro' });

npm Installation

For JavaScript/TypeScript projects with a build system:

npm install trodo

Or with yarn:

yarn add trodo

Basic Usage

import Trodo from 'trodo';

// Initialize (async – returns the same Trodo instance)
await Trodo.init({
  siteId: 'YOUR_SITE_ID',
  autoEvents: true
});

// Use the global Trodo object
Trodo.track('button_clicked', { button_name: 'signup' });
Trodo.identify('user_123');
Trodo.people.set({ plan: 'pro' });

Configuration Options

import Trodo from 'trodo';

await Trodo.init({
  // Required
  siteId: 'YOUR_SITE_ID',
  
  // Optional
  autoEvents: true,                    // Enable auto-tracking
  autoEventsDisabledPaths: [           // Paths to exclude
    '/admin',
    '/checkout'
  ],
  autoEventsDisabledEvents: [          // Auto event names to disable
    'text_selection',
    'copy_action'
  ],
  debug: false                         // Enable console logging
});

React Integration

// lib/trodo.js
import Trodo from 'trodo';

let initialized = false;

export async function initTrodo() {
  if (initialized) return;
  
  await Trodo.init({
    siteId: process.env.REACT_APP_TRODO_SITE_ID,
    autoEvents: true
  });
  
  initialized = true;
}

// App.jsx
import { useEffect } from 'react';
import Trodo from 'trodo';
import { initTrodo } from './lib/trodo';

function App() {
  useEffect(() => {
    initTrodo();
  }, []);

  useEffect(() => {
    if (user) {
      Trodo.identify(user.id);
      Trodo.people.set({
        email: user.email,
        plan: user.plan
      });
    }
  }, [user]);

  return <YourApp />;
}

Next.js Integration

// lib/trodo.js
import Trodo from 'trodo';

let initialized = false;

export async function initTrodo() {
  if (typeof window === 'undefined') return;
  if (initialized) return;
  
  await Trodo.init({
    siteId: process.env.NEXT_PUBLIC_TRODO_SITE_ID,
    autoEvents: true
  });
  
  initialized = true;
}

// app/layout.jsx (App Router)
'use client';
import { useEffect } from 'react';
import { initTrodo } from '@/lib/trodo';

export default function RootLayout({ children }) {
  useEffect(() => {
    initTrodo();
  }, []);

  return (
    <html>
      <body>{children}</body>
    </html>
  );
}

// Any component
import Trodo from 'trodo';

function MyComponent() {
  const handleClick = () => {
    Trodo.track('feature_used', { feature: 'swap' });
  };

  return <button onClick={handleClick}>Swap</button>;
}

Vue Integration

// plugins/trodo.js
import Trodo from 'trodo';

export default {
  async install(app) {
    await Trodo.init({
      siteId: import.meta.env.VITE_TRODO_SITE_ID,
      autoEvents: true
    });
    
    app.config.globalProperties.$trodo = Trodo;
    app.provide('trodo', Trodo);
  }
};

// main.js
import { createApp } from 'vue';
import App from './App.vue';
import trodoPlugin from './plugins/trodo';

const app = createApp(App);
app.use(trodoPlugin);
app.mount('#app');

// Component usage
import Trodo from 'trodo';

Trodo.track('feature_used', { feature: 'swap' });

Google Tag Manager

Deploy Trodo via GTM without modifying your codebase.

Setup Steps

Create New Tag

In GTM, go to Tags → New → Tag Configuration → Custom HTML

Add Script

Paste the following code:

<script>
  var script = document.createElement('script');
  script.src = 'https://cdn.trodo.ai/scripts/analytics/trodo.script.min.js';  
  script.setAttribute('site-id', 'YOUR_SITE_ID');
  script.setAttribute('auto-events', 'true');
  document.head.appendChild(script);
</script>

Set Trigger

Click Triggering → Select All Pages

Save and Publish

Click Save, then Submit to publish

Full Configuration

<script>
  var script = document.createElement('script');
  script.src = 'https://cdn.trodo.ai/scripts/analytics/trodo.script.min.js';  
  script.setAttribute('site-id', 'YOUR_SITE_ID');
  script.setAttribute('auto-events', 'true');
  script.setAttribute('auto-events-disabled-paths', '/admin,/internal');
  script.setAttribute('auto-events-disabled-events', 'text_selection,copy_action');
  document.head.appendChild(script);
</script>

Custom Events via Data Layer

Push events from your site to GTM, then forward to Trodo:On your website:

dataLayer.push({
  event: 'trodo_track',
  eventName: 'button_clicked',
  eventProperties: { button_name: 'signup' }
});

GTM Custom HTML Tag:

<script>
  if (window.Trodo) {
    Trodo.track('{{DL - eventName}}', {{DL - eventProperties}});
  }
</script>

Server SDKs

For backend services, background workers, and any environment where you control the runtime, use the Node.js or Python SDK. Both are stateless — you pass the end-user’s distinctId (Node) / distinct_id (Python) as the first argument on every call. The SDK does not maintain an implicit “current user” across calls the way the browser does.

Pass the distinct id on every call. There is no session cookie on the server — if you omit it, Trodo cannot attribute events to a user. If you’re making several calls in a row for the same user, bind once with forUser(distinctId) / for_user(distinct_id) and call methods on the returned context.

Install

Node.js
Python

npm install trodo-node

Node 16+ (18+ recommended for built-in fetch). TypeScript types ship with the package.

pip install trodo-python

Python 3.8+. Sync client uses requests; optional async primitives install via pip install trodo-python[async].

Initialise once at boot

Node.js
Python

import trodo from 'trodo-node';

trodo.init({
  siteId: process.env.TRODO_SITE_ID,
  autoEvents: true, // capture uncaught exceptions as `server_error`
});

import os
import trodo

trodo.init(
    site_id=os.environ["TRODO_SITE_ID"],
    auto_events=True,  # capture uncaught exceptions as `server_error`
)

Use the same Site ID as your browser install. Both surfaces feed the same dashboards.

First call

Node.js
Python

// Direct style — distinct id as first arg
await trodo.track('user-42', 'invoice_paid', { amount_cents: 9999 });

// Bound style — bind once, call many
const user = trodo.forUser('user-42');
await user.track('invoice_paid', { amount_cents: 9999 });
await user.people.set({ plan: 'pro' });

# Direct style — distinct id as first arg
trodo.track("user-42", "invoice_paid", {"amount_cents": 9999})

# Bound style — bind once, call many
user = trodo.for_user("user-42")
user.track("invoice_paid", {"amount_cents": 9999})
user.people.set({"plan": "pro"})

Configuration options

Pass these only when you need to change defaults. Everything below is optional.

Option	Node	Python	Default
Site ID	`siteId`	`site_id`	required
Server auto-events	`autoEvents`	`auto_events`	`false`
API base	`apiBase`	`api_base`	`https://sdkapi.trodo.ai`
Request timeout	`timeout` (ms)	`timeout` (s)	10 s
Retries	`retries`	`retries`	`2` (backoff on network / 5xx)
Batch mode	`batchEnabled`	`batch_enabled`	`false`
Batch size	`batchSize`	`batch_size`	`50`
Flush interval	`batchFlushIntervalMs`	`batch_flush_interval`	5000 ms / 5 s
Error callback	`onError`	`on_error`	none
Verbose logs	`debug`	`debug`	`false`

Shutdown

When batching or auto-events are enabled, call flush() / shutdown() on process exit so queued events are not dropped:

Node.js
Python

process.on('SIGTERM', async () => {
  await trodo.shutdown();
});

import atexit
atexit.register(trodo.shutdown)

Verification

After installation, verify it’s working:

1. Check Browser Console

Open developer tools (F12) and look for:

[Trodo] Initialized successfully
[Trodo] Session started: abc123
[Trodo] Event tracked: page_view

2. Check Live Events

Go to your Trodo dashboard
Navigate to Live Events or Debugger
Perform actions on your site
Events should appear within 60 seconds

3. Network Tab

In browser dev tools → Network tab, look for requests to:

api.trodo.ai/events
api.trodo.ai/sessions

Troubleshooting

Script blocked by Content Security Policy

Add these domains to your CSP:

script-src 'self' https://cdn.trodo.ai;
connect-src 'self' https://api.trodo.ai;

Events not appearing

Verify Site ID is correct
Check domain is whitelisted in settings
Disable ad blockers temporarily
Check browser console for errors

Double-counting events

Ensure the script is only loaded once. If using both CDN and npm, choose one.

Script loading slowly

The CDN script is ~15KB gzipped. If performance is critical:

Use async loading (default)
Consider npm package for bundling
Load after critical resources

Next Steps

Auto-Events

Configure automatic event tracking

Track Custom Events

Learn the track() method

INTRO

DATA IN

BEST PRACTICES

Installation

Agentic setup

Overview

Client SDK

CDN Installation

Configuration Attributes

Full Configuration Example

Complete HTML Example

npm Installation

Basic Usage

Configuration Options

React Integration

Next.js Integration

Vue Integration

Google Tag Manager

Setup Steps

Full Configuration

Custom Events via Data Layer

Server SDKs

Install

Initialise once at boot

First call

Configuration options

Shutdown

Verification

1. Check Browser Console

2. Check Live Events

3. Network Tab

Troubleshooting

Next Steps

Auto-Events

Track Custom Events

INTRO

DATA IN

BEST PRACTICES

Documentation Index

​Agentic setup

​Overview

​Client SDK

​CDN Installation

​Configuration Attributes

​Full Configuration Example

​Complete HTML Example

​npm Installation

​Basic Usage

​Configuration Options

​React Integration

​Next.js Integration

​Vue Integration

​Google Tag Manager

​Setup Steps

​Full Configuration

​Custom Events via Data Layer

​Server SDKs

​Install

​Initialise once at boot

​First call

​Configuration options

​Shutdown

​Verification

​1. Check Browser Console

​2. Check Live Events

​3. Network Tab

​Troubleshooting

​Next Steps

Auto-Events

Track Custom Events

Agentic setup

Overview

Client SDK

CDN Installation

Configuration Attributes

Full Configuration Example

Complete HTML Example

npm Installation

Basic Usage

Configuration Options

React Integration

Next.js Integration

Vue Integration

Google Tag Manager

Setup Steps

Full Configuration

Custom Events via Data Layer

Server SDKs

Install

Initialise once at boot

First call

Configuration options

Shutdown

Verification

1. Check Browser Console

2. Check Live Events

3. Network Tab

Troubleshooting

Next Steps