Gaperon (latest)

🆕 🚨 What's new?

The visitor targeting workflow has been simplified. You do not need to register the visitor navigation anymore.

Thus, the method registerUserNavigation(navigationOption: NavigationOption) is now deprecated.

Now, you manage targeting using only these 2 methods:

To engage the visitor, call activateTargetingRule(targetingRule: TargetingRule) (as you already do).
To stop engaging the visitor, calls deactivateTargetingRule() (this is new).

Between these 2 calls, the iAdvize Mobile SDK automatically updates the targeting rule availability (every 30 seconds) and updates the chat button accordingly. If the update fails (e.g.: if there is no connection), you do not need to perform any special actions. The iAdvize SDK will try to update it again 30 seconds later.

// Activating a new rule.
// - Before:
IAdvizeSDK.targetingController.registerUserNavigation(NavigationOption.ActivateNewRule(yourOtherTargetingRule))
// - After (if there is already a targeting rule activated, it is replaced):
IAdvizeSDK.targetingController.activateTargetingRule(yourOtherTargetingRule)

// Deactivating the rule.
// - Before:
IAdvizeSDK.targetingController.registerUserNavigation(NavigationOption.ClearActiveRule)
// - After:
IAdvizeSDK.targetingController.deactivateTargetingRule()

// Register new screen.
// - Before:
IAdvizeSDK.targetingController.registerUserNavigation(NavigationOption.KeepActiveRule)
// - After:
// Nothing to do.

// Activating a new rule.
// - Before:
IAdvizeSDK.shared.targetingController.registerUserNavigation(navigationOption: .activateNewRule(targetingRule: yourOtherTargetingRule))
// - After (if there is already a targeting rule activated, it is replaced):
IAdvizeSDK.shared.targetingController.activateTargetingRule(targetingRule: yourOtherTargetingRule)

// Deactivating the rule.
// - Before:
IAdvizeSDK.shared.targetingController.registerUserNavigation(navigationOption: .clearActiveRule)
// - After:
IAdvizeSDK.shared.targetingController.deactivateTargetingRule()

// Register new screen.
// - Before:
IAdvizeSDK.shared.targetingController.registerUserNavigation(navigationOption: .keepActiveRule)
// - After:
// Nothing to do.

// Activating a new rule.
// - Before:
IAdvizeSDK.registerUserNavigation(NavigationOption.NEW, targetingRuleUUIDString, channel);
// - After (if there is already a targeting rule activated, it is replaced):
IAdvizeSDK.activateTargetingRule(targetingRuleUUIDString, channel)

// Deactivating the rule.
// - Before:
IAdvizeSDK.registerUserNavigation(NavigationOption.CLEAR, "", "");
// - After:
IAdvizeSDK.deactivateTargetingRule()

// Register new screen.
// - Before:
IAdvizeSDK.registerUserNavigation(NavigationOption.KEEP, "", "");
// - After:
// Nothing to do.

// Activating a new rule.
// - Before:
IAdvizeSdk.registerUserNavigation(
  navigationOption: NavigationOption.optionNew,
  newTargetingRule: TargetingRule(uuid: targetingRuleUUIDString, channel: channel)
);
// - After (if there is already a targeting rule activated, it is replaced):
IAdvizeSdk.activateTargetingRule(TargetingRule(uuid: targetingRuleUUIDString, channel: channel));

// Deactivating the rule.
// - Before:
IAdvizeSdk.registerUserNavigation(navigationOption: NavigationOption.optionClear);
// - After:
IAdvizeSDK.deactivateTargetingRule();

// Register new screen.
// - Before:
IAdvizeSdk.registerUserNavigation(navigationOption: NavigationOption.optionKeep);
// - After:
// Nothing to do.

⚙️ Prerequisites

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

💬 Setting up your iAdvize environment

Before integrating the Mobile 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 Mobile SDK). You will also need some information related to the project for the Mobile SDK setup. Please ask your iAdvize administrator to follow the instructions available on the Mobile 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.

🎯 Understanding Mobile SDK: triggers & targeting

Key differences: Mobile SDK vs Web

Web:

iAdvize automatically detects visitor behavior
Targeting rules include criteria (URL patterns, visitor segments, timing conditions)
Triggers fire automatically based on Admin configuration

