iOS SDK

You can get the latest version from here.

The minimum iOS version is iOS 12.

Integrating the Mobile SDK

The library can be integrated into iOS projects in the following ways:

Swift Package Manager (SPM)

Go to your project → Package Dependencies tab.

Click the + sign to add a new package.

Add the following SPM dependency URL:

https://github.com/Teavaro/FunnelConnectSDK_iOS

CocoaPods

If it is the first time to add a CocoaPod to your project, then you should follow this official tutorial to install CocoaPods.

Add this pod to your project’s podfile pod 'FunnelConnect', or you can specify an explicit version pod 'FunnelConnect', 'LATEST_VERSION'

Install the pod:

cd {PATH_TO_YOUR_PROJECT}
pod install

If for some reason you got an error saying that the latest version is not found, please try to update the SDK pod using this command pod update FunnelConnect Please make sure that you have the latest stable version.

Binary Framework

• Head to this Repo.

• Download this file FunnelConnect.xcframework.

• Drag and drop it to your project.

• Make sure you always have the latest stable update of the framework.

Please make sure that you have the latest stable version.

Initializing the Library

Basic Initializing

Once integrated into your app, you can simply call the SDK initializer in the main class of your application.

This is how you do it:

FunnelConnectSDK.shared.initialize(sdkToken: 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 specifically enable or disable, this can be done by passing a custom options object to the initializer. Currently, enable debugging is the only available option, but there will be more in the future.

let fallbackConfigJson : String = "{ /* fallbackConfigJson */ }"
let options = FCOptions().enableLogging().setFallBackConfigJson(json: configJsonString)
FunnelConnectSDK.shared.initialize(sdkToken: SDK_TOKEN, options: options)

Check the SDK is Initialized

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

Boolean check

FunnelConnectSDK.shared.isInitialized()

didInitializeWithResult

FunnelConnectSDK.shared.didInitializeWithResult { [weak self] in
        // Success Action
} failure: { [weak self] error in
        // Failure Actio
}

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

try? FunnelConnectSDK.shared.clearData()
try? FunnelConnectSDK.shared.clearCookies()

Basic Usage

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

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 app visitor or authenticated customer profile. The API provides access to the profile data and allows updates, including:

1. Set or update permissions.

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

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

With callbacks

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:
Single user object:

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

Array of user objects

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

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

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

You can also set or update the user ID 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
            
})

Set Multiple User IDs

You can also set or update multiple user IDs.

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

And with success and failure callbacks.

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

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

try? FunnelConnectSDK.shared.getUsers()
OR
try? FunnelConnectSDK.shared.getUserIdByKey(key: "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.

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

The permissions and names can be defined.

And here is a description of the example permissions acronyms:

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

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 Unified Marketing ID (UMID)

try? FunnelConnectSDK.shared.getUmid()

Identification Scenarios

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

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

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

4. 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 NSError with code and message.

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

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

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.