Track Events
How to track custom events with Rybbit
The script exposes a global object window.rybbit with functions for manual tracking of events, as well as the ability to track events using data attributes on HTML elements.
Using Data Attributes
You can track custom events by adding data attributes to any HTML element:
<!-- Basic event tracking -->
<button data-rybbit-event="signup_clicked">Sign Up</button>
<!-- Event with custom properties -->
<button
data-rybbit-event="purchase_click"
data-rybbit-prop-product="premium"
data-rybbit-prop-price="49.99"
>
Buy Now
</button>This approach requires no JavaScript and works on any clickable element.
Available Functions
window.rybbit.event(eventName, properties)
Tracks a custom event with optional properties.
eventName(String): The name of the custom event (max 255 characters).properties(Object, Optional): An object containing custom data (max 2KB characters). Only strings numbers are supported as values.
// Track a simple custom event
window.rybbit.event("Signup Button Clicked");
// Track a custom event with properties
window.rybbit.event("Item Added To Cart", {
itemId: "PROD123",
price: 49.99,
category: "Clothing"
});window.rybbit.pageview()
Tracks a pageview. Useful when data-track-spa is set to "false" or when you need to manually trigger a pageview.
// Track a pageview
window.rybbit.pageview();TypeScript Support
Put this as rybbit.d.ts anywhere in your project to avoid having to do (window as any).rybbit.event() everywhere.
interface Rybbit {
/**
* Tracks a page view
*/
pageview: () => void;
/**
* Tracks a custom event
* @param name Name of the event
* @param properties Optional properties for the event
*/
event: (name: string, properties?: Record<string, any>) => void;
/**
* Sets a custom user ID for tracking logged-in users
* @param userId The user ID to set (will be stored in localStorage)
* @param traits Optional user metadata (email, name, custom fields)
*/
identify: (userId: string, traits?: Record<string, unknown>) => void;
/**
* Updates traits for the currently identified user
* @param traits User metadata to merge with existing traits
*/
setTraits: (traits: Record<string, unknown>) => void;
/**
* Clears the stored user ID
*/
clearUserId: () => void;
/**
* Gets the currently set user ID
* @returns The current user ID or null if not set
*/
getUserId: () => string | null;
/**
* Manually tracks outbound link clicks
* @param url The URL of the outbound link
* @param text Optional text content of the link
* @param target Optional target attribute of the link
*/
trackOutbound: (url: string, text?: string, target?: string) => void;
}
declare global {
interface Window {
rybbit: Rybbit;
}
}
export {};Server-Side Tracking
For tracking events from server-side applications, mobile apps, or any platform outside the browser, you can use the HTTP API. This is useful for:
- Server-side event tracking (Node.js, Python, Go, etc.)
- Mobile app analytics (iOS, Android, Flutter)
- Backend integrations and webhooks
- Scenarios where the JavaScript snippet can't be used
See the API documentation for detailed examples in multiple languages including authentication, parameters, and rate limiting information.
Related Documentation: