Track

Fields

name • string required

The name of the custom event you want to track. This should be a descriptive identifier for the event.

data • { json }

An object containing key-value pairs of event properties. This data will be sent to your analytics providers along with the event. You can use variables as string values.

platforms • [ string ]

Specify which analytics providers should receive this event. If omitted, the event will be sent to all configured providers.

Available Platforms: "firebase", "klaviyo", "cordial", "branch", "click-stream", "appsflyer", "braze", "heap", "bloomreach", "facebook"

Basic Custom Event

Tapcart.action("track", {
  name: "product_comparison_viewed",
  data: {
    product_ids: ["123", "456"],
    comparison_type: "side_by_side",
    user_segment: "premium"
  }
});

Event with App Variables

Tapcart.action("track", {
  name: "newsletter_signup",
  data: {
    customer_id: "{customer.id}",
    email: "{customer.email}",
    signup_source: "product_page",
    timestamp: new Date().toISOString()
  }
});

Event for Specific Platforms

Tapcart.action("track", {
  name: "premium_feature_used",
  data: {
    feature_name: "advanced_search",
    user_tier: "premium",
    session_duration: 120
  },
  platforms: ["klaviyo", "braze", "firebase"]
});

Built-in Analytics Events

While the track action is for custom events, Tapcart also automatically fires many built-in analytics events for standard e-commerce activities. These events are triggered automatically when users interact with your app.

Event Categories

• Cart Events: cart_add, cart_remove, cart_updated, cart_checkout, etc.
• Authentication: logged_in, logged_out, create_account
• Product Events: product_viewed, collection_viewed, search
• Wishlist Events: wishlist_add, wishlist_remove, wishlist_item_added, etc.
• Purchase Events: checkout_created, purchase_completed, added_payment_info
• UI Interactions: alert_message_viewed, drawer_item_actioned, etc.

📚

Detailed Documentation: For complete documentation of all built-in analytics events, including when they fire and what data they contain, see the Analytics Events Reference.

Example: The cartAdd event is automatically fired whenever a user adds products to their cart, providing detailed information about the items added and the current cart state.

Provider-Specific Behavior

Different analytics providers may handle custom events differently:

• Firebase: Events are logged as custom events with the exact name provided
• Klaviyo: Events are processed through Klaviyo's track API
• Braze: Events become custom events in user profiles
• AppsFlyer: Events are mapped to AppsFlyer's custom event system

Best Practices

Event Naming

• Use clear, descriptive names: "video_playback_completed" not "video_done"
• Use consistent naming conventions across your app
• Avoid special characters or spaces in event names

Data Structure

• Keep data payloads lean and relevant
• Use consistent field names across similar events
• Include context that will be useful for analysis

Performance Considerations

• Avoid tracking too frequently (e.g., on every scroll event)
• Be mindful of payload size for mobile performance
• Use the platforms parameter to limit events to relevant providers

Error Handling

If the track action fails (e.g., due to network issues or invalid data), the error will be logged but won't affect the user experience. Always ensure your tracking code doesn't block critical app functionality.