Skip to content

Custom events

Interactions, servers and bot health are recorded automatically. For anything else, such as a ticket opened, a game finished or a purchase flow started, call track().

tickets.ts
import type { Shardlens } from '@shardlens/discordjs';
import type { ButtonInteraction } from 'discord.js';
// Register your events once for typed track() calls. Without this, any lower_snake_case name is accepted.
declare module '@shardlens/discordjs' {
interface CustomEvents {
ticket_opened: { category: 'billing' | 'support' | 'other'; priority: number };
ticket_closed: { category: 'billing' | 'support' | 'other'; resolved: boolean };
}
}
declare const lens: Shardlens;
export function onOpenTicket(interaction: ButtonInteraction, category: 'billing' | 'support' | 'other') {
// The user ID is hashed inside your bot before anything is sent.
lens.track('ticket_opened', { category, priority: 2 }, { userId: interaction.user.id, guildId: interaction.guildId });
}
  • Names are lower snake case, start with a letter and are up to 64 characters: ticket_opened.
  • Properties are strings (up to 256 characters), finite numbers, booleans or null, up to 2 KB in total. Keys are up to 64 characters.
  • String values pass through secret redaction, so a token pasted into a property is replaced before it leaves your bot. Even so, never put message content, usernames or other personal data in properties.
  • The user ID is optional and is hashed in your bot, exactly like interaction users, so custom events count towards unique users without the ID leaving the process.
  • Invalid events are dropped and counted in SDK health. track() never throws.

Without the declare module block, track() accepts any valid name and any properties. Once you register events, TypeScript checks every call: unknown names and wrong property types are compile errors.

Declare them on @shardlens/discordjs, the package your bot depends on. Declaring them on @shardlens/core, where the interface lives, works too, but only where your package manager lets your code import a dependency of a dependency: pnpm doesn’t, and TypeScript then reports that the module can’t be found.

The dashboard’s Events page lists every custom event with its count and the number of people, breaks each event down by property, and has two builders:

  • Funnels: pick 2 to 5 steps (custom events or commands) and a window. Shardlens counts the people who did each step in order, within the window of their first step, with the conversion between steps, the median time to each step, and a breakdown by the day people entered.
  • Cohorts: pick what people started with and what counts as coming back (a specific event or command, or any activity). Shardlens groups people by the day or week they started and shows how many came back 1, 2, … periods later.

Steps are linked by each person’s salted hash, inside the collector. Only counts leave it: there is no per-person view and the query API can’t return a hash. Two consequences of the privacy model:

  • A journey that crosses into a new salt period counts as a new person, because the hash changes. With the default monthly period this only affects journeys that span the turn of a month.
  • Funnels and cohorts read raw events, so they cover the raw-retention window (35 days by default).