Quick Start

This article provides an example of quick integration of Altcraft mSDK for Flutter.

---

Step 0. Prerequisites

• A Flutter project is created and runs on Android/iOS.
• Native push providers are integrated into the project:
  • Android: FCM, HMS, RuStore
  • iOS: APNS, FCM, HMS
• Altcraft mSDK is configured on the native side:
  • push providers are registered;
  • JWT provider is registered if needed;
  • incoming push notification interception and passing to the SDK is configured.

Important

The JWT provider and push token provider are registered natively: in Application.onCreate on Android and in AppDelegate on iOS. They are not passed via the Dart API.

---

Step 1. Package Installation

Add the package to your Flutter project:

flutter pub add altcraft_sdk

After installation, fetch dependencies:

flutter pub get

---

Step 2. SDK Configuration and Initialization

Import the SDK and perform initialization at application startup, for example in main.dart:

import 'package:altcraft_sdk/altcraft_sdk.dart';
import 'package:flutter/widgets.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await AltcraftSDK.initialize(
    const AltcraftConfig(
      apiUrl: 'https://pxl-example.altcraft.com',
      appInfo: AppInfo(
        appID: '1:000000000000:android:0000000000000000',
        appIID: '00000000-0000-4000-8000-000000000000',
        appVer: '1.0.0',
      ),
      providerPriorityList: ['android-firebase'],
    ),
  );

  runApp(const AppRoot());
}

class AppRoot extends StatelessWidget {
  const AppRoot({super.key});

  @override
  Widget build(BuildContext context) {
    return const Directionality(
      textDirection: TextDirection.ltr,
      child: SizedBox.shrink(),
    );
  }
}

---

Step 3. Push Subscription

Push subscription is performed by calling pushSubscribe():

import 'package:altcraft_sdk/altcraft_sdk.dart';

void subscribeToPush() {
  AltcraftSDK.pushSubscribe(
    sync: true,
    profileFields: const {
      '_fname': 'Ivan',
      '_lname': 'Petrov',
    },
    customFields: const {
      'source': 'flutter_app',
    },
    cats: const [
      {
        'name': 'developer_news',
        'active': true,
      },
    ],
    replace: null,
    skipTriggers: null,
  );
}

• sync: true — executes the request synchronously on the native side. The Dart method still returns Future<void>; the request result comes through SDK events.
• sync: false — executes the request asynchronously. If sync is not provided, the native SDK uses true.
• profileFields — profile fields.
• customFields — custom subscription fields.
• cats — subscription categories.

The pushSubscribe() method returns Future<void>. In the example, calling without await is acceptable (fire-and-forget), since the processing result is available via SDK events.

---

Step 4. Subscribing to SDK Events

To receive call results and internal SDK events, use subscribeToEvents():

import 'dart:async';

import 'package:altcraft_sdk/altcraft_sdk.dart';

StreamSubscription<SdkEvent>? sdkEventsSubscription;

void subscribeToSdkEvents() {
  sdkEventsSubscription = AltcraftSDK.subscribeToEvents().listen(
    (SdkEvent event) {
      // event.function — name of the SDK function that triggered the event
      // event.type — event type: event / error / retryError
      // event.code — event code
      // event.message — event message
      // event.value — additional data, if any
      print('[AltcraftSDK event] ${event.function}: ${event.message}');
    },
  );
}

Future<void> unsubscribeFromSdkEvents() async {
  await sdkEventsSubscription?.cancel();
  sdkEventsSubscription = null;
  await AltcraftSDK.unsubscribeFromEvents();
}

---

Step 5. Requesting Notification Permission for Android

For Android, you can request notification permission via the SDK:

import 'package:altcraft_sdk/altcraft_sdk.dart';

Future<void> requestPushPermission() async {
  final bool granted = await AltcraftSDK.requestNotificationPermission();

  if (granted) {
    AltcraftSDK.pushSubscribe(sync: true);
  }
}

tip

For iOS, notification permissions are configured in the native part of the application along with UNUserNotificationCenter, APNS, and Notification Service Extension. The requestNotificationPermission() method in the current Flutter bridge is for Android; on iOS it returns false.