Prerequisites

  1. Minimum Supported OS Version: The SDK supports a minimum Android 5.0 Lollipop (API 21) and iOS 15.
  2. Environment: Minimum Flutter version: 3.3.0, Dart: 3.6.0

Installation

Add the dependency in pubspec.yaml:

dependencies:
    salesmanago_mobile_push: 1.0.0

or via command line:

flutter pub add salesmanago_mobile_push

and run installation:

flutter pub get

Initialization

All the methods available in the SDK are accessible via Salesmanago singleton class.

import 'package:salesmanago_mobile_push/sales_manago.dart';

In order to initialize SALESmanago SDK call init() method passing API key. This method must be called at the app startup.

Salesmanago.instance.init(<API key>);

API key can be obtained from your SALESmanago dashboard.

Configuration

There is a number of contact properties which can be set up with an SDK:

  • Contact data (name, email address, phone number, custom standard details)
  • Marketing consents (email, mobile, monitoring)
  • Additional custom consents
  • List of tags

They can be all set with a single method:

import 'package:salesmanago_mobile_push/model/additional_consent.dart';
import 'package:salesmanago_mobile_push/model/contact_data.dart';
import 'package:salesmanago_mobile_push/model/marketing_consents.dart';
import 'package:salesmanago_mobile_push/model/opt_in_option.dart';

Salesmanago.instance.updateContactProperties(
  contactData: ContactData(
    name: 'John Doe',
    email: 'john.doe@email.com',
    phone: '+48123456789',
    standardDetails: {
      'first_detail': 'first_value',
      'second_detail': 'second_value',
    },
  ),
  marketingConsents: MarketingConsents(
    email: OptInOption.granted,
    mobile: OptInOption.granted,
    monitoring: OptInOption.denied,
  ),
  additionalConsents: [
    AdditionalConsent(
      name: 'custom consent',
      status: OptInOption.denied,
    ),
  ],
  tagsToAdd: ['tag_to_add'],
  tagsToRemove: ['tag_to_remove'],
);

OptInOption is an SDK enum class representing possible values for consents:

  • granted - Contact has given the consent
  • denied - Contact has rejected or withdrawn the consent
  • noAnswer - Contact has neither given nor rejected the consent. The status will not change. If there was no status, the consent will be set as rejected.

All parameters are optional so this method can be used to set just some of them. However there are also dedicated methods which can be used to set selected type of contact properties.

Contact data:

Salesmanago.instance.updateContactData(
  name: 'John Doe',
  email: 'john.doe@email.com',
  phone: '+48123456789',
);

Marketing consents:

Salesmanago.instance.updateContactMarketingConsents(
  email: OptInOption.denied,
  mobile: OptInOption.noAnswer,
  monitoring: OptInOption.granted,
);

Additional custom consents:

Salesmanago.instance.updateContactAdditionalConsents([
  AdditionalConsent(
    name: 'some custom consent',
    status: OptInOption.granted,
  ),
]);

Tags:

Salesmanago.instance.addTags(['only_tag_to_add']);
Salesmanago.instance.removeTags(['only_tag_to_remove']);

Events

SALESmanago SDK enables to track user activity by sending pre-defined events:

import 'package:salesmanago_mobile_push/model/event_type.dart';

Salesmanago.instance.addEvent(EventType.login);

EventType is an SDK enum class representing possible event types. Currently following types are available:

  • login - user logs into the application

Push notifications

Push notifications are sent via Firebase Cloud Messaging on Android and via APNs on iOS.

Your app has to ask a user to permit showing notifications. Without it, the SDK will not be allowed to show the notifications. After the user grants the permission, request the SDK to update its status via onPushNotificationSystemPermissionsChanged() method.

Additionally, there is a separate method to set the contact's opt-in status for receiving in-app marketing push notifications:

Salesmanago.instance.updateMobilePushOptIn(OptInOption.granted);

iOS

Additional configuration for iOS is only required for deep links handling.

The deep link scheme has to be declared in your Info.plist file. For instance, if you create a notification with the deep link salesmanago://salesmanago.com/main in the SM dashboard, your Info.plist file should contain:

<key>FlutterDeepLinkingEnabled</key>
<true/>
<key>CFBundleURLTypes</key>
<array>
	<dict>
		<key>CFBundleTypeRole</key>
		<string>Editor</string>
		<key>CFBundleURLName</key>
		<string>YOUR APP BUNDLE IDENTIFIER</string>
		<key>CFBundleURLSchemes</key>
		<array>
			<string>salesmanago</string>
		</array>
	</dict>
</array>

You can also specify it in Xcode:

In your application target, open Info tab. In URL Types section click + and enter required data:

  • Identifier: your app bundle identifier
  • URL scheme: your unique scheme, in this example salesmanago

Now your Flutter application will receive the deeplink main in the navigation configuration:

MaterialApp(
  onGenerateRoute: (settings) {
    settings.name // this variable should contain 'main'
    );
  },
);

Note:
The iOS part of the Flutter framework treats deep links like URLs - the navigation works on paths and begins after scheme and host.
For instance, the deep link salesmanago://salesmanago.com/main will be truncated to just /main in the Flutter navigation.
When creating your deep links, be sure to include the host before path to navigate.

On the other side, on Android, Flutter receives the full deep link URL (with the scheme and host).

Android

All the Firebase management work is done inside the SDK. The only thing to do is to connect the app with your Firebase project via JSON file generated in your Firebase project dashboard.

Paste your google-services.json file into the android app-level root directory (/android/app). Next, add the Google services Gradle plugin in your android project-level build.gradle file (/android/build.gradle):

plugins {
    // dependency for the Google services Gradle plugin
    id("com.google.gms.google-services") version "<version>" apply false
}

and in the android app-level build.gradle file ((/android/app/build.gradle):

plugins {
    id("com.android.application")

    // Google services Gradle plugin
    id("com.google.gms.google-services")

    ...
}

If you want to use deep links in your push notifications, you have to declare it in your app. The AndroidManifest.xml file declares your main activity (usually MainActivity) in <activity> tag. To make this activity able to handle your deep links, you should declare your scheme in a separate intent-filter. For instance, if you create a notification with the deep link salesmanago://salesmanago.com/main in the SM dashboard, your <activity> tag should contain:

<activity
    ...
    ...

    <intent-filter> 
        ...
    </intent-filter>
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:scheme="salesmanago" />
    </intent-filter>
</activity>

Now your Flutter application will receive the deeplink salesmanago://salesmanago.com/main in the navigation configuration:

MaterialApp(
  onGenerateRoute: (settings) {
    settings.name // this variable should contain 'salesmanago://salesmanago.com/main' on notification click
    );
  },
);

In-App

For your app to display in-apps properly, your Android main activity should not block the affinity. It is usually done in the AndroidManifest.xml file under the <activity> tag via the attribute android:taskAffinity. Ensure your activity does not have an attribute android:taskAffinity="".

Libraries

internal/platform_data_mapper
internal/sales_manago_method_channel
internal/sales_manago_platform
model/contact_data
model/event_type
model/marketing_consents
model/opt_in_option
sales_manago