Well-known events are the predefined event names Pug recognizes, with typed property schemas enforced at ingestion. The catalog holds 127 events across 19 families, listed in full below.
Every SDK type-checks them, but the call shape differs:
| SDK | Call | Available |
|---|---|---|
| Flutter | Pug.track.purchase(productId: …, amount: …) — a generated method per event |
all 127 |
| Web | track('purchase', { productId, amount }) — the name narrows the property type |
119 (events flagged for other platforms are excluded) |
| Node | pug.track(distinctId, 'purchase', { … }) |
114 |
| HTTP | kind: "purchase" with wrapped customProperties |
all 127 |
Either way the check is at compile time, so an unknown property or a wrong type is an error before the event leaves the device.
Custom event names (any snake_case string other than a pug.-prefixed kind) are accepted without schema validation. See Events API for the pug. prefix restriction and validation error format.
Further reading: Tracking events — sending custom and well-known events from each SDK
Commerce
Product browsing, cart, checkout, and purchase events. price is a single-item price; amount is a transaction total. currency is an uppercase ISO 4217 code (e.g. USD, EUR). Money fields use the major currency unit (e.g. dollars, not cents).
| Event | Properties | Description |
|---|---|---|
product_viewed |
product_id* string, product_name string, category string, brand string, sku string, price double, currency string |
User viewed a product detail page |
product_list_viewed |
list_id* string, list_name string, category string, item_count int |
User viewed a product listing, category, or search-results page |
add_to_cart |
product_id* string, price double, currency string, cart_id string, quantity int, category string, brand string, sku string |
Item added to cart |
remove_from_cart |
product_id* string, price double, currency string, cart_id string, quantity int, category string, brand string, sku string |
Item removed from cart |
cart_viewed |
cart_id string, item_count int, amount double, currency string |
User opened the cart |
wishlist_added |
product_id* string, wishlist_id string, price double, currency string |
Item added to wishlist |
wishlist_removed |
product_id* string, wishlist_id string |
Item removed from wishlist |
coupon_applied |
coupon_id* string, coupon_code string, cart_id string, discount_amount double, currency string |
Coupon applied to cart |
coupon_removed |
coupon_id* string, coupon_code string, cart_id string, reason string |
Coupon removed from cart |
checkout_started |
product_id string, amount double, currency string, cart_id string, checkout_id string, item_count int |
User initiated checkout |
checkout_step_completed |
checkout_id* string, step* string, step_index int |
A checkout step was completed |
purchase |
product_id string, amount double, currency string, order_id string, quantity int, category string, brand string, sku string |
Order completed (fires once per successful order after payment is confirmed) |
order_refunded |
order_id* string, amount double, currency string, reason string |
Order was refunded |
Authentication
Sign-up, sign-in, sign-out, email verification, password reset, and MFA lifecycle. All auth events have no required properties beyond the event kind; common method values are "email", "google", "github", "totp", "sms", "webauthn", "backup_codes".
| Event | Properties | Description |
|---|---|---|
signup |
— | User completed registration |
signin |
— | User signed in |
signout |
— | User signed out |
email_verified |
— | Email address was verified |
password_reset_requested |
— | Password reset was requested |
password_reset_completed |
— | Password reset flow completed |
mfa_enabled |
method string |
MFA was enabled |
mfa_disabled |
method string |
MFA was disabled |
App Lifecycle
Native mobile lifecycle events from the Flutter SDK (iOS and Android) — the Web SDK does not emit these. The SDK auto-emits only app_open and app_close (plus screen_view for navigation); the rest are typed events you track manually.
| Event | Properties | Description |
|---|---|---|
app_open |
— | App launched or brought to the foreground |
app_close |
— | App moved to the background or closed |
app_install |
app_version string, install_source string |
First launch after a fresh install |
app_update |
app_version* string, previous_version string |
First launch after an app update |
app_backgrounded |
— | App moved to the background |
app_foregrounded |
— | App returned to the foreground |
app_crashed |
error_message string, error_type string |
Unhandled crash (also available on desktop) |
screen_view |
screen_name* string, screen_class string |
A native screen was viewed — the mobile equivalent of page_view |
App Usage
Cross-platform — available in every SDK.
| Event | Properties | Description |
|---|---|---|
feature_used |
feature_id* string, feature_name string |
A named feature was used |
Billing
Subscription, invoice, payment, trial, and refund lifecycle. currency is an uppercase ISO 4217 code; amount is the transaction total in the major currency unit.
| Event | Properties | Description |
|---|---|---|
subscription_started |
subscription_id* string, plan_id string, amount double, currency string |
New subscription was created |
subscription_changed |
subscription_id* string, previous_plan_id string, new_plan_id string |
Subscription plan was changed |
subscription_canceled |
subscription_id* string, plan_id string, reason string |
Subscription was canceled |
subscription_renewed |
subscription_id* string, plan_id string, amount double, currency string |
Subscription renewed |
subscription_paused |
subscription_id* string, plan_id string, reason string |
Subscription was paused |
subscription_resumed |
subscription_id* string, plan_id string, reason string |
Paused subscription was resumed |
subscription_trial_will_end |
subscription_id* string, plan_id string, trial_id string |
Trial is nearing expiry (fires in advance, e.g. 3 days before) |
trial_started |
trial_id string, plan_id string |
Free trial started |
trial_converted |
trial_id string, subscription_id string, plan_id string |
Trial converted to paid subscription |
invoice_paid |
invoice_id* string, subscription_id string, amount double, currency string |
Invoice was paid |
invoice_failed |
invoice_id* string, subscription_id string, amount double, currency string, reason string |
Invoice payment failed |
payment_succeeded |
payment_id string, invoice_id string, subscription_id string, amount double, currency string |
Payment succeeded |
payment_failed |
payment_id string, invoice_id string, subscription_id string, amount double, currency string, reason string |
Payment failed |
payment_method_added |
payment_method_id string, payment_method_type string |
Payment method was added |
payment_method_removed |
payment_method_id string, payment_method_type string |
Payment method was removed |
refund_failed |
order_id* string, refund_id string, amount double, currency string, reason string |
Refund attempt failed |
Chat
Conversation lifecycle, message delivery, membership, calls, attachments, and reactions. conversation_id is the durable chat identifier. member_id is the conversation-membership ID, not the SDK distinct_id. Common values: conversation_type — "dm", "group", "channel", "broadcast"; message_type — "text", "image", "video", "audio", "file", "system". duration-typed props (e.g. mute_duration) serialize as { "seconds": N, "nanos": N } — see Notes.
| Event | Properties | Description |
|---|---|---|
chat_created |
conversation_id* string, conversation_type string, participant_count int |
Conversation was created |
chat_joined |
conversation_id* string, conversation_type string |
User joined a conversation |
chat_left |
conversation_id* string, conversation_type string, reason string |
User left a conversation |
chat_deleted |
conversation_id* string, conversation_type string, reason string |
Conversation was deleted |
chat_archived |
conversation_id* string, conversation_type string |
Conversation was archived |
chat_unarchived |
conversation_id* string, conversation_type string |
Conversation was unarchived |
chat_member_added |
conversation_id* string, member_id* string, role string |
Member was added to a conversation |
chat_member_removed |
conversation_id* string, member_id* string, reason string |
Member was removed from a conversation |
chat_member_role_changed |
conversation_id* string, member_id* string, previous_role string, new_role* string |
Member’s role was changed |
chat_member_muted |
conversation_id* string, member_id* string, mute_duration duration |
Member was muted (duration omitted for indefinite mutes) |
chat_user_blocked |
user_id* string |
User was blocked (not conversation-scoped) |
chat_message_sent |
conversation_id* string, message_id string, conversation_type string, message_type string, character_count int, attachment_count int, thread_id string, parent_message_id string |
Message was sent |
chat_message_received |
conversation_id* string, message_id string, conversation_type string, message_type string, character_count int, attachment_count int, thread_id string, parent_message_id string |
Message was received |
chat_message_failed |
conversation_id* string, message_id string, conversation_type string, reason* string, thread_id string |
Message send failed |
chat_message_read |
conversation_id* string, message_id string, conversation_type string, thread_id string |
Message was read |
chat_message_deleted |
conversation_id* string, message_id string, conversation_type string, reason string, thread_id string |
Message was deleted |
chat_message_edited |
conversation_id* string, message_id string, conversation_type string, thread_id string |
Message was edited |
chat_message_pinned |
conversation_id* string, message_id string, conversation_type string, thread_id string |
Message was pinned |
chat_message_unpinned |
conversation_id* string, message_id string, conversation_type string, thread_id string |
Message was unpinned |
chat_typing_started |
conversation_id* string, conversation_type string |
User started typing (typer is the SDK distinct_id) |
chat_typing_stopped |
conversation_id* string, conversation_type string |
User stopped typing |
chat_attachment_uploaded |
conversation_id* string, message_id string, attachment_id* string, attachment_type string, size_bytes int64, thread_id string |
Attachment uploaded in chat |
chat_attachment_downloaded |
conversation_id* string, message_id string, attachment_id* string, attachment_type string, size_bytes int64, thread_id string |
Attachment downloaded from chat |
chat_call_started |
conversation_id* string, call_id* string, call_type string |
Call was started |
chat_call_joined |
conversation_id* string, call_id* string, call_type string |
User joined a call |
chat_call_left |
conversation_id* string, call_id* string, call_type string, duration duration |
User left a call |
chat_call_screen_shared |
conversation_id* string, call_id* string |
Screen sharing started on a call |
chat_call_recording_started |
conversation_id* string, call_id* string |
Call recording started |
chat_reaction_added |
conversation_id* string, message_id string, reaction* string, thread_id string |
Reaction added to a message |
chat_reaction_removed |
conversation_id* string, message_id string, reaction* string, thread_id string |
Reaction removed from a message |
Discovery / Search
Search queries, results, recommendations, filters, and sorting. These events capture how users explore and find content.
| Event | Properties | Description |
|---|---|---|
search |
query* string |
Search query submitted |
search_result_clicked |
query* string, result_id* string, index int |
User clicked a search result |
recommendation_viewed |
recommendation_id* string, item_id string, source string, index int |
Recommendation impression |
recommendation_clicked |
recommendation_id* string, item_id* string, source string, index int |
User clicked a recommendation |
filter_applied |
key* string, value string |
Filter was applied |
sort_changed |
key* string, direction string |
Sort order was changed |
Error
Application errors and exceptions. (PII) marks fields handled under the project’s scrubbing and data-residency rules (see Notes).
| Event | Properties | Description |
|---|---|---|
error_occurred |
error_code* string, message string (PII), severity string, unhandled bool, stack string (PII) |
An error was caught or escaped to a global handler. Common severity values: "info", "warning", "error", "fatal". Set unhandled: true when the error escaped application code |
File
File upload, download, and export events.
| Event | Properties | Description |
|---|---|---|
file_uploaded |
file_id* string, file_name string (PII), file_type string, size_bytes int64 |
File was uploaded |
file_downloaded |
file_id* string, file_name string (PII), file_type string, size_bytes int64 |
File was downloaded |
export_started |
export_id* string, export_type string |
Data export was initiated |
export_completed |
export_id* string, export_type string, size_bytes int64 |
Data export completed |
Form
Form interaction start and submission.
| Event | Properties | Description |
|---|---|---|
form_start |
form_id* string, form_name string |
User began filling in a form |
form_submit |
form_id* string, form_name string, action string |
Form was submitted |
Integration
Third-party integration connect and disconnect. Common integration_type values: "slack", "github", "linear", "salesforce", "hubspot", "zapier", "webhook".
| Event | Properties | Description |
|---|---|---|
integration_connected |
integration_id string, integration_type* string |
Integration was connected |
integration_disconnected |
integration_id string, integration_type* string, reason string |
Integration was disconnected |
Invitation
Workspace invitation sent and accepted.
| Event | Properties | Description |
|---|---|---|
invite_sent |
invite_id string, workspace_id string, inviter_id string, invitee_id string, invitee_email string (PII), role string |
Invitation was sent |
invite_accepted |
invite_id string, workspace_id string, inviter_id string, invitee_id string, invitee_email string (PII), role string |
Invitation was accepted |
Media
Video and audio playback events. video_started / audio_started fire on first play of a session; video_play / audio_play fire on resume from pause. position, from_position, and to_position are durations from the start of the media.
| Event | Properties | Description |
|---|---|---|
video_started |
video_id* string |
Video playback started for the first time in this session |
video_play |
video_id* string, position duration |
Video resumed from pause |
video_pause |
video_id* string, position duration |
Video was paused |
video_seeked |
video_id* string, from_position duration, to_position duration |
User seeked in video |
video_completed |
video_id* string |
Video playback reached the end |
audio_started |
audio_id* string |
Audio playback started for the first time in this session |
audio_play |
audio_id* string, position duration |
Audio resumed from pause |
audio_pause |
audio_id* string, position duration |
Audio was paused |
audio_seeked |
audio_id* string, from_position duration, to_position duration |
User seeked in audio |
audio_completed |
audio_id* string |
Audio playback reached the end |
Navigation
Page views, clicks, scroll depth, and frustration signals. Page URL, title, referrer, and UTM parameters are provided as auto-properties ($url, $pageTitle, $referrer, $utmSource/$utmMedium/$utmCampaign/…) on every event — they do not appear as typed properties here.
| Event | Properties | Description |
|---|---|---|
page_view |
— | Web page navigation or SPA route change (auto-tracked by Web SDK) |
click |
class string, id string, tag string, text string, x int, y int |
Element click — Web only |
rage_click |
click_count int (≥2), element string, x int, y int |
Multiple rapid clicks on the same non-responsive target — Web only |
dead_click |
element string, text string, x int, y int |
Click with no observable response — Web only |
scroll |
percent int (0–100), scroll_y int |
Scroll depth milestone — Web and mobile |
Notification
Notification receipt, click, and dismissal. notification_type describes the delivery channel: "push", "email", "in_app", "sms".
| Event | Properties | Description |
|---|---|---|
notification_received |
campaign_id* string, notification_type string |
Notification was received by the client |
notification_clicked |
campaign_id* string, notification_type string |
User clicked a notification |
notification_dismissed |
campaign_id* string, notification_type string |
User dismissed a notification |
Social
| Event | Properties | Description |
|---|---|---|
share |
— | User shared content |
Support
Feedback, NPS, surveys, support tickets, live chat, and help articles.
| Event | Properties | Description |
|---|---|---|
feedback_submitted |
feedback_id string, category string, comment string (PII) |
Feedback was submitted |
nps_submitted |
score int (0–10), comment string (PII) |
NPS score was submitted |
survey_started |
survey_id* string |
Survey was started |
survey_completed |
survey_id* string, question_count int |
Survey was completed |
support_ticket_created |
ticket_id* string, category string, priority string |
Support ticket was opened |
support_ticket_resolved |
ticket_id* string, resolution string (PII) |
Support ticket was resolved |
support_chat_started |
conversation_id* string, topic string (PII) |
Support chat session started |
help_article_viewed |
article_id* string, article_title string, category string |
Help article was viewed |
Workspace
Workspace creation, membership, role changes, and settings.
| Event | Properties | Description |
|---|---|---|
workspace_created |
workspace_id* string, workspace_name string |
Workspace was created |
workspace_joined |
workspace_id* string, role string |
User joined a workspace |
workspace_deleted |
workspace_id* string, reason string |
Workspace was deleted |
workspace_role_changed |
workspace_id* string, member_id* string, previous_role string, new_role* string |
Member’s workspace role was changed |
workspace_settings_updated |
workspace_id* string, setting* string |
A workspace setting was changed |
API
API key management events.
| Event | Properties | Description |
|---|---|---|
api_key_created |
api_key_id string, name string, scope string |
API key was created |
api_key_revoked |
api_key_id string, name string, reason string |
API key was revoked |
Notes
Required props are marked with * — the API returns invalid_argument if a required property is missing or the wrong type. Optional props may be omitted.
PII-tagged props are labelled (PII) above. Fields tagged PII in the schema are subject to the project’s data-residency and scrubbing rules.
duration type — duration properties (e.g. position, mute_duration, duration) are serialized as a JSON object { "seconds": N, "nanos": N }.
pug. prefix is reserved — custom event kind strings must not start with pug.. The API rejects any custom event whose kind begins with that prefix. See Events API.
Web vs Flutter — the Web SDK exposes all events listed here except the mobile app lifecycle events (app_open, app_close, app_install, app_update, app_backgrounded, app_foregrounded, app_crashed, screen_view). The Flutter SDK includes those and drops the DOM-interaction events (click, rage_click, dead_click). Its navigation event is screen_view on mobile; on web targets Flutter emits page_view instead.