Cantal

⚙️ Prerequisites

There are a few steps required before you start integrating the iAdvize Messenger SDK.

💬 Setting up your iAdvize environment

Before integrating the SDK, you need to check that your iAdvize environment is ready to use (i.e. you have an account ready to receive and answer to conversations from the SDK). You will also need some information related to the project for the SDK setup. Please ask your iAdvize administrator to follow the instructions available on the SDK Knowledge Base and to provide you with the Project Identifier as well as a Targeting Rule Identifier.

Your iAdvize administrator should already have configured the project on the iAdvize Administration Desk and created an operator account for you. If it is not yet the case please contact your iAdvize Technical Project Manager.

💻 Connecting to your iAdvize Operator Desk

Using your operator account please log into the iAdvize Desk.

If you have the Administrator status in addition to your operator account, you will be directed to the Admin Desk when logging in. Just click on the Chat button in the upper right corner to open the Operator Desk.

The iAdvize operator desk is the place where the conversations that are assigned to your account will pop up. Please ensure that your status is “Available" by enabling the corresponding chat or video toggle buttons in the upper right corner:

The chat button is green, your operator can receive incoming conversations.

If the toggle button is yellow, it means you have reached your maximum simultaneous chat slots, please end your current conversations to free a chat slot and allow the conversations to be assigned to you. If the toggle is red you are not available to chat.

🔐 Ensuring the SDK integrity

Before downloading the iAdvize Messenger SDK artifacts you can verify their integrity by generating their checksums and comparing them with the reference checksums available.

Android

Reference checksums are available:

• in the GitHub release note

• in the dedicated spreadsheet

The Android SDK consists of an archive (aar file) and a Maven project description (pom file), you can generate their checksums using the following commands (replace x.y.z by the SDK version you are checking):

curl -sL https://github.com/iadvize/iadvize-android-sdk/raw/master/com/iadvize/iadvize-sdk/x.y.z/iadvize-sdk-x.y.z.aar | openssl sha256

curl -sL https://github.com/iadvize/iadvize-android-sdk/raw/master/com/iadvize/iadvize-sdk/x.y.z/iadvize-sdk-x.y.z.pom | openssl sha256

This ensures that the online packages are valid. In order to check those checksums on the fly, this process can be automated via Gradle by adding a metadata verification xml file at $PROJECT_ROOT/gradle/verification-metadata.xml:

<?xml version="1.0" encoding="UTF-8"?>
<verification-metadata ...>
   <configuration>
      <verify-metadata>true</verify-metadata>
      <verify-signatures>false</verify-signatures>
   </configuration>
   <components>
      <component group="com.iadvize" name="iadvize-sdk" version="x.y.z">
         <artifact name="iadvize-sdk-2.8.2.aar">
            <sha256 value="checksum value" origin="iAdvize website" />
         </artifact>
         <artifact name="iadvize-sdk-x.y.z.pom">
            <sha256 value="checksum value "origin="iAdvize website" />
         </artifact>
      </component>
   </components>
</verification-metadata>

With this file present in your project structure, Gradle will automatically check the artifacts checksums before integrating them into your app. Please note that you will have to do this for all dependencies used in your project. To help you with that, verification-metadata.xml for the SDK sub-dependencies is delivered alongside the SDK. Those subdependencies checksums have been generated through the Gradle generation feature and not verified.

iOS

Reference checksums are available:

• in the GitHub release note

• in the dedicated spreadsheet

Swift Package Manager integration

The iOS SDK only consists of an archive (zip file). You can generate its checksums using the following command (replace x.y.z by the SDK version you are checking):

curl -sL https://github.com/iadvize/iadvize-ios-sdk/releases/download/x.y.z/IAdvizeSDK.zip | openssl sha3-256

