Android SDK

You can get the latest version from here.

Integrating the Mobile SDK

Add this dependency to your project build.gradle at the end of the repository:

KTS

KOTLIN

allprojects {
   repositories {
       maven (url = uri("https://jitpack.io"))
   }
}

Groovy

GROOVY

allprojects {
   repositories {
      maven {
         url 'https://jitpack.io'
      }
   }
}

Add the dependency:

KTS

KOTLIN

dependencies {
   implementation ("com.github.Teavaro:FunnelConnect-Mobile-SDK:LATEST_VERSION") {
            // Only add this if you are using Teavaro SDK with Utiq SDK
            exclude("com.github.Teavaro.FunnelConnect-Mobile-SDK", "core-android")
   }
}

Groovy

GROOVY

dependencies {
   implementation 'com.github.Teavaro:FunnelConnect-Mobile-SDK:LATEST_VERSION' {
            // Only add this if you are using Teavaro SDK with Utiq SDK
            exclude group: "com.github.Teavaro.FunnelConnect-Mobile-SDK",  module: "core-android"
   }
}

Also, add the following permissions to your manifest file

CODE

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

The minSdkVersion version number in your build.gradle should not be less than 21.

Initializing the Mobile SDK

Basic Initialization

Assuming that you have an Application class registered in the AndroidManifest.xml file, you can call the initialize function inside onCreate(), passing the application context and the SDK token that you will get from us.

KOTLIN

FunnelConnectSDK.initialize(this, SDK_TOKEN)

JAVA

FunnelConnectSDK.initialize(this, SDK_TOKEN);

Please email us for a new token and a config file for your mobile App.

Initializing with Custom Options

FCOptions() is an optional initialization parameter, so you can initialize the SDK without passing it, but in case there are options that you want to enable or disable specifically, this can be done by enabling or disabling the options in the FCOptions and passing it to the initializer.

Currently, enable debugging is the only available option, but there will be more in the future..

KOTLIN

val fallbackConfigJson : String = "{ /* fallbackConfigJson */ }"
val options = FCOptions().enableLogging().setFallBackConfigJson(fallbackConfigJson)
FunnelConnectSDK.initialize(this, SDK_TOKEN, options)

JAVA

String fallbackConfigJson = "{ /* fallbackConfigJson */ }";
FCOptions options = new FCOptions().enableLogging().setFallBackConfigJson(fallbackConfigJson);
FunnelConnectSDK.initialize(this, SDK_TOKEN, options);

Check if the SDK is initialized

At some point, you might want to check if the SDK is initialized before doing anything else.

Boolean check

KOTLIN

FunnelConnectSDK.isInitialized()

JAVA

FunnelConnectSDK.isInitialized();

onInitialize listener

KOTLIN

FunnelConnectSDK.onInitialize({
   // Success Action
}) {
   // Failure Action
}

JAVA

FunnelConnectSDK.onInitialize(() -> {
       // Success Action
}, error -> {
       // Failure Action
});

You would need to do this if you want to do something with the SDK very early (for example in the splash screen) and you want to make sure that the SDK is initialized before doing anything with the SDK, however if you will use the SDK functions in a class that will require going through multiple steps, such as the cart page in an e-commerce app, most probably you won’t need to use this function because the SDK will be already initialized by the time of reaching to that page or class, so it is your call to decide when to use that check and when not to.

Clear Cache

Cached data and cookies can be cleared easily using the following functions.

KOTLIN

FunnelConnectSDK.clearData()
FunnelConnectSDK.clearCookies()

JAVA

FunnelConnectSDK.clearData();
FunnelConnectSDK.clearCookies();

Basic Usage

Once the SDK is initialized, all the service functions can be accessed by calling FunnelConnectSDK.

Integration

Consent Management

The consent management API handles consent notification acknowledgement and permission preferences. The information is stored against the user’s profile, which can be a site or an app visitor or authenticated customer profile. The API provides access to the profile data and allows updates, including:

Set or update permissions.
Capture consent notification acknowledgement (using alert dialog or action sheet) including version history.

Start Service

The start service function is available with different overloads, for example, you may want to start the service as a guest user:

KOTLIN

FunnelConnectSDK.startService()

JAVA