Mobile SDK:

YOU implement ALL trigger detection logic in your app code
Targeting rules are routing identifiers ONLY (no criteria, no automatic triggering)
The Mobile SDK provides the conversation infrastructure, not behavior detection

What the Mobile SDK provides vs what you should implement

✅ Mobile SDK provides:

activateTargetingRule(uuid) - Shows chat button if operator/bot available
deactivateTargetingRule() - Hides chat button
Automatic 30-second availability checks
Conversation interface and message handling

❌ You must implement:

Detecting user behavior (idle time, scroll events, button taps, navigation)
Implementing business rules (show after 10s on product page, hide on checkout, etc.)
Frequency control (max 1x per session, cooldown periods)
Session tracking and visitor preferences
Deciding WHEN to call activateTargetingRule()

Example architecture

YOUR APP detects: "User idle 8 seconds on homepage"
YOUR APP decides: "Show chat button" (checks frequency cap, user preferences)
YOUR APP calls: activateTargetingRule("homepage-uuid")
Mobile SDK checks: Operator/bot available?
Mobile SDK shows: Chat button (if available)

💻 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:

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 Mobile SDK integrity

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

Reference checksums are available:

in the GitHub release note
in the dedicated spreadsheet

The iAdvize 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 Mobile SDK sub-dependencies is delivered alongside the Mobile SDK. Those subdependencies checksums have been generated through the Gradle generation feature and not verified.

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 iAdvize 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

⚙️ Setting up the Mobile SDK

1️⃣ Setting up the Mobile SDK into your project configuration

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

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.githubusercontent.com/iadvize/iadvize-android-sdk/master"))
    maven(url = uri("https://jitpack.io"))
  }
}

Add the iAdvize Mobile 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 Mobile 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.

If you have build problems this may come from compatibility issues with the Android configuration, here are the versions used by the iAdvize Mobile SDK:

Target SDK

35

Compile SDK

35

Minimum SDK

24

Build Tools

35.0.0

Kotlin

2.1.10

Gradle

8.13

Android Gradle Plugin

8.9.0

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:

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.

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

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:

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>

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';

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 Mobile SDK is built with Android target 35):

// android/build.gradle

buildscript {
  ext {
    buildToolsVersion = "35.0.0"
    minSdkVersion = 24
    compileSdkVersion = 35
    targetSdkVersion = 35
    kotlinVersion = "2.1.10"
    gradleVersion = "8.9.0"
    ndkVersion = "29.0.13113456"
  }
}

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

iAdvize Mobile SDK requires a minSdkVersion >= 24.

On Android, the iAdvize Mobile 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);
   }
}

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):

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

iAdvize Mobile SDK requires a minimum iOS platform of 13.4

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>

Download the SDK as well as the expo-build-properties library from NPM using the following command:

npx expo install expo-build-properties
npx expo install @iadvize-oss/iadvize-react-native-sdk

Configure the build properties using expo-build-properties in the app.json file:

{
  "expo": {
    ...

    "ios": {
      ...

      "infoPlist": {
        "NSCameraUsageDescription": "This application will use the camera to share photos and during video calls.",
        "NSMicrophoneUsageDescription": "This application will use the microphone during video calls."
      }
    },
    "plugins": [
      ...

      [
        "expo-build-properties",
        {
          "android": {
            "compileSdkVersion": 35,
            "targetSdkVersion": 35,
            "buildToolsVersion": "35.0.0",
            "minSdkVersion": 24
          },
          "ios": {
            "deploymentTarget": "15.1"
          }
        }
      ],
      "./iadvize.config.js"
    ],
    ...
  }
}

For that step you will need to download the iAdvize Mobile SDK Expo Plugin configuration file and save it alongside the app.json file of your project.

Afterwards you can generate the native code using the traditional Expo command:

npx expo prebuild --clean

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';

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

// android/build.gradle