SPM will also automatically verify that the checksum of the artifact it downloads correspond to the one described in the Package.swift available in the public repository (it's a SHA2-256 checksum).

CocoaPods integration

The iOS SDK consists of an archive (zip file) and a Cocoapods project description file (podspec file). You can generate their checksums using the following commands (replace x.y.z by the SDK version you are checking):

curl -sL https://github.com/iadvize/iadvize-ios-sdk/releases/download/x.y.z/IAdvizeSDK.zip | openssl sha3-256

curl -sL https://raw.githubusercontent.com/CocoaPods/Specs/master/Specs/d/0/0/iAdvize/x.y.z/iAdvize.podspec.json | openssl sha3-256

After downloading the SDK through CocoaPods, additional verifications can be made, first by comparing the podspec checksum at the end of the generated Podfile.lock with the SHA1 podspec reference checksum.

SPEC CHECKSUMS:
  iAdvize: podspec-sha1-checksum

The downloaded framework integrity can also be checked by generating the local pod files checksums and comparing them with the online reference ones:

cd Pods/iAdvize
find IAdvizeConversationSDK.xcframework -type f -exec openssl sha3-256 {} \; >> IAdvizeSDK-local.checksums

React Native

Our React Native SDK plugin is hosted on an external platform called Node Package Manager (NPM) that already has internal checksum validation strategies in order to ensure that the downloaded plugin code (the wrapper code) is untampered.

Flutter

Our Flutter SDK plugin is hosted on an external platform called pub.dev, that already has internal checksum validation strategies in order to ensure that the downloaded plugin code (the wrapper code) is untampered.

⚙️ Setting up the SDK

1️⃣ Setting up the SDK into your project configuration

First of all, to be able to use the SDK you need to add the SDK dependency into your project. Some configuration steps will also be needed in order to use it.

Android

Add the iAdvize repository to your project repositories inside your top-level Gradle build file:

// Project-level build.gradle.kts

allprojects {
  repositories {
    maven(url = uri("https://raw.github.com/iadvize/iadvize-android-sdk/master"))
    maven(url = uri("https://jitpack.io"))
  }
}

Add the iAdvize Messenger SDK dependency inside your module-level Gradle build file (replace x.y.z by the latest SDK version available):

// Module-level build.gradle.kts

configurations {
  all {
    exclude(group = "xpp3", module = "xpp3")
  }
}

dependencies {
  implementation("com.iadvize:iadvize-sdk:x.y.z")
}

The exclude configuration is required because the iAdvize Messenger SDK uses Smack, an XMPP library that is built upon xpp3, which is bundled by default in the Android framework. This exclude ensures that your app does not also bundle xpp3 to avoid classes duplication errors.

In that same file, you also need to ensure that you are using the right Android target to build (iAdvize Messenger SDK is built with Android target 33):

// Module-level build.gradle.kts

android {
  buildToolsVersion "33.0.1"

  defaultConfig {
    minSdk = 21
    targetSdk = 33
    compileSdk = 33
  }
}

iAdvize Messenger SDK requires a minSdkVersion >= 21.

After syncing your project you should be able to import the iAdvize dependency in your application code with import com.iadvize.conversation.sdk.IAdvizeSDK

You will then need to provide a reference to your application object and initialize the SDK with it.

In your AndroidManifest.xml declare your application class:

<application android:name="my.app.package.App">
  <!-- your activities etc... -->
</application>

This class should then initialize the SDK:

package my.app.package.App

class App : Application() {
  override fun onCreate() {
    super.onCreate()
    IAdvizeSDK.initiate(this)
  }
}

⌨️ In-context example:

• Project-level Gradle file

• Module-level Gradle file

• Import

• SDK Initiation

The SDK supports video conversations using a third-party native (C++) binaries. If you are delivering your app using an APK you will note a size increase as the default behavior of the build system is to include the binaries for each ABI in a single APK. We strongly recommended that you take advantage of either App Bundles or APK Splits to reduce the size of your APKs while still maintaining maximum device compatibility.

iOS

SPM

From Xcode go to File > Add Packages, then paste the iAdvize Messenger SDK URL https://github.com/iadvize/iadvize-ios-sdk in the top-right search bar. Select the versioning strategy fitting your app then click on Add Package.

You should then be able to import the iAdvize dependency in your application code using import IAdvizeConversationSDK

⌨️ In-context example: Import

CocoaPods

Add this line to your Podfile, inside the target section (replace x.y.z by the latest SDK version available, and choose the versioning strategy fitting your app):

platform :ios, '13.0'

target 'YOUR_TARGET' do
  project 'YOUR_PROJECT'
  pod 'iAdvize', 'x.y.z'
end

iAdvize Messenger SDK requires a minimum iOS platform of 13.0.

After running pod install you should be able to import the iAdvize dependency in your application code with import IAdvizeConversationSDK

⌨️ In-context example:

• Podfile

• Import

The SDK supports video conversations. Thus it will request camera and microphone access before entering a video call. To avoid the app to crash, you have to setup two keys in your app Info.plist

<key>NSCameraUsageDescription</key>
<string>This application will use the camera to share photos and during video calls.</string>
<key>NSMicrophoneUsageDescription</key>
<string>This application will use the microphone during video calls.</string>

React Native

Download the library from NPM using the following command:

npm install @iadvize-oss/iadvize-react-native-sdk

Alternatively, you can use Yarn:

yarn add @iadvize-oss/iadvize-react-native-sdk

The SDK API is then available via the following import:

import IAdvizeSDK from '@iadvize-oss/iadvize-react-native-sdk';

Android setup

In your android/build.gradle file, and add the iAdvize SDK repository. You also need to ensure that you are using the right Android framework to build (iAdvize Messenger SDK is built with Android target 33):

// android/build.gradle

buildscript {
  ext {
    buildToolsVersion = "33.0.1"
    minSdkVersion = 21
    compileSdkVersion = 33
    targetSdkVersion = 33
  }
}

allprojects {
  repositories {
    maven { url "https://raw.github.com/iadvize/iadvize-android-sdk/master" }
    maven { url "https://jitpack.io" }
  }
}

iAdvize Messenger SDK requires a minSdkVersion >= 21.

On Android, the iAdvize Messenger SDK needs to be initialized before use to allow several functionalities to work. For instance, the default floating button use an ActivityLifecycleController that must be started before the main ReactNative activity is created, otherwise the controller won't be able to trigger the button display. Thus you need to add those lines in the android/app/src/main/java/yourpackage/MainApplication.java to initialize the SDK properly:

// android/app/src/main/java/yourpackage/MainApplication.java

import com.iadvize.conversation.sdk.IAdvizeSDK;

public class MainApplication extends Application implements ReactApplication {
   @Override
   public void onCreate() {
     super.onCreate();
     IAdvizeSDK.initiate(this);
   }
}

iOS setup

Add this line to your Podfile, inside the target section (replace x.y.z by the latest SDK version available, and choose the versioning strategy fitting your app):

platform :ios, '13.0'

target 'YOUR_TARGET' do
  project 'YOUR_PROJECT'
  pod 'iAdvize', 'x.y.z'
end

iAdvize Messenger SDK requires a minimum iOS platform of 13.0.

Once this is done, make sure to go to ios folder and install CocoaPods dependencies:

cd ios && pod install --repo-update

The SDK supports video conversations. Thus it will request camera and microphone access before entering a video call. To avoid the app to crash, you have to setup two keys in your app Info.plist

<key>NSCameraUsageDescription</key>
<string>This application will use the camera to share photos and during video calls.</string>
<key>NSMicrophoneUsageDescription</key>
<string>This application will use the microphone during video calls.</string>

Flutter

Download the library from pub.dev using the following command:

flutter pub add iadvize_flutter_sdk

The SDK API is then available via the following import:

import 'package:iadvize_flutter_sdk/iadvize_sdk.dart';

Android setup

In your android/build.gradle file, and add the iAdvize SDK repository:

// android/build.gradle

allprojects {
  repositories {
    maven { url "https://raw.github.com/iadvize/iadvize-android-sdk/master" }
    maven { url "https://jitpack.io" }
  }
}

You also need to ensure that you are using the right Android framework to build (iAdvize Messenger SDK is built with Android target 33), as a good practice, also check that you are using the latest Kotlin version in android/build.gradle (you can find the version used in the plugin through its README file)

// android/build.gradle

buildscript {
  ext.kotlin_version = '1.8.10'
}

// android/app/build.gradle

defaultConfig {
  minSdkVersion 21
  targetSdkVersion 33
}

iAdvize Messenger SDK requires a minSdkVersion >= 21.

iOS setup

Add this line to your Podfile, inside the target section (replace x.y.z by the latest SDK version available, and choose the versioning strategy fitting your app):

platform :ios, '13.0'

target 'YOUR_TARGET' do
  project 'YOUR_PROJECT'
  pod 'iAdvize', 'x.y.z'
end

iAdvize Messenger SDK requires a minimum iOS platform of 13.0.

Once this is done, make sure to go to ios folder and install CocoaPods dependencies:

cd ios && pod install --repo-update

The SDK supports video conversations. Thus it will request camera and microphone access before entering a video call. To avoid the app to crash, you have to setup two keys in your app Info.plist

<key>NSCameraUsageDescription</key>
<string>This application will use the camera to share photos and during video calls.</string>
<key>NSMicrophoneUsageDescription</key>
<string>This application will use the microphone during video calls.</string>

2️⃣ Activating the SDK

Now that the SDK is available into your project build, let's integrate it into your app, first by activating it. Activation is the step that logs a user into the iAdvize flow.

You can choose between multiple authentication options:

Anonymous	For an unidentified user browsing your app.
Simple	For a logged in user in your app. You must pass a unique string identifier so that the visitor will retrieve his conversation history across multiple devices and platforms. The identifier that you pass must be unique and non-discoverable for each different logged-in user.
Secured	Use it in conjunction with your in-house authentication system. You must pass a JWE provider callback that will be called when an authentication is required, you will then have to call your third party authentication system for a valid JWE to provide to the SDK. For a full understanding of how the secured authentication works in the iAdvize platform you can refer to this section.

To activate the SDK you must use the activate function with your projectId (see the Prerequisites section above to get that identifier). You have access to callbacks in order to know if the SDK has been successfully activated. In case of an SDK activation failure the callback will give you the reason of the failure and you may want to retry later.

Android

IAdvizeSDK.activate(
  projectId = projectId,
  authenticationOption = authOption,
  gdprOption = gdprOption,
  callback = object : IAdvizeSDK.Callback {
    override fun onSuccess() {
      Log.d("iAdvize SDK", "The SDK has been activated.")
    }
    override fun onFailure(t: Throwable) {
      Log.e("iAdvize SDK", "The SDK activation failed with:", t)
    }
  }
)

⌨️ In-context example: SDK Activation

iOS

IAdvizeSDK.shared.activate(projectId: projectId,
                           authenticationOption: authOption,
                           gdprOption: gdprOption)) { success in
    if success {
        ...
    }
}

