Brevo Flutter Tracker

A Flutter package for integrating Brevo (formerly Sendinblue) Marketing Automation API for user identification and event tracking.

Features

  • User Identification: Create and update user profiles with custom attributes
  • Event Tracking: Track custom events like purchases, cart updates, form submissions
  • Link Tracking: Monitor link clicks and downloads
  • Page Tracking: Track page views and user navigation
  • Type-safe API: Strongly typed models for all requests
  • Comprehensive Error Handling: Custom exceptions for different error scenarios
  • Singleton Pattern: Easy-to-use singleton instance

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  http: ^1.2.0

Getting Started

1. Initialize the Tracker

Initialize the Brevo tracker in your app's main() function with your Marketing Automation API key:

import 'package:brevoflutter/brevo_tracker.dart';

void main() {
  BrevoTracker.instance.initialize(
    apiKey: 'YOUR_MA_KEY_HERE',
  );

  runApp(const MyApp());
}

Important: Replace YOUR_MA_KEY_HERE with your actual Brevo Marketing Automation API key. You can find your API key at: https://app.brevo.com/settings/keys/api

2. Identify Users

Create or update user profiles with custom attributes:

try {
  final response = await BrevoTracker.instance.identifyUser(
    email: 'user@example.com',
    attributes: {
      'FirstName': 'John',
      'LastName': 'Doe',
      'Age': 30,
      'SMS': 919989894562,
      // Add any custom attributes you've defined in your Brevo account
    },
  );

  print('User identified: ${response.success}');
} on BrevoException catch (e) {
  print('Error: ${e.message}');
}

3. Track Events

Track custom events with structured data:

try {
  final response = await BrevoTracker.instance.trackEvent(
    email: 'user@example.com',
    event: 'cart_updated',
    eventData: {
      'data': {
        'added_product': [
          {
            'currency': 'EUR',
            'name': 'Wrist watch',
            'type': 'accessories',
            'price': '50.00',
          }
        ],
      },
    },
    properties: {
      'cart_total': '150.00',
      'items_count': 3,
    },
  );

  print('Event tracked: ${response.success}');
} on BrevoException catch (e) {
  print('Error: ${e.message}');
}

Monitor when users click on specific links:

try {
  final response = await BrevoTracker.instance.trackLink(
    email: 'user@example.com',
    link: 'https://example.com/document.pdf',
    properties: {
      'category': 'downloads',
      'document_type': 'case_study',
    },
  );

  print('Link tracked: ${response.success}');
} on BrevoException catch (e) {
  print('Error: ${e.message}');
}

5. Track Page Views

Track page views and user navigation:

try {
  final response = await BrevoTracker.instance.trackPage(
    email: 'user@example.com',
    page: 'Checkout',
    properties: {
      'title': 'Checkout - Step 2',
      'url': '/checkout/payment',
      'referrer': '/cart',
    },
  );

  print('Page tracked: ${response.success}');
} on BrevoException catch (e) {
  print('Error: ${e.message}');
}

API Reference

BrevoTracker

Main singleton class for interacting with the Brevo API.

Methods

  • initialize({required String apiKey, http.Client? httpClient}): Initialize the tracker with your API key
  • identifyUser({required String email, Map<String, dynamic>? attributes}): Identify or update a user
  • trackEvent({required String email, required String event, Map<String, dynamic>? eventData, Map<String, dynamic>? properties}): Track a custom event
  • trackLink({required String email, required String link, Map<String, dynamic>? properties}): Track a link click
  • trackPage({required String email, required String page, Map<String, dynamic>? properties}): Track a page view
  • dispose(): Clean up resources

Exception Handling

The package provides several custom exceptions:

  • BrevoException: Base exception class
  • BrevoInitializationException: Thrown when the tracker is not initialized
  • BrevoBadRequestException: HTTP 400 - Invalid parameters
  • BrevoUnauthorizedException: HTTP 401 - Invalid or missing API key
  • BrevoRateLimitException: HTTP 429 - Rate limit exceeded
  • BrevoServerException: HTTP 500+ - Server error
  • BrevoNetworkException: Network connectivity issues

Reserved Property Keys

The following keys are reserved and cannot be used in the properties parameter:

  • For trackEvent: email, event
  • For trackLink: email, link
  • For trackPage: email, page

Using reserved keys will throw an ArgumentError.

Best Practices

Security

  • Never expose your API key in client-side code: Consider using environment variables or secure storage
  • Make API calls from your backend: For production apps, proxy requests through your server
  • Rotate API keys regularly: As part of security best practices

Performance

  • Implement retry logic: Use exponential backoff for rate limit errors (HTTP 429)
  • Batch requests: When tracking multiple events, consider batching them
  • Handle errors gracefully: Always wrap API calls in try-catch blocks

Data Management

  • Use consistent naming: Maintain consistent event and property names across your app
  • Keep properties descriptive: Use clear, meaningful names for properties
  • Test thoroughly: Test all tracking calls before deploying to production

Example App

See the lib/main.dart file for a complete example app demonstrating all features.

API Documentation

For more information about the Brevo Marketing Automation API, visit:

License

This package is provided as-is for use with Brevo Marketing Automation services.

Support

For issues related to:

Libraries

brevoflutter
A Flutter package for Brevo (formerly Sendinblue) Marketing Automation API integration.