allprojects {
  repositories {
    maven { url "https://raw.githubusercontent.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 35), 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

allprojects {
  ext {
    buildToolsVersion = "35.0.0"
    minSdkVersion = 24
    compileSdkVersion = 35
    targetSdkVersion = 35
    kotlinVersion = "2.1.10"
    gradleVersion = "8.9.0"
    ndkVersion = "29.0.13113456"
  }
}

iAdvize Messenger SDK requires a minSdkVersion >= 24.

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.4'

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

iAdvize Messenger SDK requires a minimum iOS platform of 13.4

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 Mobile SDK

Now that the Mobile 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 visitor into the iAdvize flow.

You can choose between multiple authentication options:

Anonymous

For an unidentified visitor browsing your app.

Simple

For a logged in visitor 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 visitor.

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 Mobile SDK. For a full understanding of how the secured authentication works in the iAdvize platform you can refer to this section.

To activate the Mobile 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 a Mobile SDK activation failure the callback will give you the reason of the failure and you may want to retry later.

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(error: IAdvizeSDK.Error) {
      Log.e("iAdvize SDK", "The SDK activation failed with:", error)
    }
  }
)

⌨️ In-context example: SDK Activation

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

⌨️ In-context example: SDK Activation

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
}

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 Mobile 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 visitor out

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

IAdvizeSDK.logout()

4️⃣ Displaying logs

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

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

You can get a description of the Mobile SDK status at any time by using the debugInfo API:

IAdvizeSDK.debugInfo()

This will generate a JSON object with the Mobile SDK status information, encoded into a string that you can easily add into your bug reporting tool payload:

{
  "targeting": {
    "screenId": "67BA3181-EBE2-4F05-B4F3-ECB07A62FA92",
    "activeTargetingRule": {
      "id": "D8821AD6-E0A2-4CB9-BF45-B2D8A3CF4F8D",
      "conversationChannel": "chat"
    },
    "isActiveTargetingRuleAvailable": false,
    "currentLanguage": "en"
  },
  "device": {
    "model": "iPhone",
    "osVersion": "17.5",
    "os": "iOS"
  },
  "ongoingConversation": {
    "conversationChannel": "chat",
    "conversationId": "02012815-4BDA-42EF-87DC-5C6ED317AF7F"
  },
  "chatbox": {
    "useDefaultFloatingButton": true,
    "isChatboxPresented": false
  },
  "activation": {
    "activationStatus": "activated",
    "authenticationMode": "simple",
    "projectId": "7260"
  },
  "connectivity": {
    "wifi": true,
    "isReachable": true,
    "cellular": false
  },
  "visitor": {
    "vuid": "d4a57969c7fc4e2a9380f3931fdcee3a965650eb9c6b4",
    "tokenExpiration": "2025-02-27T08:14:11Z"
  },
  "sdkVersion": "2.15.4"
}

💬 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 visitor’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 visitor’s device current language. You can force the targeting language to a specific value using:

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

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

What is a targeting rule in Mobile SDK?

Unlike web targeting rules (which include criteria and automatic triggering), Mobile SDK targeting rules are routing identifiers only:

❌ No behavioral criteria (URL patterns, dwell time, scroll depth)

❌ No automatic triggering based on visitor behavior

✅ Routes conversations to specific routing rules/teams/bots

✅ Checks operator/bot availability

Your responsibility:

Detect user behavior in your app (navigation, idle time, button taps)
Implement business logic for WHEN to activate rules
Call activateTargetingRule() when YOUR conditions are met

SDK responsibility:

Check if operator/bot is available for this targeting rule
Show/hide chat button based on availability
Update availability every 30 seconds

Best practice: Create one targeting rule per app context:

Homepage → activateTargetingRule("homepage-uuid")
Product page → activateTargetingRule("pdp-uuid")
Cart → activateTargetingRule("cart-uuid")

Each rule can route to different teams/bots while you control the triggering logic.

See Understanding Mobile SDK: triggers and targeting for architecture details.

Calling activateTargetingRule

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

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

⌨️ In-context example: Targeting rule activation

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

⌨️ In-context example: Targeting rule activation

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 Mobile SDK matches the language configured for this rule
an operator/bot assigned to this rule is available to answer (connected and with a free chat slot)

After you activate a rule, those conditions are automatically re-evaluated every 30 seconds. The chat button is updated accordingly.

If the update fails (e.g.: if there is no connection), you do not need to perform any special actions. The iAdvize Mobile SDK will try to update it again 30 seconds later.

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.