⌨️ In-context example: SDK Activation

React Native

try {
  // Anonymous Auth => Do not set the onJWERequested listener & set an empty userId
  await IAdvizeSDK.activate(projectId, '', ...);
  
  // Simple Auth => Do not set the onJWERequested listener & set a non-empty userId
  await IAdvizeSDK.activate(projectId, "my-user-unique-id", ...);
  
  // Secured Auth => Set the onJWERequested listener
  IAdvizeSDKListeners.onJWERequested(function (eventData: any) {
    console.log('onJWERequested' + ' ' + eventData);
    
    // Fetch JWE from your 3rd-party auth system
    
    // In SDK v3, you must return the value here (synchronously)
    var jwe = ... ;
    return jwe;
    
    // In SDK v4, you should the value using an asynchronous API call (here or elsewhere)
    IAdvizeSDK.provideJWE(jwe);
  });
  await IAdvizeSDK.activate(projectId, '', ...);

  // SDK is activated
} catch (e) {
  // SDK failed to activate
}

Flutter

IAdvizeSdk.activate(
  projectId: 'projectId',
  authenticationOption: authOption
  gdprOption: gdprOption,
  ).then((bool activated) => activated
      ? log('iAdvize Example : SDK activated')
      : log('iAdvize Example : SDK not activated'));

Once the iAdvize Messenger SDK is successfully activated, you should see a success message in the console:

✅ iAdvize conversation activated, the version is x.y.z

3️⃣ Logging the user out

You will have to explicitly call the logout function of the iAdvize Messenger SDK when the user sign out of your app.

Android

IAdvizeSDK.logout()

iOS

IAdvizeSDK.shared.logout()

React Native

IAdvizeSDK.logout()

Flutter

IAdvizeSdk.logout();

4️⃣ Displaying logs

To have more information on what’s happening on the SDK side you can change the log level.

Android

// VERBOSE, INFO, WARNING, ERROR, NONE
// Default is WARNING
IAdvizeSDK.logLevel = Logger.Level.VERBOSE

iOS

// verbose, info, warning, error, success, none
// Default is warning
IAdvizeSDK.shared.logLevel = .verbose

React Native

// VERBOSE, INFO, WARNING, ERROR, SUCCESS, NONE
// Default is WARNING
IAdvizeSDK.setLogLevel(LogLevel.VERBOSE);

Flutter

// verbose, info, warning, error, success, none
// Default is warning
IAdvizeSdk.setLogLevel(LogLevel.verbose);

💬 Starting a conversation

To be able to start a conversation you will first have to trigger a targeting rule in order for the default chat button to be displayed. The Chatbox will then be accessible by clicking on that chat button.

1️⃣ Configuring the targeting language

The targeting rule configured in the iAdvize Administration Panel is setup for a given language. This means that if, for example, you setup a targeting rule to be triggered only for EN language and the current user’s device is setup with a different targeting language (for instance FR), the targeting rule will not trigger.

By default, the targeting rule language used is the user’s device current language. You can force the targeting language to a specific value using:

Android

IAdvizeSDK.targetingController.language = LanguageOption.Custom(Language.FR)

iOS

IAdvizeSDK.shared.targetingController.language = .custom(value: .fr)

React Native

IAdvizeSDK.setLanguage('fr');

The language string should respect ISO 639-1.

Flutter

IAdvizeSdk.setLanguage('fr');

The language string should respect ISO 639-1.

This language property is NOT intended to change the language displayed in the SDK. It is solely used for the targeting process purpose.

2️⃣ Activating a targeting rule

Using a targeting rule UUID (see the Prerequisites section above to get that identifier), you can engage a user by calling:

Android

IAdvizeSDK.targetingController.activateTargetingRule(
  TargetingRule(
    targetingRuleUUID,
    ConversationChannel.CHAT // or ConversationChannel.VIDEO
  )
)

⌨️ In-context example: Targeting rule activation

iOS

let targetingRule = TargetingRule(id: UUID, conversationChannel: .chat) // or .video
IAdvizeSDK.shared.targetingController.activateTargetingRule(targetingRule: targetingRule)

⌨️ In-context example: Targeting rule activation

React Native

IAdvizeSDK.activateTargetingRule(targetingRuleUUIDString, ConversationChannel.CHAT); // OR ConversationChannel.VIDEO

Flutter

IAdvizeSdk.activateTargetingRule(TargetingRule(uuid: 'targeting-rule-uuid', channel: ConversationChannel.chat)); // or ConversationChannel.video

If all the following conditions are met, the default chat button should appear:

• the targeting rule exists and is enabled in the administration panel

• the targeting rule language set in the SDK matches the language configured for this rule

• an operator assigned to this rule is available to answer (connected and with a free chat slot)

After you activate a rule and it succeeds (by displaying the button), those conditions are checked every 30 seconds to verify that the button should still be displayed or not.

Upon the first encountered failure from this periodic check, the button is hidden and the SDK stops verifying the conditions. It means that if the rule cannot be triggered (after the first call, or after any successive check), you will have to call the activateTargetingRule (or registerUserNavigation) method again in order to restart the engagement process.

3️⃣ Initiating the conversation

Once the default chat button is displayed, the visitor tap on it to access the Chatbox. After composing and sending a message a new conversation should pop up in the operator desk.

Chat button is displayed. Visitor composes a message & send it.

Conversation appears in the operator desk

4️⃣ Following user navigation

While your user navigates through your app, you will have to update the active targeting rule in order to engage him/her with the best conversation partner at any time. In order to so, the SDK provides you with multiple navigation options to customize the behavior according to your needs:

Android

// To clear the active targeting rule and thus stopping the engagement process (this is the default behavior)
val navOption = NavigationOption.ClearActiveRule

// To keep/start the engagement process with the same active targeting rule in the new user screen
val navOption = NavigationOption.KeepActiveRule

// To keep/start the engagement process but with another targeting rule for this screen
val navOption = NavigationOption.ActivateNewRule(newRule)

// Register the user navigation through your app
IAdvizeSDK.targetingController.registerUserNavigation(navOption)

iOS

// To clear the active targeting rule and thus stopping the engagement process (this is the default behavior)
let navOption: NavigationOption = .clearActiveRule

// To keep/start the engagement process with the same active targeting rule in the new user screen
let navOption: NavigationOption = .keepActiveRule

// To keep/start the engagement process but with another targeting rule for this screen
let navOption: NavigationOption = .activateNewRule(targetinRuleId: newRuleId)

// Register the user navigation through your app
IAdvizeSDK.shared.targetingController.registerUserNavigation(navigationOption: navOption)

React Native

// To clear the active targeting rule and thus stopping the engagement process (this is the default behavior)
IAdvizeSDK.registerUserNavigation(NavigationOption.CLEAR, "", "");

// To keep/start the engagement process with the same active targeting rule in the new user screen
IAdvizeSDK.registerUserNavigation(NavigationOption.KEEP, "", "");

// To keep/start the engagement process but with another targeting rule for this screen
IAdvizeSDK.registerUserNavigation(NavigationOption.NEW, targetingRuleUUIDString, channel);

Flutter

// To clear the active targeting rule and thus stopping the engagement process (this is the default behavior)
IAdvizeSdk.registerUserNavigation(navigationOption: NavigationOption.optionClear);

