--- schema_version: "1" id: a4c6d840bbb731299f9e411e55bdb1e8b93bcc8bcfee2fec93103292a5b9b3b2 title: Time Tracking collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/data-cloud/interactions-sdk/guides/c360a-api-time-tracking.md canonical_url: https://developer.salesforce.com/docs/data/salesforce-interactions-sdk/guide/c360a-api-time-tracking.html source_site: developer.salesforce.com content_type: documentation content_hash: a93e31effa99d390fef55045379c1f3f3f701d74bff62bd87251ddbc76d4df7a products: - Salesforce Interactions SDK - Data 360 Developer Documentation --- # Time Tracking Time tracking captures user engagement metrics by monitoring active time spent on pages and catalog items. Events are sent when configurable time thresholds are crossed (for example, 30 seconds or 60 seconds of active engagement). Time tracking attaches itself to other events you send (such as `catalog` events) and automatically includes their context in engagement events. Only active time is tracked—periods when the user is actually interacting with the page through mouse movement, clicks, scrolling, or keyboard input. By default, time tracking is **disabled**. To enable it, set `enabled: true` in your configuration. To disable it, set `enabled: false` or remove the time tracking configuration. ## Configuration Options | Option Name | Type | Default | Description | | ------------------------------- | ------- | --------------- | ------------------------------------------------------------------------------------ | | `enabled` | boolean | `false` | Set to `true` to enable time tracking. | | `thresholds` | array | See below | Array of threshold objects with `label` (string) and `threshold` (milliseconds). | | `eventTypes` | array | `['catalog']` | Event types to capture context from. Only the first matching event is captured. | | `activityTimeoutMillis` | number | `5000` | Milliseconds of inactivity before user is considered inactive (minimum: 1000ms). | | `minimumActivityTimeToRegister` | number | `300` | Minimum milliseconds of activity required to count as active time. | | `maxSessionDurationMillis` | number | `3600000` | Maximum session duration in milliseconds (1 hour). Session resets after this time. | | `sendPageExitWithoutThreshold` | boolean | `false` | If `true`, send `pageExit` event even when no threshold was reached. | | `maxEventsPerSession` | number | `20` | Maximum time tracking events per session. Prevents event flooding. | Default thresholds: `[{label: 'LOW_INTEREST', threshold: 30000}, {label: 'HIGH_INTEREST', threshold: 60000}]` ## Implementation Examples Time tracking captures context from other events you send. By default, it captures the first `catalog` event on a page and includes that catalog's details (like `catalogObject` and `catalogEventId`) in all time tracking events. You can configure which event types to capture using the `eventTypes` option. ### Enable with Default Settings Enable time tracking with default thresholds (30 seconds and 60 seconds) and a catalog context. ```javascript SalesforceInteractions.init({ consents: [{ purpose: SalesforceInteractions.ConsentPurpose.Tracking, provider: "OneTrust", status: consentStatus }], dataCloud: { timeTracking: { enabled: true } } }); ``` ### Custom Configuration Configure custom thresholds and event types. ```javascript SalesforceInteractions.init({ consents: [{ purpose: SalesforceInteractions.ConsentPurpose.Tracking, provider: "OneTrust", status: consentStatus }], dataCloud: { timeTracking: { enabled: true, thresholds: [ { label: 'ENGAGED', threshold: 15000 }, { label: 'HIGH_ENGAGEMENT', threshold: 60000 } ], eventTypes: ['catalog', 'blogPost'] } } }); ``` ## Event Structure Time tracking generates events with the `Engagement` category and automatically includes fields from captured context events. | Field Name | Field Type | Description | | ------------------ | ---------- | ------------------------------------------------------------------------------------------------ | | `eventType` | string | Dynamically set to `{contextType}Time` (for example, `catalogTime`). Events are only sent after a context event has been captured. | | `interactionName` | string | Either `timeOnPage` or `pageExit`. | | `category` | string | Always `Engagement`. | | `threshold` | string | The threshold label that was crossed (for example, `LOW_INTEREST`) or `pageExit`. | | `totalActiveTime` | number | Total milliseconds of active time for this context/session. | | `pageStartTime` | string | ISO 8601 timestamp when tracking started for this context. | | `lastActivityTime` | string | ISO 8601 timestamp of the most recent user activity. | | `pageViewId` | string | UUID v4 generated per page view to correlate events. | | `pingSequence` | number | Incrementing counter for events in this page view. | When a context event (for example, a catalog event) is captured, its fields are automatically copied to time tracking events. For catalog contexts, this includes `catalogObject` and `catalogEventId`. ## Stopping Time Tracking You can programmatically stop the time tracking service: ```javascript SalesforceInteractions.DataCloud.stopTimeTracking() ``` This is useful for: - Privacy controls (user opts out) - Conditional tracking based on page type - Testing scenarios >**Note**: Once stopped, the service cannot be restarted without reinitializing the SDK. ## Best Practices ### Threshold Configuration - Order thresholds from shortest to longest (they're automatically sorted, but it's clearer) - Use meaningful labels that will be useful in analytics (e.g., 'QUICK_VIEW', 'ENGAGED', 'HIGHLY_ENGAGED') - Consider your typical user engagement patterns when setting threshold values - Ensure `maxEventsPerSession` is at least `thresholds.length + 1` to allow all thresholds plus pageExit ### Event Types - If tracking catalog views, use `eventTypes: ['catalog']` - If tracking custom events, include them: `eventTypes: ['catalog', 'custom']` - Order matters: the first matching event type is captured ### Activity Timeout - Too short (e.g., 1 second): May miss brief pauses in user activity - Too long (e.g., 30 seconds): May overcount inactive time - Default (5 seconds) works well for most use cases ### Session Duration - Consider your typical session lengths - Default (1 hour) prevents unrealistic accumulation for abandoned tabs - For longer-form content, you may want to increase this ### Page Exit Behavior - Default (`sendPageExitWithoutThreshold: false`) filters out bounce visits - Set to true if you want to track all page exits, including short visits - Useful for bounce rate analysis ## Troubleshooting ### No Events Being Sent 1. **Check if enabled:** Ensure `timeTracking.enabled: true` is set 2. **Check consent:** Time tracking respects consent management; ensure Opt-In consent exists 3. **Check context capture:** Verify that events matching eventTypes are being sent 4. **Check thresholds:** Ensure thresholds are reachable (not too high) 5. **Check rate limits:** Verify `maxEventsPerSession` hasn't been exceeded ### Events Missing Context 1. **Verify event types:** Ensure the events you're sending match eventTypes configuration 2. **Check timing:** Context is captured from the first matching event; ensure it's sent before significant time passes 3. **Check event structure:** Ensure your events have the expected structure and fields ### Too Many Events 1. **Reduce thresholds:** Fewer thresholds mean fewer events 2. **Lower maxEventsPerSession:** Set a stricter limit 3. **Increase threshold values:** Higher thresholds mean events are sent less frequently ### Inaccurate Time Tracking 1. **Check activityTimeoutMillis:** Too short may miss activity; too long may overcount 2. **Check minimumActivityTimeToRegister:** Too high may undercount; too low may include noise ## See Also - [Catalog Interaction](https://developer.salesforce.com/docs/data/salesforce-interactions-sdk/guide/c360a-api-catalog-interaction.md) - [Custom Events](https://developer.salesforce.com/docs/data/salesforce-interactions-sdk/guide/c360a-api-custom-events.md) - [Translation of SDK Events to Web Connector Schemas](https://developer.salesforce.com/docs/data/salesforce-interactions-sdk/guide/c360a-api-translating-sdk-events-to-web-connector-schemas.md)