While your visitor navigates through your app, you may want to update the active targeting rule in order to engage him/her with the best conversation partner at any time. To do so, simply activate the new rule. It will replace the previous one.

val newTargetingRule = TargetingRule(
    newTargetingRuleUUID,
    ConversationChannel.CHAT // or ConversationChannel.VIDEO
)
IAdvizeSDK.targetingController.activateTargetingRule(newTargetingRule)

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

5️⃣ Deactivating a targeting rule

When you do not want to engage the visitor anymore, simply deactivate the targeting rule.

IAdvizeSDK.targetingController.deactivateTargetingRule()

The current targeting rule is automatically deactivated when you call the logout() method.

6️⃣ Frequency control & proactive messaging limitations

Reactive-only nature

The Mobile SDK is reactive-only:

✅ Visitor must tap the chat button to start a conversation
❌ Cannot push messages to trigger conversation start
✅ Push notifications work for ongoing conversations (operator/bot replies)
❌ Cannot proactively message visitors to initiate conversation

While workflows/AI Shopping Assistant can "proactively" greet and guide visitors WITHIN a conversation, the visitor must first open the chatbox.

Frequency capping

The Mobile SDK does NOT provide built-in frequency control.

Track locally:

How many times activateTargetingRule() is called per session/day
Cooldown periods (don't show for X hours after dismissal)
Visitor preferences ("don't show again")

Analytics for optimization

While the SDK doesn't control frequency, iAdvize tracks metrics for analysis:

TARGETING_RULE_DISPLAY_NUMBER - Button display count
TARGETING_RULE_TRIGGERED - Conversation start count

Access via GraphQL API - Pre-aggregated Indicators for historical analysis and optimization (not real-time control).

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.

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

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

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

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:

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:

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

provide an URL pointing to your GPDR policy, it will be opened on visitor click
provide a listener/delegate that will be called on visitor 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 Mobile SDK without the GDPR process. However, be careful to explicitly mention the iAdvize Chat part in your GDPR consent details.

// 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:

// 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:

// 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 visitor 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.

const configuration: ChatboxConfiguration = {
  automaticMessage: 'Hello! Please ask your question :)',
  gdprMessage: 'Your own custom GDPR message.'
};
IAdvizeSDK.setChatboxConfiguration(configuration)

// 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:

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

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.

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

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

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

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

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

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

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...

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)

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)

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)

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.

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)

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)

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.

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.

5️⃣ Presenting a smaller Chatbox

The Chatbox can be presented in a compact mode.

The visitor can then expand the chatbox manually. The chatbox is automatically expanded when the keyboard opens. This compact mode can be enabled by using a flag in the ChatboxConfiguration.

val configuration = ChatboxConfiguration()
configuration.smallerChatboxEnabled = true // Default is false
IAdvizeSDK.chatboxController.setupChatbox(configuration)

🎨 Branding the Default Floating Button

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

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

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)

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);

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 visitor to chat
hide/show the button following the active targeting rule availability and the ongoing conversation status
open the Chatbox when the visitor presses your button

1️⃣ Disabling the Default Floating Button

IAdvizeSDK.defaultFloatingButtonController.setupDefaultFloatingButton(DefaultFloatingButtonOption.Disabled)

2️⃣ Displaying/hiding the chat button

Understanding availability callbacks

These listeners notify you when:

Targeting rule availability changes (operator/bot becomes available/unavailable)
Availability update fails
Conversation status changes

⚠️ Important distinction:

Availability callbacks (from Mobile SDK) tell you:

"Is an operator/bot available for this targeting rule right now?"

Your business logic (in your app) determines:

"Should I show the chat button based on user behavior, frequency caps, preferences?"

Combined decision logic

To show/hide your custom button, combine BOTH:

✅ Your conditions met? (user behavior, frequency, preferences)
✅ Mobile SDK availability = true? (operator/bot available)
→ Result: Show button only if BOTH are true

Implementing the visibility logic

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:

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

    // You may launch the targeting again based on the error type
  }
})

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
  }
})

extension IntegrationApp: TargetingControllerDelegate {
  func activeTargetingRuleAvailabilityDidUpdate(isActiveTargetingRuleAvailable: Bool) {
    // SDK active rule availability changed to isActiveTargetingRuleAvailable
    updateChatButtonVisibility()
  }
  func activeTargetingRuleDidFailToUpdate(error: TargetingError) {
   // SDK active rule availability failed
    updateChatButtonVisibility()

    // You may launch the targeting again based on the error type
  }
}
    
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
}

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

