Go Mailer Push SDK for Flutter #

Receive push notifications sent by Go-Mailer in your Flutter app. This SDK handles device registration, user identification, and notification interaction tracking - Go-Mailer takes care of sending the notifications.

What This SDK Does #

• 📱 Registers your app to receive push notifications from Go-Mailer
• 👤 Identifies users so Go-Mailer knows who to send notifications to
• 📊 Tracks interactions when users tap notifications
• 🔧 Simple Integration - just call our helper functions at the right time
• 📱 Cross-Platform - works on both iOS and Android

Installation #

Add this to your pubspec.yaml:

dependencies:
  go_mailer_push_sdk: ^1.3.0

Then run:

flutter pub get

iOS Setup #

1. Enable Push Notifications capability in Xcode
2. Configure APNs certificates in your Apple Developer account
3. The SDK handles APNs registration automatically

Android Setup #

1. Add Firebase to your Flutter project
2. Place google-services.json in android/app/
3. The SDK handles FCM registration automatically

Quick Start #

Step 1: Initialize (call once when your app starts)

import 'package:go_mailer_push_sdk/go_mailer.dart';

// Initialize Go-Mailer SDK (defaults to production)
await GoMailer.initialize(
  apiKey: 'your-go-mailer-api-key',
);

Environment Configuration #

The SDK supports multiple environments for testing:

// Production (default)
await GoMailer.initialize(
  apiKey: 'your-api-key',
  config: GoMailerConfig(
    environment: GoMailerEnvironment.production, // https://api.go-mailer.com/v1
  ),
);

// Staging
await GoMailer.initialize(
  apiKey: 'your-api-key',
  config: GoMailerConfig(
    environment: GoMailerEnvironment.staging, // https://api.gm-g7.xyz/v1
  ),
);

// Development
await GoMailer.initialize(
  apiKey: 'your-api-key',
  config: GoMailerConfig(
    environment: GoMailerEnvironment.development, // https://api.gm-g6.xyz/v1
  ),
);

// Custom endpoint
await GoMailer.initialize(
  apiKey: 'your-api-key',
  config: GoMailerConfig(
    baseUrl: 'https://your-custom-endpoint.com/v1',
  ),
);

Step 2: Identify the user (call when user logs in or you know their email)

await GoMailer.setUser({
  'email': 'user@example.com',
  // Add any other user properties you want Go-Mailer to know about
});

Step 3: Request permission (call when appropriate in your UX flow)

bool granted = await GoMailer.requestNotificationPermission();
if (granted) {
  // User will now receive notifications sent by Go-Mailer
}

Step 4: Track clicks (call when a notification opens your app)

// Go-Mailer includes notification_id in every notification payload
await GoMailer.trackNotificationClick('notification-id-from-payload');

That's it! Go-Mailer will handle sending notifications to your users.

Complete API Reference #

1. Initialize the SDK #

await GoMailer.initialize(
  apiKey: 'your-go-mailer-api-key',
  logLevel: GoMailerLogLevel.info, // optional
);

Call this once when your app starts. Required before using any other methods.

2. Identify Users #

await GoMailer.setUser({
  'email': 'user@example.com',
  'firstName': 'John',
  'lastName': 'Doe',
  // ... any other user properties
});

Tell Go-Mailer who this user is so we can send them targeted notifications.

3. Handle Permissions #

// Request permission to show notifications
bool granted = await GoMailer.requestNotificationPermission();

// Check current permission status
bool hasPermission = await GoMailer.checkNotificationPermission();

iOS requires explicit permission. Android grants it automatically in most cases.

4. Track Notification Interactions #

// When user taps a notification and opens your app
await GoMailer.trackNotificationClick('notification-id-from-payload');

Important: Go-Mailer includes a notification_id in every notification we send. Extract this from the payload and pass it to this method.

5. Optional: Custom Event Tracking #

// Track custom user actions (optional)
await GoMailer.trackEvent('button_clicked', {
  'button_name': 'subscribe'
});

6. Get Device Information #

// Get the device token (for debugging)
String? token = await GoMailer.getDeviceToken();

7. Flush Pending Events (Reliability) #