// To keep/start the engagement process with the same active targeting rule in the new user screen
IAdvizeSdk.registerUserNavigation(navigationOption: NavigationOption.optionKeep);

// To keep/start the engagement process but with another targeting rule for this screen
IAdvizeSdk.registerUserNavigation(
  navigationOption: NavigationOption.optionNew,
  newTargetingRule: TargetingRule(uuid: 'targeting-rule-uuid', channel: ConversationChannel.chat) // or ConversationChannel.video
)

Please note that calling registerUserNavigation with the CLEAR NavigationOption will stop the engagement process, and calling it with other options will start it if it is stopped.

👋 Configuring GDPR and welcome message

1️⃣ Adding a welcome message

As seen above, the Chatbox is empty by default. You can configure a welcome message that will be displayed to the visitor when no conversation is ongoing.

Android

val configuration = ChatboxConfiguration()
configuration.automaticMessage = "Any question? Say Hello to Smart and we will answer you as soon as possible! 😊"
IAdvizeSDK.chatboxController.setupChatbox(configuration)

⌨️ In-context example: Welcome message

iOS

var configuration = ChatboxConfiguration()
configuration.automaticMessage = NSLocalizedString(
  "Any question? Say Hello to Smart and we will answer you as soon as possible! 😊",
  comment: ""
)
IAdvizeSDK.shared.chatboxController.setupChatbox(configuration: configuration)

⌨️ In-context example: Welcome message

React Native

const configuration: ChatboxConfiguration = {
  automaticMessage: "Any question? Say Hello to Smart and we will answer you as soon as possible! 😊",
};
IAdvizeSDK.setChatboxConfiguration(configuration);

Flutter

final ChatboxConfiguration configuration = ChatboxConfiguration(
  automaticMessage: "Any question? Say Hello to Smart and we will answer you as soon as possible! 😊",
);
IAdvizeSdk.setChatboxConfiguration(configuration);

When no conversation is ongoing, the welcome message is displayed to the visitor:

When no conversation is ongoing, the welcome message is displayed to the visitor

2️⃣ Enabling GDPR approval

If you need to get the visitor consent on GDPR before he starts chatting, you can pass a GDPROption while activating the SDK. By default this option is set to Disabled.

If enabled, a message will request the visitor approval before allowing him to send a message to start the conversation:

GDPR approval request

This GDPR option dictates how the SDK behaves when the user taps on the More information button. You can either:

• provide an URL pointing to your GPDR policy, it will be opened on user click

• provide a listener/delegate that will be called on user click and you can then implement your own custom behavior

If your visitors have already consented to GDPR inside your application, you can activate the iAdvize SDK without the GDPR process. However, be careful to explicitly mention the iAdvize Chat part in your GDPR consent details.

Android

// Disabled
val gdprOption = GDPROption.Disabled

// URL
val gdprOption = GDPROption.Enabled(GDPREnabledOption.LegalUrl(URI.create("http://my.gdpr.rules.com")))

// Listener
val gdprOption = GDPROption.Enabled(GDPREnabledOption.Listener(object : GDPRListener {
  override fun didTapMoreInformation() {
    // Implement your own logic
  }
}))

val configuration = ChatboxConfiguration()
configuration.automaticMessage = "Any question? Say Hello to Smart and we will answer you as soon as possible! 😊"
configuration.gdprMessage = "Your own GDPR message."
IAdvizeSDK.chatboxController.setupChatbox(configuration)

⌨️ In-context example:

• GDPR Option

• GDPR Message

iOS

// Disabled
let gdprOption = .disabled

// URL
if let legalInfoURL = URL(string: "http://my.gdpr.rules.com") {
  let gdprOption = .enabled(option: .legalInformation(url: legalInfoURL))
}

// Listener
class GDPRMoreInfoListener: GDPRDelegate {
  func didTapMoreInformation() {
    // Implement your own logid
  }
}
let gdprListener = GDPRMoreInfoListener()
let gdprOption = .enabled(option: .delegate(delegate: gdprListener))

var configuration = ChatboxConfiguration()
configuration.automaticMessage = NSLocalizedString(
  "Any question? Say Hello to Smart and we will answer you as soon as possible! 😊",
  comment: ""
)
configuration.gdprMessage = "Your own GDPR message."
IAdvizeSDK.shared.chatboxController.setupChatbox(configuration: configuration)

⌨️ In-context example:

• GDPR Option

• GDPR Message

React Native

// No listener set + null URL => GDPR is disabled
await IAdvizeSDK.activate(projectId, userId, null);

// No listener set + non-null URL => GDPR is enabled, the webpage opens when user click on more info button
await IAdvizeSDK.activate(projectId, userId, "http://my.gdpr.rules.com");

// Listener set => GDPR is enabled, the listener is called when user click on more info button
IAdvizeSDKListeners.onGDPRMoreInfoClicked(function (eventData: any) {
  // Implement your own behavior
});
await IAdvizeSDK.activate(projectId, userId, null);

If you set both the listener and an URL, the listener will take priority.

var configuration = ChatboxConfiguration()
configuration.automaticMessage = NSLocalizedString(
  "Any question? Say Hello to Smart and we will answer you as soon as possible! 😊",
  comment: ""
)
configuration.gdprMessage = "Your own GDPR message."
IAdvizeSDK.setChatboxConfiguration(configuration: configuration)

Flutter

// Disabled
GDPROption gdprOption = GDPROption.disabled();

// URL
GDPROption gdprOption = GDPROption.url(url: "http://my.gdpr.rules.com")

// Listener
GDPROption gdprOption = GDPROption.listener(onMoreInfoClicked: () {
  log('iAdvize Example : GDPR More Info button clicked');
  // Implement your own logic here
});

final ChatboxConfiguration configuration = ChatboxConfiguration(
  gdprMessage: "Your own GDPR message",
);
IAdvizeSdk.setChatboxConfiguration(configuration);

🎨 Branding the Chatbox

The ChatboxConfiguration object that we used in the previous section to customize the welcome and GDPR messages can also be used to change the Chatbox UI to better fit into the look and feel of your application.

You should setup the configuration before presenting the chatbox. If you call this method while the chatbox is visible, some parameters will only apply for new messages or after closing/reopening the chatbox.

1️⃣ Updating the font

The font used in the Chatbox can easily be updated using your own font:

Android

val configuration = ChatboxConfiguration()
configuration.fontPath = "fonts/comic_sans_ms_regular.ttf"
IAdvizeSDK.chatboxController.setupChatbox(configuration)

The font should be placed inside the assets folder. Here the file is located at src/main/assets/fonts/comic_sans_ms_regular.ttf

iOS

var configuration = ChatboxConfiguration()
configuration.font = UIFont(name: "AmericanTypewriter-Condensed", size: 11.0)
IAdvizeSDK.shared.chatboxController.setupChatbox(configuration: configuration)

Even if the UIFont constructor needs a size attribute, the exact font size and traits are automatically chosen and the font is scaled to the current Dynamic Type setting.

The font should either be a system font, or be a font embedded into the app, with a font file inside the bundle and its corresponding declaration into the Info.plist file.

React Native

const configuration: ChatboxConfiguration = {
  // For iOS devices
  fontName: 'AmericanTypewriter-Condensed',
  fontSize: 11, // iOS only

  // For Android devices
  fontPath: 'fonts/comic_sans_ms_regular.ttf',
};

