track method

Future<void> track(dynamic eventData, { String? screen, String? environment, })

Tracks an event by sending a POST request to Evntaly.

eventData - The event payload to be tracked. Can be either:

• EvntalyEvent object (recommended for IntelliSense support)
• Map<String, dynamic> for flexible custom events screen - Optional screen/page name for requestContext (app-specific) environment - Optional environment for requestContext (e.g., "production", "development")

Device and app information (appVersion, deviceModel, batteryLevel, etc.) are automatically detected. Only sends the request if trackingEnabled is true AND checkLimit() returns true. The context and requestContext are added directly to the eventData object.

Example with typed event:

await EvntalyClient.instance.track(
  EvntalyEvent(
    title: "Hello, World!",
    description: "System generated event",
    user: EvntalyUser(id: "user_001"),
    sessionID: "session-123",
    feature: "Order Flow",
    topic: "@shopify/order_created",
  ),
);

Example with Map (flexible):

await EvntalyClient.instance.track({
  'title': 'Custom Event',
  'customField': 'value',
});

Implementation

Future<void> track(
  dynamic eventData, {
  String? screen,
  String? environment,
}) async {
  // Convert EvntalyEvent to Map if needed
  Map<String, dynamic> eventMap;
  if (eventData is EvntalyEvent) {
    eventMap = eventData.toMap();
  } else if (eventData is Map<String, dynamic>) {
    eventMap = eventData;
  } else {
    _log('Invalid Event data type. Expected EvntalyEvent or Map<String, dynamic>', level: 'error');
    return;
  }
  try {
    if (!_initialized) {
      _log('SDK not initialized. Please call init() first.', level: 'error');
      return;
    }

    if (!_trackingEnabled) {
      _log('Tracking is disabled. Event not sent.');
      return;
    }

    final canTrack = await checkLimit();
    if (!canTrack) {
      _log('❌ Tracking limit reached. Event not sent.');
      return;
    }

    // Add context with dynamic information (matching TypeScript implementation)
    eventMap['context'] = EvntalyContext.build();

    // Add requestContext with automatically detected device and app information
    // Location is automatically included inside requestContext
    eventMap['requestContext'] = await EvntalyRequestContext.build(
      screen: screen,
      environment: environment,
    );

    final requestUrl = Uri.parse('$_baseUrl/api/v1/register/event');
    final response = await http.post(
      requestUrl,
      headers: {
        'Content-Type': 'application/json',
        'secret': _developerSecret ?? '',
        'pat': _projectToken ?? '',
      },
      body: jsonEncode(eventMap),
    );

    _log('Track event response:', level: 'log', args: [response.body]);
  } catch (error) {
    _log('Track event error:', level: 'error', args: [error]);
  }
}