Track events manually

In addition to autocaptured events, use the CSQ().trackEvent() API to send custom events and attach properties to them for use in Product Analytics.

await CSQ().trackEvent(eventName: 'product_purchased');

It doesn't matter what you call your event, there are ways in Product Analytics to cross-track events regardless of name. See our guide on combo events ↗ to learn more.

Custom events can be enhanced with a set of properties that will correspond to the tracked event when passed into the CSQ().trackEvent() call.

await CSQ().trackEvent(
  eventName: 'product_purchased',
  properties: {
    'product_id': 'SKU123',
    'product_name': 'Premium Subscription',
    'price': 29.99,
    'currency': 'USD',
    'is_discounted': true,
  },
);

Here are more examples showing different event types and property combinations:

// Content interaction event
await CSQ().trackEvent(
  eventName: 'video_played',
  properties: {
    'video_id': 'vid_789',
    'video_title': 'Getting Started Tutorial',
    'duration_seconds': 245,
    'is_premium_content': false,
  },
);

// User engagement event
await CSQ().trackEvent(
  eventName: 'article_shared',
  properties: {
    'article_id': 'art_456',
    'share_method': 'email',
    'article_category': 'technology',
    'read_progress': 0.75,
  },
);

// Search and discovery event
await CSQ().trackEvent(
  eventName: 'search_performed',
  properties: {
    'search_query': 'flutter tutorials',
    'result_count': 24,
    'filter_applied': true,
  },
);

In some cases, you might want to add a property, or a collection of properties, to all events tracked by Product Analytics. Adding a global event property can be accomplished using CSQ().addEventProperties().

await CSQ().addEventProperties(properties: {
  'user_tier': 'premium',
  'app_version': '2.1.4',
  'platform': 'mobile',
  'is_beta_user': false,
  'session_count': 42,
});

Properties that are added using the csq.addEventProperties() API will be attached to all events tracked by Product Analytics, including any events that are automatically tracked by a CSQ autocapture SDK. Once a property is no longer needed in the global collection, use this API to remove properties one at a time.

await CSQ().removeEventProperty(name: 'is_beta_user');

On the other hand, if you want to remove all properties added with CSQ().addEventProperties() at once, you can achieve this by using CSQ().clearEventProperties().

await CSQ().clearEventProperties();

However, neither of these methods will affect events that have already been processed.