On iOS the font should either be a system font, or be a font embedded into the app, with a font file inside the bundle and its corresponding declaration into the Info.plist file.

On Android the font should be placed inside the assets folder. Here the file is located at src/main/assets/fonts/comic_sans_ms_regular.ttf

Flutter

final ChatboxConfiguration configuration = ChatboxConfiguration(
  // For iOS devices
  iosFontName: 'AmericanTypewriter-Condensed',
  iosFontSize: 11,

  // For Android devices
  androidFontPath: 'fonts/comic_sans_ms_regular.ttf',
);
IAdvizeSdk.setChatboxConfiguration(configuration);

On iOS the font should either be a system font, or be a font embedded into the app, with a font file inside the bundle and its corresponding declaration into the Info.plist file.

On Android the font should be placed inside the assets folder. Here the file is located at src/main/assets/fonts/comic_sans_ms_regular.ttf

2️⃣ Styling the navigation bar

Some parts of the he toolbar/navigationbar appearing at the top of the Chatbox can also be customized:

• the background color

• the main color

• the title

Android

val configuration = ChatboxConfiguration()
configuration.toolbarBackgroundColor = Color.BLACK,
configuration.toolbarMainColor = COLOR.WHITE,
configuration.toolbarTitle = "Conversation"
IAdvizeSDK.chatboxController.setupChatbox(configuration)

iOS

var configuration = ChatboxConfiguration()
configuration.navigationBarBackgroundColor = .black
configuration.navigationBarMainColor = .white
configuration.navigationBarTitle = "Conversation"
IAdvizeSDK.shared.chatboxController.setupChatbox(configuration: configuration)

React Native

const configuration: ChatboxConfiguration = {
  navigationBarBackgroundColor: '#000000',
  navigationBarMainColor: '#FFFFFF',
  navigationBarTitle: 'Conversation'
};
IAdvizeSDK.setChatboxConfiguration(configuration);

Flutter

final ChatboxConfiguration configuration = ChatboxConfiguration(
  navigationBarBackgroundColor: Colors.black,
  navigationBarMainColor: Colors.yellow,
  navigationBarTitle: 'Conversation',
);
IAdvizeSdk.setChatboxConfiguration(configuration);

3️⃣ Changing the Chatbox colors

The displayed messages colors can be customized, either the ones from the agent (incomingMessages) or the ones from the visitor (outgoingMessages):

• the message bubble background color

• the message text color

• the message bubble stroke/border color

• the accent color, used for all message controls (same color for both agent & visitor): quick answers, file messages, send button, typing indicator...

Android

val configuration = ChatboxConfiguration()
configuration.incomingMessageBackgroundColor = Color.BLACK
configuration.incomingMessageTextColor = Color.YELLOW
configuration.incomingMessageStrokeColor = Color.YELLOW
configuration.outgoingMessageBackgroundColor = Color.YELLOW
configuration.outgoingMessageTextColor = Color.BLACK
configuration.outgoingMessageStrokeColor = Color.BLACK
configuration.accentColor = Color.MAGENTA
IAdvizeSDK.chatboxController.setupChatbox(configuration)

iOS

var configuration = ChatboxConfiguration()
configuration.incomingMessageBackgroundColor = .black
configuration.incomingMessageTextColor = .yellow
configuration.incomingMessageBorderColor = .yellow
configuration.outgoingMessageBackgroundColor = .yellow
configuration.outgoingMessageTextColor = .black
configuration.outgoingMessageBorderColor = .black
configuration.accentColor = .magenta
IAdvizeSDK.shared.chatboxController.setupChatbox(configuration: configuration)

React Native

var configuration = ChatboxConfiguration()
configuration.incomingMessageBackgroundColor = '#000000';
configuration.incomingMessageTextColor = '#FFFF00';
configuration.incomingMessageStrokeColor = '#FFFF00';
configuration.outgoingMessageBackgroundColor = '#FFFF00';
configuration.outgoingMessageTextColor = '#000000';
configuration.outgoingMessageStrokeColor = '#000000';
configuration.accentColor = '#FF00FF';
IAdvizeSDK.setChatboxConfiguration(configuration: configuration)

Flutter

final ChatboxConfiguration configuration = ChatboxConfiguration(
  incomingMessageBackgroundColor: Colors.black,
  incomingMessageTextColor: Colors.yellow,
  incomingMessageStrokeColor: Colors.yellow,
  outgoingMessageBackgroundColor: Colors.yellow,
  outgoingMessageTextColor: Colors.black,
  outgoingMessageStrokeColor: Colors.black,
  accentColor: Colors.magenta,
);
IAdvizeSdk.setChatboxConfiguration(configuration);

4️⃣ Using a brand avatar

The operator avatar displayed alongside his messages can be updated for branding purposes. You can specify a drawable either via an URL or a local resource.

Android

val configuration = ChatboxConfiguration()

// Update the incoming message avatar with a Drawable resource.
configuration.incomingMessageAvatar = IncomingMessageAvatar.Image(
  ContextCompat.getDrawable(context, R.drawable.ic_brand_avatar)
)

// Update the incoming message avatar with an URL.
configuration.incomingMessageAvatar = IncomingMessageAvatar.Url(URL("http://avatar.url"))

IAdvizeSDK.chatboxController.setupChatbox(configuration)

iOS

var configuration = ChatboxConfiguration()

// Update the incoming message avatar with a UIImage.
configuration.incomingMessageAvatar = .image(image: UIImage(named: "BrandAvatar"))

// Update the incoming message avatar with an URL.
configuration.incomingMessageAvatar = .url(url: "http://avatar.url")

IAdvizeSDK.shared.chatboxController.setupChatbox(configuration: configuration)

React Native

const configuration: ChatboxConfiguration = {
  incomingMessageAvatarImageName: Image.resolveAssetSource(require('./test.jpeg')).uri,
  incomingMessageAvatarURL: 'https://picsum.photos/200/200',
};

If you fill both fields, incomingMessageAvatarImageName will take priority over incomingMessageAvatarURL.

Flutter

final ChatboxConfiguration configuration = ChatboxConfiguration(
  incomingMessageAvatarImage: const AssetImage('assets/test.jpeg'),
  // OR
  incomingMessageAvatarURL: 'https://picsum.photos/200/200',
);
IAdvizeSdk.setChatboxConfiguration(configuration);

If you fill both fields, incomingMessageAvatarImageName will take priority over incomingMessageAvatarURL.

GIFs are not supported.

🎨 Branding the Default Floating Button

By default, the SDK uses its own Default Floating Button for the user to engage in the conversation. This Default Floating Button display process is automated by the SDK and works out of the box. You have however limited possibilities to brand it to your needs.

Android

The Default Floating Button can be parametrized, both in its look (colors / icon) and position (anchor / margins) using the appropriate configuration:

val configuration = DefaultFloatingButtonConfiguration(
  anchor = Gravity.START or Gravity.BOTTOM,
  margins = DefaultFloatingButtonMargins(),
  backgroundTint = ContextCompat.getColor(this, R.color.colorPrimary),
  iconResIds = mapOf(
    ConversationChannel.CHAT to R.drawable.chat_icon,
    ConversationChannel.VIDEO to R.drawable.video_icon
  )
  iconTint = Color.WHITE
)
val option = DefaultFloatingButtonOption.Enabled(configuration)
IAdvizeSDK.defaultFloatingButtonController.setupDefaultFloatingButton(option)

