CDP Service

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

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

Start the CDP Service:

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

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

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

FunnelConnectSDK.cdp().startService(dataCallback = {
    val response = JSONObject(it)
    if (response.has("umid")) {
        println(response.getString("umid"))
    }
}, errorCallback = {
       error.printStackTrace()
})
FunnelConnectSDK.cdp().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:

FunnelConnectSDK.cdp().startService(notificationsName = "{NOTIFICATION_NAME}", notificationsVersion = -1)
FunnelConnectSDK.cdp().startService(null,  "{NOTIFICATION_NAME}", 1, null, null);
FunnelConnectSDK.cdp().startService(notificationsName = "{NOTIFICATION_NAME}", notificationsVersion = -1, dataCallback= { ... }, errorCallback = { ... })
FunnelConnectSDK.cdp().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 it is not passed in case of Kotlin, 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 user object to start the CDP service as an identified user:

FunnelConnectSDK.cdp().startService(FCUser("email", "mail@domain.com"))
FunnelConnectSDK.cdp().startService(new FCUser("email", "mail@domain.com"), "{NOTIFICATION_NAME}", 1, null, null);

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

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

{
"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 fired, 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 Universal 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 acklowledged consent notifications with distinct version.
notificationStatus Shows permissions for which a notification has been acknowledged.

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

Set User Id:

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

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

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

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

Get saved user Id:

You can get the saved user Id if it was set before:

FunnelConnectSDK.cdp().getUserId()
FunnelConnectSDK.cdp().getUserId();

Set or update permissions:

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.

The permissions can be set or updated by passing map PermissionsMap of permission names and the status of each permission is represented by a boolean value indicating that it is accepted or rejected.

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

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

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

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

And here is a description of the example permissions acronyms:

Acronym Description
LI-OM Online Marketing
LI-OPT Optimisation (Analytics)
LI-NBA Next Best Action / Personalisation

Retrieve permissions:

You can retrieve permissions in the form of PermissionsMap where you can get a permission value by key

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

Log event/events:

We can log/track user actions in an app by sending user behavioral information to the CDP, 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.

You may add more descriptive information in the string description parameter as required, which will then be available in the CDP.

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

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

We can also add success and failure callbacks if needed.

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

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

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

You can also add success and failure callbacks if needed.

val events = mapOf("addToCart" to "12 V Battery", "checkOutMethod" to "COD")
FunnelConnectSDK.cdp().logEvents(events, successCallback = {}, errorCallback = {})
Map<String, String> events = new HashMap<>();
events.put("addToCart", "12 V Battery");
events.put( "checkOutMethod", "COD");
FunnelConnectSDK.cdp().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 UMID (Universal Marketing ID) :

FunnelConnectSDK.cdp().getUmid()
FunnelConnectSDK.cdp().getUmid();

Scenarios of user & customer identification:

  • 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, user Id, IDFA) 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 Universal 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 Universal Marketing ID (UMID).