Mobile SDK Integration

PushPilot delivers notifications via FCM topics. Your app must subscribe each device to the correct topics during initialisation. The minimum required topic is "all".

Why is this required?

PushPilot sends notifications to FCM topics, not individual device tokens. A device that has not subscribed to the relevant topic will never receive notifications from your PushPilot campaigns, regardless of whether FCM is configured correctly in the dashboard.

Required FCM topic

all

Subscribe every device to this topic on app initialisation

Install dependency

yaml

# pubspec.yaml
dependencies:
  firebase_core: ^2.0.0
  firebase_messaging: ^14.0.0

Subscribe to topic

dart

import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_messaging/firebase_messaging.dart';

Future<void> initPushPilot() async {
  // Ensure Firebase is initialised
  await Firebase.initializeApp();

  final messaging = FirebaseMessaging.instance;

  // Request permission (required on iOS)
  await messaging.requestPermission(
    alert: true,
    badge: true,
    sound: true,
  );

  // Subscribe to the 'all' topic — required for PushPilot campaigns
  await messaging.subscribeToTopic('all');
  debugPrint('PushPilot: subscribed to FCM topic "all"');
}

// Call initPushPilot() in main() or after login:
//
// void main() async {
//   WidgetsFlutterBinding.ensureInitialized();
//   await initPushPilot();
//   runApp(const MyApp());
// }

Quick-start checklist

1
Add Firebase to your app
Follow the Firebase setup guide for your platform and initialise the Firebase SDK.
2
Request notification permission
On iOS, permission must be granted by the user before topics can be subscribed.
3
Subscribe to the "all" topic
Call subscribeToTopic("all") during app initialisation or right after login.
4
Connect Firebase in PushPilot
Go to Integrations → Firebase Projects and upload your service-account JSON.
5
Create a campaign and activate it
Build a campaign in PushPilot — devices subscribed to "all" will receive notifications.

Subscribing to custom topics

Beyond the all topic, you can subscribe users to additional topics (e.g. premium, news) based on user preferences or behaviour.

Custom topic subscription (Flutter)

// Subscribe a user to additional topics after they choose preferences
Future<void> subscribeToTopics(List<String> topics) async {
  final messaging = FirebaseMessaging.instance;
  for (final topic in topics) {
    await messaging.subscribeToTopic(topic);
  }
}

// Example: subscribe premium users
await subscribeToTopics(['all', 'premium', 'weekly-digest']);

Before using a custom topic in a campaign, go to Integrations → Topics and register the topic name.

OneSignal apps

If you are using OneSignal as your push provider, no additional SDK changes are needed beyond your existing OneSignal SDK integration. PushPilot targets users via OneSignal Segments rather than FCM topics.

Next steps

Connect Firebase (FCM)Topics & Segments Creating Campaigns FAQ