⌨️ In-context example: Default Floating Button Configuration

iOS

The Default Floating Button will use hardcoded icons and the ChatboxConfiguration.accentColor as background color:

var configuration = ChatboxConfiguration()
configuration.accentColor = .red
IAdvizeSDK.shared.chatboxController.setupChatbox(configuration: configuration)

The Default Floating Button is anchored to the bottom left side of the screen. You can modify its placement by specifying the button margins:

IAdvizeSDK.shared.chatboxController.setFloatingButtonPosition(leftMargin: 20.0, bottomMargin: 20.0)

React Native

The Default Floating Button will use hardcoded icons and the ChatboxConfiguration.accentColor as background color:

const configuration: ChatboxConfiguration = {
  accentColor: '#000000',
};

The Default Floating Button is anchored to the bottom left side of the screen. You can modify its placement by specifying the button margins:

IAdvizeSDK.setFloatingButtonPosition(20, 20);

Flutter

The Default Floating Button will use hardcoded icons and the ChatboxConfiguration.accentColor as background color:

final ChatboxConfiguration configuration = ChatboxConfiguration(
  accentColor: Colors.red,
);
IAdvizeSdk.setChatboxConfiguration(configuration);

The Default Floating Button is anchored to the bottom left side of the screen. You can modify its placement by specifying the button margins:

IAdvizeSdk.setFloatingButtonPosition(leftMargin: 20, bottomMargin: 20);

✨ Using a custom chat button

If you are not satisfied with the Default Floating Button look and feel or if you want to implement a specific behavior related to its display you may need to use a custom conversation button.

With a custom button it is your responsibility to:

• design the floating or fixed button to invite your user to chat

• hide/show the button following the active targeting rule availability and the ongoing conversation status

• open the Chatbox when the user presses your button

1️⃣ Disabling the Default Floating Button

Android

IAdvizeSDK.defaultFloatingButtonController.setupDefaultFloatingButton(DefaultFloatingButtonOption.Disabled)

iOS

IAdvizeSDK.shared.chatboxController.useDefaultFloatingButton = false

React Native

IAdvizeSDK.setDefaultFloatingButton(false);

Flutter

IAdvizeSdk.setDefaultFloatingButton(false);

2️⃣ Displaying/hiding the chat button

The chat button is linked to the targeting and conversation workflow and should update its visibility each time the status of those workflows is changed. First of all you need to implement the appropriate callbacks:

Android

IAdvizeSDK.targetingController.listeners.add(object : TargetingListener {
  override fun onActiveTargetingRuleAvailabilityUpdated(isActiveTargetingRuleAvailable: Boolean) {
    // SDK active rule availability changed to isActiveTargetingRuleAvailable
    updateChatButtonVisibility()
  }
})

IAdvizeSDK.conversationController.listeners.add(object : ConversationListener {
  override fun onOngoingConversationUpdated(ongoingConversation: OngoingConversation?) {
    // SDK ongoing conversation has updated
    updateChatButtonVisibility()
  }
  override fun onNewMessageReceived(content: String) {
    // A new message was received via the SDK
  }
  override fun handleClickedUrl(uri: Uri): Boolean {
    // A message link was tapped, return true if you want your app to handle it
    return false
  }
})

iOS

extension IntegrationApp: TargetingControllerDelegate {
  func activeTargetingRuleAvailabilityDidUpdate(isActiveTargetingRuleAvailable: Bool) {
    // SDK active rule availability changed to isActiveTargetingRuleAvailable
    updateChatButtonVisibility()
  }
}
    
extension IntegrationApp: ConversationControllerDelegate {
  func ongoingConversationUpdated(ongoingConversation: IAdvizeConversationSDK.OngoingConversation?) {
    // SDK ongoing conversation status changed
    updateChatButtonVisibility()
  }
  func didReceiveNewMessage(content: String) {
    // A new message was received via the SDK
  }
  func conversationController(_ controller: ConversationController, shouldOpen url: URL) -> Bool {
    // A message link was tapped, return false if you want your app to handle it
  }
}

class IntegrationApp {
  IAdvizeSDK.shared.targetingController.delegate = self
  IAdvizeSDK.shared.conversationController.delegate = self
}

React Native

IAdvizeSDKListeners.onActiveTargetingRuleAvailabilityUpdated(function (eventData: any) {
  // SDK active rule availability changed
  updateChatButtonVisibility()
});

IAdvizeSDKListeners.onOngoingConversationStatusChanged(function (eventData: any) {
  // SDK ongoing conversation status changed
  updateChatButtonVisibility()
});

Flutter

IAdvizeSdk.setConversationListener(manageUrlClick: true);
IAdvizeSdk.onOngoingConversationUpdated.listen((bool ongoing) {
  _updateCustomChatButtonVisibility();
});

IAdvizeSdk.setOnActiveTargetingRuleAvailabilityListener();
IAdvizeSdk.onActiveTargetingRuleAvailabilityUpdated.listen((bool available) {
  _updateCustomChatButtonVisibility();
});

The chat button gives access to the Chatbox so it should be visible:

• at all times when a conversation is ongoing to allow the visitor to come back to the current conversation

• when the active targeting rule is available, to engage the visitor to chat

Android

fun updateChatButtonVisibility() {
  val sdkActivated = IAdvizeSDK.activationStatus == IAdvizeSDK.ActivationStatus.ACTIVATED
  val chatboxOpened = IAdvizeSDK.chatboxController.isChatboxPresented()
  val ruleAvailable = IAdvizeSDK.targetingController.isActiveTargetingRuleAvailable()
  val hasOngoingConv = IAdvizeSDK.conversationController.ongoingConversation() != null

  if (sdkActivated && !chatboxOpened && (hasOngoingConv || ruleAvailable)) {
    showChatButton()
  } else {
    hideChatButton()
  }
}

iOS

func updateChatButtonVisibility() {  
  guard IAdvizeSDK.shared.activationStatus == .activated else {
    hideChatButton()
    return
  }
  guard !IAdvizeSDK.shared.chatboxController.isChatboxPresented() else {
    hideChatButton()
    return
  }
  guard IAdvizeSDK.shared.conversationController.ongoingConversation() != nil ||
        IAdvizeSDK.shared.targetingController.isActiveTargetingRuleAvailable else {
      hideChatButton()
      return
  }
  showChatButton()
}

React Native

const updateChatButtonVisibility = async () => {
  const ruleAvailable = IAdvizeSDK.isActiveTargetingRuleAvailable()
  const hasOngoingConv = IAdvizeSDK.ongoingConversationId().trim().length !== 0
  const chatboxOpened = IAdvizeSDK.isChatboxPresented()

  if (!chatboxOpened && (hasOngoingConv || ruleAvailable)) {
    showChatButton()
  } else {
    hideChatButton()
  }
};

Flutter

bool _showCustomButton = false;

Future _updateCustomChatButtonVisibility() async {
  final bool sdkActivated = await IAdvizeSdk.isSDKActivated();
  final bool ruleAvailable = await IAdvizeSdk.isActiveTargetingRuleAvailable();
  final bool hasOngoingConv = await ongoingConversationId() != null;

  setState(() {
    _showCustomButton = sdkActivated && (hasOngoingConv || ruleAvailable);
  });
}

3️⃣ Opening the Chatbox

When the visitor taps on your custom chat button you should open the Chatbox by calling the following method:

Android