FunnelConnectSDK.startService(null, 1, null, null);

You can also start the service as a guest user, but with success and failure callbacks:

KOTLIN

FunnelConnectSDK.startService(dataCallback = {
    val response = JSONObject(it)
    if (response.has("umid")) {
        println(response.getString("umid"))
    }
}, errorCallback = {
       error.printStackTrace()
})

JAVA

FunnelConnectSDK.startService(null, , NOTIFICATION_NAME, 1, data -> {
    try {
            JSONObject response = new JSONObject(data);
            if (response.has("umid")) {
                System.out.println(response.getString("umid"));
            }
     }
    catch (Exception exception) {
            exception.printStackTrace();
    }
}, error -> {
    error.printStackTrace();
});

And in case you need to pass a specific notification version with or without success and failure callbacks, you can do this:

KOTLIN

FunnelConnectSDK.startService(notificationsName = NOTIFICATION_NAME, notificationsVersion = -1)

JAVA

FunnelConnectSDK.startService(null,  NOTIFICATION_NAME, 1, null, null);

With callbacks

KOTLIN

FunnelConnectSDK.startService(notificationsName = NOTIFICATION_NAME, notificationsVersion = -1, dataCallback = { ... }, errorCallback = { ... })

CODE

FunnelConnectSDK.startService(null, NOTIFICATION_NAME, 1, data -> { ... }, error -> { ... });

The notifications name and version version are defined in the API pipeline configuration as per requirements, If the request data does not match the pipeline configuration, a 400 HTTP response is returned.

The default notifications version is 1 if not passed, but you can pass the desired notifications version, or you can pass -1 if you don’t wish to send the notifications element at all.

You can pass a single user object or array of user objects if you want to set multiple user identifiers such as email and device id to start the service as an identified user:
Single user object

KOTLIN

FunnelConnectSDK.startService(FCUser("email", "mail@domain.com"))

JAVA

FunnelConnectSDK.startService(new FCUser("email", "mail@domain.com"));

Array of user objects

KOTLIN

FunnelConnectSDK.startService(listOf(FCUser("email", "mail@domain.com"), FCUser("gaid", "3eb0e1b9-0cac-449e-82fd-bff5485c3ed7")))

JAVA

List<FCUser> fcUsers = new ArrayList<>();
fcUsers.add(new FCUser("email", "mail@domain.com"));
fcUsers.add(new FCUser("gaid", "3eb0e1b9-0cac-449e-82fd-bff5485c3ed7"));
FunnelConnectSDK.startService(fcUsers);

You can use the same overloads that are available for guest users.

If you are using the start function with data callback, this is a sample of the expected data that returns inside the dataCallback.

JSON

{
"umid": "4ad2c29dddb3abae2b45bb4399740792f7aabd32d33acc10b9566be23d0892ae",
"state": 1,
"permissions": {},
"permissionsLastModification": {},
"notificationHistory": [],
"notificationStatus": {},
"attributes": {
        "segment-1": "XXX",
        "segment-2": "yyy",
        "segment-3": "zzz",
        "deviceName": "OT",
        "city": "City",
        "isp": "Telco Operator",
        "domainName": "domain.com",
        "browserType": "LI",
        "region": "Region",
        "mobileBrand": "Mobile Brand",
        "cc": "GB",
        "osFamily": "",
        "browserFamily": "cURL"
    }
}

Once the startService is invoked, the JSON response will be stored locally, and you can access it at any time by calling startService function again.

The following parameters can be extracted from the data response:

Parameter	Description
`umid`	Unified Marketing ID in UUID format, distinct to a user.
`state`	Indicates if the profile belongs to a visitor (`0`) or customer (`1`).
`permissions`	Returns the chosen permission preferences.
`permissionsLastModification`	Returns the date of the last permission preferences update
`notificationHistory`	Returns an array of objects of all acknowledged consent notifications with distinct version.
`notificationStatus`	Shows permissions for which a notification has been acknowledged

All the SDK functions should be used after the startService function has been called, otherwise, you will get empty or null values.

Set User ID

If you started the service as a guest user or Identified user, you still can set or update the user ID at anytime.

KOTLIN

FunnelConnectSDK.setUser(FCUser("email", "mail@domain.com"))

