brevoflutter 0.1.1

A Flutter package for Brevo (formerly Sendinblue) Marketing Automation API integration. Track users, events, link clicks, and page views with type-safe models and comprehensive error handling.

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: '[e-mail]',
    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: '[e-mail]',
    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}');
}

4. Track Link Clicks

Monitor when users click on specific links:

try {
  final response = await BrevoTracker.instance.trackLink(
    email: '[e-mail]',
    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: '[e-mail]',
    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:

• Official Documentation: https://developers.brevo.com
• API Reference: https://developers.brevo.com/reference
• Get API Keys: https://app.brevo.com/settings/keys/api

License

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

Support

For issues related to:

• This package: Open an issue in this repository
• Brevo API: Contact Brevo support at https://help.brevo.com