IAdvizeSDK.chatboxController.presentChatbox(context)

⌨️ In-context example: Full custom chat button implementation

iOS

IAdvizeSDK.shared.chatboxController.presentChatbox(
  animated: Bool,
  presentingViewController: UIViewController?
) {
  // ...
}

⌨️ In-context example: Full custom chat button implementation

React Native

IAdvizeSDK.presentChatbox()

Flutter

IAdvizeSdk.presentChatbox();

You can be informed of the Chatbox opening/closing by subscribing to the right listener:

Android

IAdvizeSDK.chatboxController.listeners.add( object : ChatboxListener {
    override fun onChatboxOpened() {
        Log.d("TEST", "Chatbox has opened")
    }

    override fun onChatboxClosed() {
        Log.d("TEST", "Chatbox has closed")
    }
})

iOS

IAdvizeSDK.shared.chatboxController.delegate = self

extension MyApp: ChatboxControllerDelegate {
    public func chatboxDidOpen() {
        print("Chatbox has opened")
    }

    public func chatboxDidClose() {
        print("Chatbox has closed")
    }
}

⌨️ In-context example: Full custom chat button implementation

React Native

IAdvizeSDKListeners.onChatboxOpened(function (eventData: any) {
  console.log('Chatbox has opened');
});

IAdvizeSDKListeners.onChatboxClosed(function (eventData: any) {
  console.log('Chatbox has closed');
});

Flutter

IAdvizeSdk.setChatboxListener();
StreamSubscription _chatboxOpenedSubscription = IAdvizeSdk.onChatboxOpened
    .listen((event) => log('Chatbox has opened'));
StreamSubscription _chatboxClosedSubscription = IAdvizeSdk.onChatboxClosed
    .listen((event) => log('Chatbox has closed'));

🔔 Handling push notifications

Before starting this part you will need to configure push notifications inside your application. You can refer to the following resources if needed:

Android

Firebase Cloud Messaging documentation

iOS

Push notification setup tutorial

React Native

React Native Firebase Setup

React Native Firebase Messaging Setup

Flutter

Flutter Firebase Setup

Flutter Firebase Messaging Setup

You will also need to ensure that the push notifications are setup in your iAdvize project. The process is described in the SDK Knowledge Base.

1️⃣ Registering the device token

For the SDK to be able to send notifications to the visitor’s device, its unique device push token must be registered:

Android

class NotificationService : FirebaseMessagingService() {
  override fun onNewToken(token: String) {
    super.onNewToken(token)
    IAdvizeSDK.notificationController.registerPushToken(token)
  }
}

⌨️ In-context example: Device token register

iOS

IAdvizeSDK.shared.notificationController.registerPushToken("the_device_push_token", applicationMode: .prod)

⌨️ In-context example: Device token register

React Native

import messaging from '@react-native-firebase/messaging';

const registerPushToken = async () => {
  try {
    const token = await messaging().getToken();
    IAdvizeSDK.registerPushToken(token, ApplicationMode.DEV);
    console.log('iAdvize SDK registerPushToken success');
  } catch (e) {
    console.error(e);
  }
};

The ApplicationMode is used only for the iOS application.

Flutter

import 'package:firebase_messaging/firebase_messaging.dart';

FirebaseMessaging.instance.onTokenRefresh.listen((fcmToken) {
  IAdvizeSdk.registerPushToken(pushToken: fcmToken, mode: ApplicationMode.dev);
}).onError((err) {
  log('Error registering token: $err');
});

The ApplicationMode is used only for the iOS application.

2️⃣ Enabling/disabling push notifications

Push notifications are activated as long as you have setup the push notifications information for your app on the iAdvize administration website (process is described in the SDK Knowledge Base). You can manually enable/disable them at any time using:

Android

IAdvizeSDK.notificationController.enablePushNotifications(object : IAdvizeSDK.Callback {
  override fun onSuccess() {
    // Enable succeded
  }
  override fun onFailure(t: Throwable) {
    // Enable failed
  }
})

IAdvizeSDK.notificationController.disablePushNotifications(object : IAdvizeSDK.Callback {
  override fun onSuccess() {
    // Disable succeded
  }
  override fun onFailure(t: Throwable) {
    // Disable failed
  }
})

iOS

IAdvizeSDK.shared.notificationController.enablePushNotifications { success in
  ...
}
    
IAdvizeSDK.shared.notificationController.disablePushNotifications { success in
  ...
}

React Native

try {
  await IAdvizeSDK.enablePushNotifications();
  // Push notifications enabled
} catch (e) {
  // Error enabling push notifications
}

try {
  await IAdvizeSDK.disablePushNotifications();
  // Push notifications disabled
} catch (e) {
  // Error disabling push notifications
}

Flutter

IAdvizeSdk.enablePushNotifications().then((bool success) =>
  log('Push notifications enabled $success'));

IAdvizeSdk.disablePushNotifications().then((bool success) =>
  log('Push notifications disabkled $success'));

3️⃣ Handling push notifications reception

Once setup, you will receive push notifications when the operator sends any message. As the SDK notifications are caught in the same place than your app other notifications, you first have to distinguish if the received notification comes from iAdvize or not.

Android

class NotificationService : FirebaseMessagingService() {
  override fun onMessageReceived(remoteMessage: RemoteMessage) {
    if (IAdvizeSDK.notificationController.isIAdvizePushNotification(remoteMessage.data)) {
      // This is an iAdvize SDK notification
    }
  }
}

iOS

func application(
  _ application: UIApplication,
  didReceiveRemoteNotification userInfo: [AnyHashable: Any],
  fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void
) {
  if IAdvizeSDK.shared.notificationController.isIAdvizePushNotification(with: userInfo) {
    // This is an iAdvize SDK notification
  }
}

React Native

// Firebase Messaging notification handlers

messaging().onMessage(async remoteMessage => {
  console.log('Received a foreground notification message');
  handleNotification(remoteMessage)
});

messaging().setBackgroundMessageHandler(async remoteMessage => {
  console.log('Received a background notification message');
  handleNotification(remoteMessage)
});

function handleNotification(remoteMessage: any) {
  console.log('handling notification', JSON.stringify(remoteMessage));
  var isIAdvizeSDKNotification = IAdvizeSDK.isIAdvizePushNotification(remoteMessage.data)
}

Flutter

// Firebase Messaging notification handlers

@pragma('vm:entry-point')
Future _backgroundNotificationHandler(RemoteMessage message) async {
  log('Received a background notification message ${message}');
  handleNotification(message);
}

FirebaseMessaging.onBackgroundMessage(_backgroundNotificationHandler);

FirebaseMessaging.onMessage.listen((RemoteMessage message) {
  log('Received a foreground notification message ${message}');
  handleNotification(message);
});

void handleNotification(RemoteMessage message) {
  log('handling notification $message');
  IAdvizeSdk.isIAdvizePushNotification(message.data).then(
    (bool isAdvizeNotification) =>
      log('Notification from iAdvize ? $isAdvizeNotification'));
}

Notifications will be received in your app for all messages sent by the agent. It is your responsibility to display the notification and to check whether or not it is relevant to display it. For instance, you don’t need to show a notification to the visitor when the Chatbox is opened

Android

fun shouldDisplayNotification(remoteMessage: RemoteMessage) =
  IAdvizeSDK.notificationController.isIAdvizePushNotification(remoteMessage.data) 
  && !IAdvizeSDK.chatboxController.isChatboxPresented()