JAVA

FunnelConnectSDK.setUser(new FCUser("email", "mail@domain.com"), null, null);

You can also set or update the user ID but with success and failure callbacks.

KOTLIN

FunnelConnectSDK.setUser(FCUser("email", "mail@domain.com"), dataCallback = {}, errorCallback = {})

JAVA

FunnelConnectSDK.setUser(new FCUser("email", "mail@domain.com"), data -> {}, error -> {});

Set Multiple User IDs

You can also set or update multiple user IDs.

KOTLIN

FunnelConnectSDK.setUsers(listOf(FCUser("email", "mail@domain.com"), FCUser("gaid", "3eb0e1b9-0cac-449e-82fd-bff5485c3ed7")))

JAVA

List<FCUser> fcUsers = new ArrayList<>();
fcUsers.add(new FCUser("email", "mail@domain.com"));
fcUsers.add(new FCUser("gaid", "3eb0e1b9-0cac-449e-82fd-bff5485c3ed7"));
FunnelConnectSDK.setUsers(fcUsers);

You can also set or update the user ID but with success and failure callbacks.

KOTLIN

FunnelConnectSDK.setUsers(listOf(FCUser("email", "mail@domain.com"), FCUser("gaid", "3eb0e1b9-0cac-449e-82fd-bff5485c3ed7")), dataCallback = {}, errorCallback = {})

JAVA

List<FCUser> fcUsers = new ArrayList<>();
fcUsers.add(new FCUser("email", "mail@domain.com"));
fcUsers.add(new FCUser("gaid", "3eb0e1b9-0cac-449e-82fd-bff5485c3ed7"));
FunnelConnectSDK.setUsers(fcUsers);

Get Saved User ID(s)

You can get single or multiple saved user ID(s) if set before:

KOTLIN

FunnelConnectSDK.getUsers()
OR
FunnelConnectSDK.getUserIdByKey("email")

JAVA

FunnelConnectSDK.getPermissions();
FunnelConnectSDK.getUserIdByKey("email");

Set or Update Permissions

The permissions can be set or updated by creating Permissions object, then pass permission name and value of type boolean indicating that it is accepted or rejected.

The permissions are defined in the API pipeline configuration as per requirements, If the request data does not match the pipeline configuration a 400 HTTP response is returned.

You can pass -1 to the notificationsVersion parameter if you don’t wish to send the notifications element at all.

KOTLIN

PermissionsMap().apply {
    addPermission("OM", true)
    addPermission("NBA", false)
}.let { 
    FunnelConnectSDK.updatePermissions(it, NOTIFICATION_NAME, 1)
}

JAVA

PermissionsMap permissionsMap = new PermissionsMap();
permissionsMap.addPermission("OM", true);
permissionsMap.addPermission("NBA", false);
FunnelConnectSDK.updatePermissions(permissionsMap, NOTIFICATION_NAME, 1);

Here is an example of permissions object sent in the POST data body:

JSON

{
  "permission": {
    "LI-OPT": false,
    "LI-OM": true,
    "LI-NBA": false
  }
}

The permissions and names can be defined.

And here is a description of the example permissions acronyms:

Acronym	Description
`LI-OM`	Online Marketing
`LI-OPT`	Optimization (Analytics)
`LI-NBA`	Next Best Action / Personalization

Retrieve Permissions

You can retrieve permissions in the form of Permissions object where you can get any permission value by key/name.

KOTLIN

val permissions = FunnelConnectSDK.getPermissions()
val nbaPermission = permissions.getPermission("NBA")

JAVA

PermissionsMap permissions = FunnelConnectSDK.getPermissions();
boolean nbaPermission = permissions.getPermission("NBA");

Log Event(s)

We can log/track user actions in an app by sending user behavioral information, which can be used to create segments, update the 360-degree profile, or act as a trigger for further data and campaign activation action.

An event can be an element name such as a button and an action performed such as a click or some other behavioral tracking information.

We can log a single event by passing the event name and event value.

KOTLIN

FunnelConnectSDK.logEvent("addToCart", "12 V Battery")

JAVA

FunnelConnectSDK.logEvent("addToCart", "12 V Battery", null, null);

