QuickStart Guide

Welcome to SuperFCM - a modern, lightweight push notification platform for mobile apps, built on top of Firebase Cloud Messaging (FCM).

warning

This documentation is currently under construction and may be incomplete. If you find any errors or missing information, please reach out to info@superfcm.com.

What You'll Learn

In this quickstart guide, you'll learn:

• What SuperFCM is and how it enhances Firebase Cloud Messaging
• How to integrate the SuperFCM Flutter SDK into your mobile application
• The core functionality of the SDK including:
  • Initializing the SDK and handling notification permissions
  • Managing user sessions for engagement tracking
  • Implementing event tracking for triggered notifications
  • Working with custom properties for audience segmentation
  • Setting up test devices for notification testing
  • Linking user IDs for cross-device tracking

What is SuperFCM?

SuperFCM provides a powerful yet intuitive interface to manage subscribers, segment audiences, and send notifications beyond the basics — whether instant, scheduled, event-triggered, or recurring at flexible intervals.

With SuperFCM, you can:

• Manage subscriber lists with powerful segmentation
• Send targeted push notifications
• Schedule notifications in advance
• Set up event-triggered notifications
• Create recurring notification campaigns
• Track notification delivery and engagement

Prerequisites

Before getting started with SuperFCM:

1. Register an account at SuperFCM.
2. Create a new app in the SuperFCM dashboard.
3. Set up Firebase for your project (if you haven't already).

tip

For detailed instructions on account setup and Firebase integration, please see our Account Setup Guide.

SuperFCM SDK Integration

SuperFCM offers SDK integration for different platforms. This guide will cover the basics of getting started with our Flutter SDK.

1. Install the SDK

Add the SuperFCM Flutter SDK to your pubspec.yaml:

dependencies:
  superfcm_flutter: ^latest_version

Run the following command to install the dependencies:

flutter pub get

2. Initialize Firebase

Ensure Firebase is properly initialized in your app:

import 'package:firebase_core/firebase_core.dart';

// Initialize Firebase
await Firebase.initializeApp();

tip

This is the only point where a direct reference to Firebase is required in your Flutter app when using SuperFCM. The SuperFCM Flutter SDK is built as a wrapper around Firebase Cloud Messaging (FCM). While it's technically possible to use FCM features directly alongside SuperFCM, we do not recommend it, and such usage has not been tested.

3. Initialize SuperFCM

Initialize SuperFCM as early as possible in your app's lifecycle, typically in your main.dart file:

import 'package:superfcm_flutter/superfcm_flutter.dart';

// Configure and initialize SuperFCM
await SuperFCM.instance.initialize(
  SuperFCMConfig(
    // replace with your App ID from the SuperFCM dashboard
    appId: 'your-superfcm-app-id',
  ),
  onOpened: (message) {
    // Handle when app is opened from notification
    print('App opened from message: ${message.data}');
  },
  onForeground: (message) {
    // Handle foreground messages
    print('Received message: ${message.data}');
  },
);

SDK Core Functionality

Permission Handling

SuperFCM tracks notification permission status automatically but doesn't request permissions without your explicit command:

SuperFCM.instance.requestPermission(
  alert: true,
  badge: true,
  sound: true,
)

Session Tracking

SuperFCM automatically tracks app sessions to help you understand user engagement patterns:

// Configure session behavior during initialization
final config = SuperFCMConfig(
  appId: 'your-superfcm-app-id',
  // Enable automatic session tracking (default: true)
  autoTrackSessions: true,
  // Set inactivity threshold for new sessions (default: 30 minutes)
  sessionInactivityThreshold: Duration(minutes: 30),
);

Event Tracking

Track events that can trigger notifications configured in the SuperFCM Dashboard:

SuperFCM.instance.trackEvent('begin_checkout');

Managing Custom Properties

Use custom properties for precise audience segmentation:

// Update multiple properties
SuperFCM.instance.updateProperties({
  'hasSubscription': true,
  'totalSpent': 19.99,
  'favoriteCategory': 'electronics',
});

Linking User IDs (Cross-Device Tracking)

Link a user's identity with their device to enable cross-device tracking:

SuperFCM.instance.linkExternalId('your-user-id');

warning

If your app supports sign-in or account switching, be aware that linking an external ID only updates the external ID for the matching subscription. All other properties — including custom properties — will remain unchanged.

Best Practice: After linking a new external ID, explicitly refresh or re-sync the subscription data to ensure all relevant properties (like custom attributes or plan details) are up to date.

Testing Notifications

To designate a device for receiving test notifications:

SuperFCM.instance.setTest(true);

note

Only subscriptions designated as test will be available as test users in the SuperFCM dashboard.

Need Help?

If you encounter any issues or have questions, please contact us at info@superfcm.com or visit our GitHub repository for the Flutter SDK.