iOS

func shouldDisplayNotification(userInfo: [AnyHashable: Any]) -> Bool {
  guard IAdvizeSDK.shared.notificationController.isIAdvizePushNotification(with: userInfo) else {
    return false
  }
  
  guard !IAdvizeSDK.shared.chatboxController.isChatboxPresented() else {
    return false
  }
  
  return true
}

React Native

function handleNotification(remoteMessage: any) {
  console.log('handling notification', JSON.stringify(remoteMessage));

  var chatboxOpened = IAdvizeSDK.isChatboxPresented()
  var isIAdvizeSDKNotification = IAdvizeSDK.isIAdvizePushNotification(remoteMessage.data)
  var shouldDisplay = chatboxOpened == false && isIAdvizeSDKNotification

  console.log("chatboxOpened:", chatboxOpened, "isIAdvizeSDKNotification", isIAdvizeSDKNotification, "shouldDisplay=>", shouldDisplay);
}

Flutter

void handleNotification(RemoteMessage message) {
  log('handling notification $message');

  Future isIAdvizeSDKNotification =IAdvizeSdk.isIAdvizePushNotification(message.data);
  Future isChatboxPresented = IAdvizeSdk.isChatboxPresented();

  Future.wait([isIAdvizeSDKNotification, isChatboxPresented]).then((List flags) {
    bool shouldDisplay = flags[0] && !flags[1];
    log("isIAdvizeSDKNotification:${flags[0]} isChatboxPresented:${flags[1]} shouldDisplay:$shouldDisplay");
  });
}

4️⃣ Customizing the notification

Android

You are responsible for displaying the notification so you can use any title / text / icon you want. The text sent by the agent is available in the content part of the notification data received.

override fun onMessageReceived(remoteMessage: RemoteMessage) {
  if (IAdvizeSDK.notificationController.isIAdvizePushNotification(remoteMessage.data)) {
    val agentMessageReceived = remoteMessage.data["content"] ?: "Default text"
  }
}

⌨️ In-context example: Handling received notification

iOS

By default, the title of the notification is set to the string key iadvize_notification_title. If you want to update/translate this title you can override this value by adding the iadvize_notification_title key in your Localizable.strings file:

"iadvize_notification_title" = "You have received a new message";

React Native

function handleNotification(remoteMessage: any) {
  console.log('handling notification', JSON.stringify(remoteMessage));
  var messageContent = remoteMessage.data.content
}

Flutter

void handleNotification(RemoteMessage message) {
  log('handling notification $message');
  String messageContent = message.data["content"];
}

5️⃣ Clearing push notifications

The iAdvize SDK notifications are automatically cleared from the Notification Tray / Notification Center when the Chatbox is opened. If you want to clear them at any other given time you can call this API:

Android

IAdvizeSDK.notificationController.clearIAdvizePushNotifications()

iOS

IAdvizeSDK.shared.notificationController.clearIAdvizePushNotifications()

React Native

IAdvizeSDK.clearIAdvizePushNotifications()

Flutter

IAdvizeSdk.clearIAdvizePushNotifications()

However, as notifications display depends on the Notification Channel, some configuration is needed in order for this behavior to work correctly:

Android

First of all create the Notification Channel:

IAdvizeSDK.notificationController.createNotificationChannel(context)

Then, when receiving the notification, send it through the SDK Notification Channel if the notification is from iAdvize:

if (IAdvizeSDK.notificationController.isIAdvizePushNotification(remoteMessage.data)) {
  val notification = NotificationCompat.Builder(this, IAdvizeSDK.notificationController.channelId)
    ... // notification config
    .build()
} else {
    // Host app notification handling
}

iOS

On iOS no setup is required, the clearing of the push notificatiosn works out of the box.

React Native

First of all create the Notification Channel:

IAdvizeSDK.createNotificationChannel();

You don't need to check that you are on the Android platform before calling this API, as it does nothing on the iOS platform.

Then, when receiving the notification, send it through the SDK Notification Channel if the notification is from iAdvize. In order to show a notification in a specific Notification Channel, please refer to your Notification library documentation.

Flutter

First of all create the Notification Channel:

IAdvizeSdk.createNotificationChannel();

You don't need to check that you are on the Android platform before calling this API, as it does nothing on the iOS platform.

Then, when receiving the notification, send it through the SDK Notification Channel if the notification is from iAdvize. In order to show a notification in a specific Notification Channel, please refer to your Notification library documentation.

📈 Adding value to the conversation

1️⃣ Registering visitor transactions

You can register a transaction made within your application:

Android

IAdvizeSDK.transactionController.register(
  Transaction(
    "transactionId",
    Date(),
    10.00,
    Currency.EUR
  )
)

iOS

let transaction = Transaction(externalTransactionId: "transactionId", date: Date(), amount: 10.0, currency: .eur)
IAdvizeSDK.shared.transactionController.registerTransaction(transaction)

React Native

const transaction: Transaction = {
  transactionId: 'transactionId',
  currency: 'EUR',
  amount: 10
};
IAdvizeSDK.registerTransaction(transaction);

The currency value should respect ISO 4217.

Flutter

IAdvizeSdk.registerTransaction(Transaction(
  transactionId: 'transactionId',
  currency: 'EUR',
  amount: 10
));

The currency value should respect ISO 4217.

2️⃣ Saving visitor custom data

The iAdvize Messenger SDK allows you to save data related to the visitor conversation:

Android

IAdvizeSDK.visitorController.registerCustomData(listOf(
  CustomData.fromString("Test", "Test"),
  CustomData.fromBoolean("Test2", false),
  CustomData.fromDouble("Test3", 2.0),
  CustomData.fromInt("Test4", 3)
),
object : IAdvizeSDK.Callback {
  override fun onSuccess() {
    // Success
  }
  override fun onFailure(t: Throwable) {
    // Failure
  }
})

iOS

IAdvizeSDK.shared.visitorController.registerCustomData(
  customData:
    ["Test": .customDataString("Test"),
     "Test2": .customDataBoolean(false),
     "Test3": .customDataDouble(2.0),
     "Test4": .customDataInt(3)]
) { success in
    // completion handler
}

React Native

var customData = {
  "Test": "Test",
  "Test2": false,
  "Test3": 2.5,
  "Test4": 3
};
IAdvizeSDK.registerCustomData(customData);

Flutter

List customData = [
  CustomData.fromString("Test", "Test"),
  CustomData.fromBoolean("Test2", false),
  CustomData.fromDouble("Test3", 2.0),
  CustomData.fromInt("Test4", 3)
];
IAdvizeSdk.registerCustomData(customData).then((bool success) =>
    log('iAdvize Example : custom data registered: $success'));

As those data are related to the conversation they cannot be sent if there is no ongoing conversation. Custom data registered before the start of a conversation are stored and the SDK automatically tries to send them when the conversation starts.

The visitor data you registered are displayed in the iAdvize Operator Desk in the conversation sidebar, in a tab labelled Custom data:

Custom data tab shows registered data from the SDK

👍 Fetching visitor satisfaction

The satisfaction survey is automatically sent to the visitor at the end of the conversation, as long as it is activated in the iAdvize administration website. The survey is presented to the visitor in a conversational approach, directly into the Chatbox.

Satisfaction survey

Only the CSAT, NPS and COMMENT steps of the survey are supported.