IAdvizeSDKListeners.onActiveTargetingRuleAvailabilityUpdateFailed(function (eventData: any) {
   // SDK active rule availability failed
    updateChatButtonVisibility()

    // You may launch the targeting again based on the error type
});

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

IAdvizeSdk.setConversationListener(manageUrlClick: true);
IAdvizeSdk.onOngoingConversationUpdated.listen((bool ongoing) {
  // SDK ongoing conversation status changed
  _updateCustomChatButtonVisibility();
});

IAdvizeSdk.setOnActiveTargetingRuleAvailabilityListener();
IAdvizeSdk.onActiveTargetingRuleAvailabilityUpdated.listen((bool available) {
  // SDK active rule availability changed
  _updateCustomChatButtonVisibility();
});
IAdvizeSdk.onActiveTargetingRuleAvailabilityUpdateFailed.listen((Map<String, String> error) {
   // SDK active rule availability failed
   updateChatButtonVisibility()

   // You may launch the targeting again based on the error type
});

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

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()
  }
}

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()
}

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()
  }
};

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:

IAdvizeSDK.chatboxController.presentChatbox(context)

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

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

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

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

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

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

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

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

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

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:

Firebase Cloud Messaging documentation

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

1️⃣ Registering the device token

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

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

⌨️ In-context example: Device token register

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.

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 during Mobile SDK activation, 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:

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

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

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
}

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.

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

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
  }
}

// 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)
}

// 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

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

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
}

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);
}

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/localizing the notification

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

Our SDK uses APNs localization keys so iOS fetches the translated title from your app’s localization resources.

Key used by the SDK

iadvize_notification_title — shown when a new message arrives
Recommended English value: “You have received a new message”

What you need to do

Add the key to your app’s localization files
Use a String Catalog (Localizable.xcstrings) or a classic Localizable.strings.
Ensure the resource is included in your app target.
Provide translations for every language your app supports

English

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

French

"iadvize_notification_title" = "Vous avez reçu un nouveau message";

Why this is required

When APNs payloads use title-loc-key, iOS resolves the key only against the app’s main bundle. Even though the SDK ships its own translations, notification title must exist in your app bundle so the system can find it. If a translation is missing for a given locale, iOS will fall back using your app’s standard localization rules (e.g., your development region).

Translation suggestions

Here are translations you can use if your app supports some of these languages.

Code

Language

iadvize_notification_title

cs

Czech

Dostali jste novou zprávu

da

Danish

Du har modtaget en ny besked

de

German

Sie haben eine neue Nachricht erhalten

en

English

You have received a new message

es

Spanish

Has recibido un nuevo mensaje

fr

French

Vous avez reçu un nouveau message

it

Italian

Hai ricevuto un nuovo messaggio

lt

Lithuanian

Jūs gavote naują žinutę

nl

Dutch

U hebt een nieuw bericht ontvangen

pl

Polish

Otrzymałeś nową wiadomość

pt

Portuguese

Recebeu uma nova mensagem

sk

Slovak

Dostali ste novú správu

sv

Swedish

Du har fått ett nytt meddelande

5️⃣ Clearing push notifications

The iAdvize Mobile 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:

IAdvizeSDK.notificationController.clearIAdvizePushNotifications()

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

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
}

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.

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.

📈 Adding value to the conversation

1️⃣ Registering visitor transactions

You can register a transaction made within your application:

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

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

The currency value should respect ISO 4217.

2️⃣ Saving visitor custom data

How custom data is used

Custom data you register:

Operators: See values in "Custom data" sidebar tab
Workflows/AI Shopping Assistant: Use values as context parameters (e.g., productId to fetch product info)
Visitors: Don't see raw values in chatbox

See Using custom data with workflows & AI Shopping Assistant for examples.

Example

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

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(error: IAdvizeSDK.Error) {
    // Failure
  }
})

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

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 Mobile 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:

3️⃣ Using custom data with workflows & AI Shopping Assistant

Custom data you register is:

