What tode tracks and why
tode records three kinds of events from a plugin: an action, an action with a number, and a session. Each event carries a few fields about where it happened. This page lists every field, the number on the dashboard it feeds, and what that number tells you about your plugin.
Nothing here is read from the document. tode never sees file names, layer names, text, selections or images. It sees the events you send and the environment they came from.
The three events
Action
tode.trackAction('replace_fonts');One name, one moment. You call it where something happens: a button, an export, a feature that finished its work.
On the dashboard: Actions per day stacked by name, Actions by name with each name's share, and Feature adoption, the share of active users who did a given action at least once in the range.
Why it is useful: the names are your feature list. Over a month they show which features earn their place and which nobody opens, so you know what to improve, what to promote and what to drop. When a new release changes the share of one action against the others, the Changed line on the dashboard points at it.
Action with a number
tode.trackActionWithMetric('fonts_replaced', 42);The same, with a value: how many layers were processed, how many fonts were replaced, how long a job took.
On the dashboard: Metric totals per day and Metric values with count, average, median (p50), p95 and maximum per metric name.
Why it is useful: a count says the feature ran; the number says how hard it worked. A p95 of 1,200 layers tells you the plugin meets big files, and whether to optimise for them. The totals say how much work the plugin did for its users in a month, which is a number worth putting on a pricing page.
Session
Sessions are not a call. When the plugin UI opens, the SDK opens a WebSocket to tode; when the plugin closes, the socket closes and the server records how long it was open. The SDK never sends a session payload itself.
On the dashboard: Sessions per day with the average length, Session length as a histogram (under 10 s, 10–30 s, 30 s–1 min, 1–2 min, 2–5 min, 5–10 min, 10–30 min, over 30 min) with p50 and p95, and the Avg session tile.
Why it is useful: length is the honest measure of whether the plugin does a job. Sessions under ten seconds are people who opened it and left; a healthy utility plugin sits around one to five minutes. The histogram also shows the two kinds of users a plugin often has: the quick-task crowd and the ones who live in it.
The fields on every event
Every event, whichever kind, carries these. The SDK fills them in; you never set them by hand.
actionName
The name you passed. Keep names stable across releases, in snake_case, and fewer than your plan's event-type limit (see Plans and Limits). The dashboard groups and counts by the exact string.
actionValue
Only on an action with a number. Any finite number up to 1012; counts and durations never get near that.
timestamp
When the event happened, in milliseconds, from the user's clock. If that clock is more than ten minutes off the server's, the server time is used instead, so history cannot be backfilled by accident.
Feeds: every per-day chart, the Activity by hour heatmap (weekday × hour, shown in your local time), the Busiest on note, and the detection of an unusual day against its seven-day baseline.
figma_userId
The user's Figma id, as a string, read from figma.currentUser. It is only available when the plugin manifest asks for it:
{
"permissions": ["currentuser"]
}Without the permission the SDK sends an empty value and tode cannot tell one user from another.
Feeds: Unique users, Active users per day split into new and returning, Returning users (a user is new when their first ever event for this plugin falls inside the range), Stickiness (DAU / MAU over the last 28 days), Week-one retention (users first seen in a week, and how many of them had any event the week after), Feature adoption, and the milestones in the Growing line (passed 1,000 users, and so on).
Why it is useful: this is the field that separates a usage counter from analytics. Actions tell you how often a feature runs; users tell you how many people it runs for and whether they come back. Retention is the one number that predicts whether a paid plan will hold.
tode keeps the id and nothing else about the person: no name, no email, no avatar. The dashboard only ever shows users in aggregate.
figma_editorType
Where the plugin ran: figma (Figma Design), figjam, dev (Dev Mode), slides or buzz. Anything else is dropped rather than stored as a category of its own.
Feeds: the Environment widget, and the Changed line when one editor's share moves against the previous period.
Why it is useful: a plugin built for Figma Design that gets a third of its sessions from Dev Mode has a second audience it did not plan for. The split also tells you which editor to test a release in first.
figma_mode
The editor's mode at the time: default, inspect, codegen, textreview, linkpreview, auth, query or textrun.
Feeds: the mode breakdown in the Environment widget and the same share-shift detection.
Why it is useful: in Dev Mode the difference between inspect and codegen is the difference between someone reading a design and someone generating code from it. For a codegen plugin that is the whole product.
eventSource
Where in the plugin the event came from: ui (the plugin's iframe), plugin (the controller, code.ts) or widget.
Feeds: the Event source share in the Environment widget.
Why it is useful: it tells you whether people use the plugin through its interface or through things that run without one, such as a widget or a command from the controller. That changes where to spend design effort.
userCountry
A two-letter country code. When the plugin starts, the SDK asks tode for the country of the current connection; the server answers from the request's IP and the SDK sends the code with every event. The IP address itself is not stored.
Feeds: Visitors by country and the world map, and the Changed line when a country's share shifts.
Why it is useful: language, pricing and support hours. A plugin with a growing share of users in Brazil or Japan has a localisation decision to make, and the map makes that visible before the support emails do.
figma_pluginId and figma_widgetId
The plugin's id from the manifest, and the widget's id when the code runs as a widget. tode checks the event belongs to the plugin the API key was issued for; the ids are not shown on the dashboard.
figma_apiVersion, appSource
The Figma plugin API version the plugin runs on, and the host application (figma today). Kept for support and debugging; neither appears on the dashboard.
What the dashboard adds on top
From the events above, tode computes a few readouts that are not stored anywhere, only derived:
- Growing / Steady / Slipping / Quiet. Users in the range against the previous period, with actions alongside. Quiet means fewer than 50 events, too few to judge.
- Changed. The single strongest shift in the range: a day far above or below its seven-day baseline, or a category (editor, mode, country or action) whose share moved by 1.5× or more.
All of them are aggregates. There is no per-user view, by design.
What is never collected
- The document: file names, page names, layers, text, selections, images, comments.
- The person: name, email, avatar, team. Only the Figma user id, and only with the
currentuserpermission. - The network: the IP address is used once to resolve the country and is not stored.
- Cookies: none. The SDK sets nothing in the browser.
The full list of fields is the SDK's types.ts, which is open source.
Next steps
- Best Practices: naming actions so the dashboard stays readable
- Plans and Limits: how events and event types count against a plan
- tode.trackAction() and tode.trackActionWithMetric()