Installation and configuration (Flutter)

In this article you will find out how to install and initialize SDK in a Flutter mobile application. While performing the actions from this guide, keep the order presented in this article.

Important: The Settings article contains additional information about SDK behaviors you may need prior to configuration.


You need:

  • Access to workspace
  • A Profile API Key
    When creating the API key, use allowlisting or denylisting to only allow the events you intend to use.
  • Flutter configured on your machine - Getting Started
  • VS Code / Android Studio / Xcode


For the Android platform it uses the Synerise Android SDK.

The development and debugging can be done with Android Studio.

  • Recommended environment:
    • Minimum Android SDK version - 21
    • Supported targetSDKVersion - 33


For the iOS platform it uses the Synerise iOS SDK.

The development and debugging can be done with Xcode.

  • Recommended environment:
    • Xcode 15
    • iOS SDK 17
  • Target deployment: iOS 9.0+



 $ flutter pub add synerise_flutter_sdk

This will add a line similar to this to your package’s pubspec.yaml and run an implicit flutter pub get:

  synerise_flutter_sdk: ^0.7.4

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

Path dependency

First you will need to add the Synerise Flutter SDK to your mobile application. To do that you can use the path dependency method in your pubspec.yaml as follows:

via ssh:



via https:


After that you can run flutter pub get to resolve the new dependency.

Importing Synerise SDK

You will need to import Synerise.dart from the synerise_flutter_sdk plugin.

import 'package:synerise_flutter_sdk/synerise.dart';

Android gradle & configuration

  1. In the Android part of your application, add
    maven { url '' }
    to the android/build.gradle:

  2. Make sure you included the following repositories:
    google() mavenCentral()

The whole build.gradle snippet must look as follows:

repositories {
    maven { url '' }

then in your MainActivity file add:

public class MainActivity extends FlutterActivity {
public void configureFlutterEngine(@NonNull FlutterEngine flutterEngine) {

iOS configuration

In iOS portion of your application (/ios) you will need to run pod update


Basic initialization

Initialize the Synerise SDK and provide the Profile API Key.

Important: Initialize Synerise SDK in the application workflow as early as possible.
  .withClientApiKey("YOUR_PROFILE_API_KEY")  // 1
  .withRequestValidationSalt("YOUR_REQUEST_VALIDATION_SALT")  // 2
  .withDebugModeEnabled(false)  // 3
  .withCrashHandlingEnabled(true)  // 4
  1. .withClientApiKey('YOUR_PROFILE_API_KEY') - Sets Profile API Key for Synerise SDK initialization.
  2. .withRequestValidationSalt('YOUR_REQUEST_VALIDATION_SALT') - Sets salt string for request validation.
  3. .withDebugModeEnabled(false) - Enables debug mode. See Debug mode section for more information.
  4. .withCrashHandlingEnabled(true) - Enables crash handling. Synerise SDK sends a crash event automatically when an uncaught exception occurs.
Important: Secure sensitive keys (for example, clientApiKey and requestValidationSalt) with mechanisms like string obfuscation or encryption.

Initialization with custom API environment

You can change the base URL of the API for on-premise installations.

Use the following initialization method:


Running example app

  • Open project folder in selected IDE
  • flutter pub get in the terminal (dependencies pull)
  • select the device/emulator in your IDE (for ios part it is required to run pod update in example/ios directory)
  • cd example and flutter run

Debug mode

You can enable debug logs for Synerise SDK by using the .withDebugModeEnabled(true) method in Synerise.initializer when you initialize the SDK.

WARNING: Do not use debug mode in a release version of your application.

You can receive logs about:

  • Core: push notifications
  • Tracker: declarative events, sending process
  • Client: customer state, authorization
  • Injector: campaigns
  • Content: content widget, documents, recommendations

Main Synerise listeners

Injector Listeners

You can specify your custom action when a customer clicks on simple push, banner or walkthrough. Synerise SDK implements two main actions that a customer may invoke - open URL and Deeplink:

  • listener.onOpenUrl = (url) - This method is called when Synerise handles URL action from campaign activities.
  • listener.onDeepLink = (deepLink) - This method is called when Synerise handles deeplink action from campaign activities. Note: For more information about handling actions from the Synerise SDK, see the Campaigns section.
Synerise.injector.listener((listener) {
  listener.onOpenUrl = (url) {
  listener.onDeepLink = (deepLink) {

### Notifications Listeners

When you want to deal with Push Notifications:

- listener.onRegistrationRequired - This method is called when Synerise needs registration for Push Notifications.

Synerise.notifications.listener((listener) {
  listener.onRegistrationRequired = () {
    FirebaseMessaging.instance.getToken().then((value) {
      if (value != null) {
        Synerise.notifications.registerForNotifications(value, true);

We are sorry to hear that

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.



Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

Close modal icon Placeholder alt for modal to satisfy link checker