Tracking custom events

Learn how to send custom analytics events from your application.

Wiredash Analytics allows you to track custom events in your application using the Wiredash.trackEvent() function. This is useful for tracking user interactions, such as button clicks or purchases.

INFO

Make sure you have Wiredash SDK version > 2.2.0 installed.

Tracking a client-side event

To track an event, use the Wiredash.trackEvent method for easy access throughout your app.

To track an event:

1. Ensure you have Wiredash SDK version 2.2.0 or higher installed.
2. Import Wiredash with import 'package:wiredash/wiredash.dart';
3. Typically, you will want to track an event when a user performs an action, such as clicking a button or submitting a form, so you should use this on the button handler.
4. Call Wiredash.trackEvent and pass a string representing the event name as the first argument. You can also pass custom data as the second argument:

await Wiredash.trackEvent('Click Button', data: {/**/});

Tracking an event with custom properties

You can also pass custom data along with an event. To do so, pass an object with key-value pairs as the second argument to trackEvent():

await Wiredash.trackEvent('Signup', data: { provider: 'google' });
await Wiredash.trackEvent('Subscribed', data: { plan: 'business', price: 89.90 });

Limitations

When implementing custom events, there are several limitations to keep in mind:

Event Names

The name must be between 3 and 64 characters in length and can include letters (a-z, A-Z), numbers (0-9), hyphens (-), underscores (_), and spaces. It must start with a letter (a-z, A-Z). Double spaces and trailing spaces are prohibited.

Event Data

Each event can have a maximum of 10 key-value pairs. Keys can be up to 128 characters long and must not be empty. Values can be of type string, integer, boolean, or null, and each value must not exceed 1024 characters after JSON encoding.

Event sending behavior

• Events are batched and sent every 30 seconds (directly on web).
• The first batch is sent after a 5-second delay so Wiredash doesn't slow down your app's startup.
• Events are sent immediately when the app goes to the background.
• Events are stored locally and retried later if sending fails.
• Unsent events are discarded after 3 days.

Background isolates

When trackEvent() is called from a background isolate, the event is stored locally. The main isolate will send these events automatically with the next batch or latestwhen the app goes to the background.

Handling multiple Wiredash widgets

Access the closest Wiredash widget using the Wiredash.of(context) method.

Wiredash.of(context).trackEvent('Click Button');

Don't have a context? If your app has multiple Wiredash widgets with different projectIds, specify the desired projectId when creating WiredashAnalytics to ensure the event is sent to the correct project.

final analytics = WiredashAnalytics(projectId: 'your_project_id');

If no projectId is provided and multiple widgets are mounted, events are sent to the project associated with the first mounted widget, and a warning is logged to the console.

Testing

Wiredash will not send events during your widget tests, as it automatically detects when it’s running in a testing environment.

If you want to test that a user action triggered an analytics event, use the WiredashAnalytics class, which you can mock easily using your favorite mocking library.

final analytics = WiredashAnalytics();
await analytics.trackEvent('Click Button', data: {/**/});

// Inject into other classes
final bloc = MyBloc(analytics: analytics);

// mock in your tests
final mockAnalytics = MockWiredashAnalytics();
final bloc = MyBloc(analytics: mockAnalytics);
await bloc.doSomething();
verify(() => mockAnalytics.trackEvent('Click Button')).called(1);