✅ Visible to operators - Displayed in "Custom data" tab in operator desk
✅ Usable by workflows/AI Shopping Assistant - Passed as contextual parameters to retrieve information
❌ Not shown to visitors - Raw values don't appear in chatbox

How workflows and/or AI Shopping Assistant use custom data

The AI Shopping Assistant and workflows can use custom data (like productId) as context to retrieve relevant information from your configured knowledge sources.

Example: Product Context on PDP

// Register product ID when visitor views product page
IAdvizeSDK.visitorController.registerCustomData(
    CustomData("productId", "SKU-12345"),
    CustomData("productName", "Garden Hose 50ft"),
    CustomData("productCategory", "Gardening")
)

When a conversation starts:

The operator sees: productId = SKU-12345, productName = Garden Hose 50ft
The AI Shopping Assistant uses productId to query your product catalog (if configured in knowledge sources)
The bot can answer product-specific questions without the visitor repeating information

Important: The bot doesn't display raw custom data values to visitors. It uses them as lookup parameters to retrieve relevant information from your configured knowledge sources.

Channel-agnostic workflows/AI Shopping Assistant behavior

Workflows/AI Shopping Assistant configuration in iAdvize Admin works identically across:

Web
Mobile App (Mobile SDK)
Social/Messaging channels

The Mobile SDK provides the conversation interface; the workflows/AI Shopping Assistant intelligence and behavior are configured in iAdvize Admin and remain consistent across all channels.

Use cases

Product pages: pass productId for product-specific assistance
Cart: pass cart contents for contextual recommendations
Order tracking: pass orderId for WISMO (Where Is My Order) workflows
Category pages: pass category info for relevant suggestions

Learn more about AI Shopping Assistant configuration: documentation

👍 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.

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

📊 Analytics & Monitoring

iAdvize Admin dashboard

Filter mobile conversations in Reports:

By targeting rule: Name rules clearly ("Mobile - Homepage", "Mobile - PDP")
By routing rule: Track performance per team/bot
Standard metrics: Conversations, response time, CSAT, NPS

Limitation: Cannot differentiate iOS vs Android (both show as "Mobile App" channel)

Advanced Analytics: GraphQL API

For detailed metrics and historical analysis:

TARGETING_RULE_DISPLAY_NUMBER - How often chat button was displayed
TARGETING_RULE_TRIGGERED - How often conversations started
Pre-aggregated indicators for periodic exports

Documentation: Retrieve Messages & Pre-aggregated Indicators

⚠️ Note: These are historical/reporting metrics, not available in real-time for app logic.

App-side analytics

The Mobile SDK does NOT track or report:

When/why you call activateTargetingRule()
User behavior that leads to trigger activation
Frequency of button displays per visitor
Session tracking and user preferences

You must instrument these in your analytics platform (Google Analytics, Firebase, Mixpanel, etc.) for:

Trigger effectiveness analysis
A/B testing trigger strategies
User engagement patterns
Conversion funnel tracking

PreviousMobile SDK NextFourme

Last updated 1 day ago

hashtag🆕 🚨 What's new?

hashtag⚙️ Prerequisites

hashtag💬 Setting up your iAdvize environment

hashtag🎯 Understanding Mobile SDK: triggers & targeting

hashtagKey differences: Mobile SDK vs Web

hashtagWhat the Mobile SDK provides vs what you should implement

hashtagExample architecture

hashtag💻 Connecting to your iAdvize Operator Desk

hashtag🔐 Ensuring the Mobile SDK integrity

hashtag⚙️ Setting up the Mobile SDK

hashtag1️⃣ Setting up the Mobile SDK into your project configuration

hashtag2️⃣ Activating the Mobile SDK

hashtag3️⃣ Logging the visitor out

hashtag4️⃣ Displaying logs

hashtag💬 Starting a conversation

hashtag1️⃣ Configuring the targeting language

hashtag2️⃣ Activating a targeting rule

hashtagWhat is a targeting rule in Mobile SDK?

hashtagCalling activateTargetingRule

hashtag3️⃣ Initiating the conversation

hashtag4️⃣ Following visitor navigation

hashtag5️⃣ Deactivating a targeting rule

hashtag6️⃣ Frequency control & proactive messaging limitations

