Well-Known Events
Well-known events are the predefined event names that Pug recognizes, with typed property schemas enforced at ingestion. Both SDKs expose them as Pug.track.<event>(props) — the call is compile-time checked, so passing an unknown property or the wrong type is a type 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.