We can also add success and failure callbacks if needed.

KOTLIN

FunnelConnectSDK.logEvent("addToCart", "12 V Battery", successCallback = {}, errorCallback = {})

JAVA

FunnelConnectSDK.logEvent("addToCart", "12 V Battery", () -> {}, error -> {});

You can log multiple events by passing a map/dictionary of events names and values.

KOTLIN

val events = mapOf("addToCart" to "12 V Battery", "checkOutMethod" to "COD")
FunnelConnectSDK.logEvents(events)

JAVA

Map<String, String> events = new HashMap<>();
events.put("addToCart", "12 V Battery");
events.put( "checkOutMethod", "COD");
FunnelConnectSDK.logEvents(events, null, null);

You can also add success and failure callbacks if needed.

KOTLIN

val events = mapOf("addToCart" to "12 V Battery", "checkOutMethod" to "COD")
FunnelConnectSDK.logEvents(events, successCallback = {}, errorCallback = {})

JAVA

Map<String, String> events = new HashMap<>();
events.put("addToCart", "12 V Battery");
events.put( "checkOutMethod", "COD");
FunnelConnectSDK.logEvents(events, () -> {}, error -> {});

If you want to track a login button click, make sure to do it inside the success action of the setUser function and not after it, else both functions would run at the same time and the backend profile merge might prevent the tracking call identifier lookup to succeed as it no longer exists.

Get Unified Marketing ID (UMID)

Use the following code.

KOTLIN

FunnelConnectSDK.getUmid()

JAVA

FunnelConnectSDK.getUmid();

Identification Scenarios

If the user is required to log in before using the App, we suggest using the startService function and pass the user identifier (for example email, customer id, etc.) parameter.
If the App can be used by an anonymous/guest user, In this case, we can use the startService function without passing a user Id, in this case, a visitor profile will be created for fetch campaign and profile attributes including a Unified Marketing ID (UMID) if already existent.
If the app can be used in both previously described ways (authenticated user and anonymous/guest user), In this case, we can combine methods. For example, the startService method can be used to create a visitor profile if not already created, and to retrieve the data, and the setUserId when the user logs into the app and a user identifier is available to upgrade or merge the visitor profile into a user profile.
The dataClosure closure of the startService function can be used to handle further actions, which can be for example logEvent(...) method to log/track user actions within the app (see logEvent) and user profile attributes including a Unified Marketing ID (UMID).

Error Handling

All the functions with callbacks mentioned in the previous sections have success and failure callbacks, the failure callback returns a custom error relevant to the function, this custom error can be used to show an error or an action that can be taken based on the returned error.

All of the following errors are of type FunnelConnectError that inherits Throwable.

Showing errors flagged from the SDK to the end user is not recommended. Errors are returned so custom actions can be taken by developers based on the error type.

The following are all the errors that are expected to be returned:

Error	Description
`HttpException`	Denotes an HTTP exception with an error message and a status code.
`NoInternetConnectionException`	Denotes that the internet is not reachable through WiFi or cellular. If WiFi or cellular is connected but no internet connection this error won’t be thrown.
`SdkAlreadyInitializedException`	This error will be thrown on an attempt to initialize the SDK after it has already been initialized.
`SdkTokenCanNotBeEmptyException`	This error will be thrown if you pass an empty token to the SDK’s initializer.
`SdkNotInitializedException`	This error will be thrown if you try to access any function from the SDK before/without initializing the SDK.
`InvalidSdkTokenException`	Denotes an invalid token is used to initialize the SDK.
`ConfigFileNotFound`	Denotes that SDK config is not found.
`InfoNotEnabledException`	Denotes that `Info` is not enabled and it should be enabled or not used.
`TrackingNotEnabledException`	Denotes that `Tracking` is not enabled and it should be enabled or not used.
`IdentificationNotEnabledException`	Denotes that `Identification` is not enabled and it should be enabled or not used (Start the FunnelConnect service as a guest user).
`GenericException`	Denotes a general error that is not one of the errors in this table.
`UnknownException`	Denotes an unknown error.

Support and Bug Reporting

If you have any suggestions or you want to report a bug or ask a question, please create a new issue in this repository.

You can also check if there is a similar issue to yours that has been solved before.