hashtagReactive-only nature

hashtagFrequency capping

hashtagAnalytics for optimization

hashtag👋 Configuring GDPR and welcome message

hashtag1️⃣ Adding a welcome message

hashtag2️⃣ Enabling GDPR approval

hashtag🎨 Branding the Chatbox

hashtag1️⃣ Updating the font

hashtag2️⃣ Styling the navigation bar

hashtag3️⃣ Changing the Chatbox colors

hashtag4️⃣ Using a brand avatar

hashtag5️⃣ Presenting a smaller Chatbox

hashtag🎨 Branding the Default Floating Button

hashtag✨ Using a custom chat button

hashtag1️⃣ Disabling the Default Floating Button

hashtag2️⃣ Displaying/hiding the chat button

hashtagUnderstanding availability callbacks

hashtagImplementing the visibility logic

hashtag3️⃣ Opening the Chatbox

hashtag🔔 Handling push notifications

hashtag1️⃣ Registering the device token

hashtag2️⃣ Enabling/disabling push notifications

hashtag3️⃣ Handling push notifications reception

hashtag4️⃣ Customizing/localizing the notification

hashtag5️⃣ Clearing push notifications

hashtag📈 Adding value to the conversation

hashtag1️⃣ Registering visitor transactions

hashtag2️⃣ Saving visitor custom data

hashtagHow custom data is used

hashtagExample

hashtag3️⃣ Using custom data with workflows & AI Shopping Assistant

hashtagHow workflows and/or AI Shopping Assistant use custom data

hashtagChannel-agnostic workflows/AI Shopping Assistant behavior

hashtagUse cases

hashtag👍 Fetching visitor satisfaction

hashtag📊 Analytics & Monitoring

hashtagiAdvize Admin dashboard

hashtagAdvanced Analytics: GraphQL API

hashtagApp-side analytics

🆕 🚨 What's new?

⚙️ Prerequisites

💬 Setting up your iAdvize environment

🎯 Understanding Mobile SDK: triggers & targeting

Key differences: Mobile SDK vs Web

What the Mobile SDK provides vs what you should implement

Example architecture

💻 Connecting to your iAdvize Operator Desk

🔐 Ensuring the Mobile SDK integrity

⚙️ Setting up the Mobile SDK

1️⃣ Setting up the Mobile SDK into your project configuration

2️⃣ Activating the Mobile SDK

3️⃣ Logging the visitor out

4️⃣ Displaying logs

💬 Starting a conversation

1️⃣ Configuring the targeting language

2️⃣ Activating a targeting rule

What is a targeting rule in Mobile SDK?

Calling activateTargetingRule

3️⃣ Initiating the conversation

4️⃣ Following visitor navigation

5️⃣ Deactivating a targeting rule

6️⃣ Frequency control & proactive messaging limitations

Reactive-only nature

Frequency capping

Analytics for optimization

👋 Configuring GDPR and welcome message

1️⃣ Adding a welcome message

2️⃣ Enabling GDPR approval

🎨 Branding the Chatbox

1️⃣ Updating the font

2️⃣ Styling the navigation bar

3️⃣ Changing the Chatbox colors

4️⃣ Using a brand avatar

5️⃣ Presenting a smaller Chatbox

🎨 Branding the Default Floating Button

✨ Using a custom chat button

1️⃣ Disabling the Default Floating Button

2️⃣ Displaying/hiding the chat button

Understanding availability callbacks

Implementing the visibility logic

3️⃣ Opening the Chatbox

🔔 Handling push notifications

1️⃣ Registering the device token

2️⃣ Enabling/disabling push notifications

3️⃣ Handling push notifications reception

4️⃣ Customizing/localizing the notification

5️⃣ Clearing push notifications

📈 Adding value to the conversation

1️⃣ Registering visitor transactions

2️⃣ Saving visitor custom data

How custom data is used

Example

3️⃣ Using custom data with workflows & AI Shopping Assistant

How workflows and/or AI Shopping Assistant use custom data

Channel-agnostic workflows/AI Shopping Assistant behavior

Use cases

👍 Fetching visitor satisfaction

📊 Analytics & Monitoring

iAdvize Admin dashboard

Advanced Analytics: GraphQL API

App-side analytics