Integration

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 FunnelConnect Service

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

try? FunnelConnectSDK.shared.startService()

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

extension String {
    func toDictionary() -> [String: Any]? {
            if let data = data(using: .utf8) {
                return try? JSONSerialization.jsonObject(with: data, options: []) as? [String: Any]
            }
            return nil
        }
}

FunnelConnectSDK.shared.startService(dataCallback: { [weak self] data in
            if let info = data.toDictionary(), info["state"] != nil {
                //...
            }
        }, errorCallback: { [weak self] error in
            // ...
})

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

try? FunnelConnectSDK.shared.startService(notificationsName: "{NOTIFICATION_NAME}" , notificationsVersion: -1)

FunnelConnectSDK.shared.startService(notificationsName: "{NOTIFICATION_NAME}" , notificationsVersion: -1, dataCallback: { [weak self] data in
            
}, errorCallback: { [weak self] error in
            
})

The notifications name and 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, 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:

try? FunnelConnectSDK.shared.startService(fcUser: FCUser(userIdType: "email", userId: "mail@domain.com"))

let fcUsers = [FCUser(userIdType: "email", userId: "mail@domain.com"), FCUser(userIdType: "idfa", userId: "9F4129C1-22B4-433B-BD79-7E581F443EED")]
try? FunnelConnectSDK.shared.startService(fcUsers: fcUsers)

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.

Set User ID/IDs

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

try? FunnelConnectSDK.shared.setUser(fcUser: FCUser(userIdType: "email", userId: "mail@domain.com"))

let fcUsers = [FCUser(userIdType: "email", userId: "mail@domain.com"), FCUser(userIdType: "idfa", userId: "9F4129C1-22B4-433B-BD79-7E581F443EED")]
try? FunnelConnectSDK.shared.setUsers(fcUsers: fcUsers)

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

FunnelConnectSDK.shared.setUser(fcUser: FCUser(userIdType: "email", userId: "mail@domain.com"), dataCallback: { [weak self] data in
            
        }, errorCallback: { [weak self] error in
            
})

let fcUsers = [FCUser(userIdType: "email", userId: "mail@domain.com"), FCUser(userIdType: "idfa", userId: "9F4129C1-22B4-433B-BD79-7E581F443EED")]
FunnelConnectSDK.shared.setUsers(fcUsers: fcUsers, dataCallback: { [weak self] data in
                    
                }, errorCallback: { [weak self] error in
                    
})

Get saved user ID

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

try? FunnelConnectSDK.shared.getUsers()
OR
try? FunnelConnectSDK.shared.getUserIdByKey(key: "email")

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 creating Permissions object, then pass permission name and value of type boolean indicating that it is accepted or rejected.

let permissions = Permissions()
permissions.addPermission(key: "OM", accepted: true)
permissions.addPermission(key: "NBA", accepted: false)
try? FunnelConnectSDK.shared.updatePermissions(permissions: permissions, notificationsName: "{NOTIFICATION_NAME}" ,notificationsVersion: 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 Permissions object where you can get any permission value by key/name

let permissions = try? FunnelConnectSDK.shared.getPermissions()
let nbaPermission = permissions?.getPermission(key: "NBA") ?? false

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.

try? FunnelConnectSDK.shared.logEvent(key: "addToCart", value: "12 V Battery")

We can also add success and failure callbacks if needed.

FunnelConnectSDK.shared.logEvent(key: "addToCart", value: "12 V Battery", successCallback: { [weak self] in
            
        }, errorCallback: { [weak self] error in
         
})

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

let events = ["addToCart": "12 V Battery", "checkOutMethod": "COD"]
try? FunnelConnectSDK.shared.logEvents(events: events)

You can also add success and failure callbacks if needed.

let events = ["addToCart": "12 V Battery", "checkOutMethod": "COD"]
FunnelConnectSDK.shared.logEvents(events: events, successCallback: { [weak self] in
            
        }, errorCallback: { [weak self] error in
         
})

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)

try? FunnelConnectSDK.shared.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, 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 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).