await GoMailer.flushPendingEvents();

For Android the SDK may queue events if called before the device token is registered. This method triggers an immediate flush attempt. (No-op on iOS for now.)

Runtime Events & Reliability #

The SDK emits structured events through the go_mailer_events EventChannel. Subscribe to the stream for diagnostics:

Reliability & Privacy Enhancements (>=1.3.0):

• Exponential backoff (500ms base, x2 factor, jitter up to 150ms, max 5 attempts) for token & event submissions on transient errors (429, 5xx, network timeouts) on BOTH Android & iOS.
• Pre-token event queue on both platforms (events tracked before registration are queued then flushed once token is registered or via flushPendingEvents()).
• Persistent disk-backed queue (Android: SharedPreferences, iOS: UserDefaults) survives app restarts/crashes.
• Queue size capped at 100 events; oldest is dropped with event_dropped emitted.
• Automatic basic email masking in logs & network payloads (maskedEmail field) to reduce PII exposure (original email still sent for association; configurable masking toggle planned).
• OkHttp (Android) / URLSession (iOS) with explicit timeouts.

Roadmap:

• Configurable queue size & retention policy.
• Additional sensitive field masking (e.g. emails by configuration toggle).
• Metrics / health pings API.

Example listener:

GoMailer.pushNotificationStream.listen((e) {
  final type = e['type'];
  final data = e['data'];
  debugPrint('GoMailer SDK Event: $type => $data');
});

How Go-Mailer Sends Notifications #

You don't need to worry about sending notifications - Go-Mailer handles this for you! When we send notifications to your users, we include a notification_id that you'll need to extract and use for tracking clicks.

What the notification payload looks like (for reference): #

iOS:

{
  "aps": {
    "alert": {
      "title": "Hello from Go-Mailer!",
      "body": "Your notification message"
    }
  },
  "notification_id": "abc123",
  "your_custom_data": "any_value"
}

Android:

{
  "notification": {
    "title": "Hello from Go-Mailer!",
    "body": "Your notification message"
  },
  "data": {
    "notification_id": "abc123",
    "your_custom_data": "any_value"
  }
}

Your job: Extract the notification_id and call GoMailer.trackNotificationClick(notification_id) when the user taps the notification.

Troubleshooting #

Common Issues #

"SDK not initialized"

• Make sure you call GoMailer.initialize() before any other methods

"Permission denied" on iOS

• iOS requires explicit permission. Call requestNotificationPermission()
• Check your app's notification settings in iOS Settings

"Notifications not received"

• Verify your Firebase setup (Android) or APNs certificates (iOS)
• Check that setUser() was called with a valid email
• Ensure Go-Mailer has your correct push certificates/keys

"Click tracking not working"

• Make sure you're extracting notification_id from the payload correctly
• Call trackNotificationClick() when the notification opens your app, not when it's received

Example Implementation #

import 'package:flutter/material.dart';
import 'package:go_mailer_push_sdk/go_mailer.dart';

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    // Initialize on app start
    _initializeGoMailer();
  }

  Future<void> _initializeGoMailer() async {
    await GoMailer.initialize(apiKey: 'your-api-key');
  }

  Future<void> _handleLogin(String email) async {
    // Identify user after login
    await GoMailer.setUser({'email': email});
    
    // Request permission at the right moment
    bool granted = await GoMailer.requestNotificationPermission();
    if (granted) {
      print('User will receive Go-Mailer notifications');
    }
  }

  // Handle notification clicks (implementation depends on your navigation)
  Future<void> _handleNotificationClick(Map<String, dynamic> data) async {
    final notificationId = data['notification_id'];
    if (notificationId != null) {
      await GoMailer.trackNotificationClick(notificationId);
    }
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      // Your app content
    );
  }
}

Requirements #

• Flutter >= 2.0.0
• Dart >= 2.12.0
• iOS 10.0+ / Android API level 16+
• Valid Go-Mailer account and API key

Need Help? #

• 📖 Complete Documentation
• 💬 Support
• 🐛 Report Issues

Go-Mailer - Customer engagement messaging platform
go-mailer.com