Importing the iOS SDK

SDK versions compatibility and requirements

Please refer the releases page for to get specific version.

Installation

The Copilot.cx iOS SDK is available via private CocoaPod, here few steps to follow in order to install successfully the iOS SDK:

1. Navigate to your project folder in a terminal window.
2. Make sure you have the CocoaPods gem installed on your machine before installing the Copilot.cx pod. This will create a file named Podfile in your project's root directory.

$ sudo gem install cocoapods  

3. Create the Podfile - you can the Podfile with a text editor or execute the pod init command at the root of your Xcode project.

$ pod init

4. Add the Copilot.cx SDK pod to your Podfile (please refer the releases page for to get specific version):

# For example pod 'Copilot', '10.10.10'
pod 'Copilot', 'YOUR_COPILOT_IOS_SDK_VERSION_HERE'

Please make sure you use specific versions of the SDK in your podfile.

5. Finally, run the following commands in your project root directory from the terminal window:

$ pod install
$ open <your project>.xcworkspace

6. Add a new Property List file (.plist) to your project and name it Copilot-Info.plist. Put your app’s configuration in the Copilot-Info.plist file, it should look like this :

Source representation:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
        <key>IS_GDPR_COMPLIANT</key>
        <<IS_APPLICATION_GDPR_COMPLIANT(true/false)>/>
        <key>Authentication Params</key>
        <dict>
            <key>APPLICATION_ID</key>
            <string>YOUR_APPLICATION_ID_HERE</string>
            <key>ENVIRONMENT_URL</key>
            <string>COPILOT_ENVIRONMENT_URL_HERE</string>
        </dict>
        <key>MANAGE_TYPE</key>
        <string>Sphere</string>
    </dict>
</plist>

💡 Please note, you can configure the SDK to work with different Plist files based on your application configuration when setting up Copilot.cx instance in your AppDelegate. Copilot.setup(analyticsProviders: [FirebaseAnalyticsEventLogProvider()], customPlistName: "AlternateCopilot-Info")

7. Replace IS_APPLICATION_GDPR_COMPLIANT,YOUR_APPLICATION_ID_HERE and COPILOT_ENVIRONMENT_URL_HERE with the appropriate values (please refer the SDK configuration section)

8. Add the FirebaseAnalyticsEventLogProvider class implementing the EventLogProvider protocol to your project.

💡 Please note, in case you already call the FirebaseApp.configure() method from anywhere else(e.g. AppDelegate) there's no need to call this method again. Calling the configure method twice will result in exception to be thrown.

import Foundation
import Firebase
import FirebaseAnalytics
import CopilotCX

class FirebaseAnalyticsEventLogProvider: EventLogProvider {
    
    init() {
        FirebaseApp.configure()
        updateFirebaseAnalyticsStatus(shouldLogEvents: false)
    }
    
    func enable() {
        updateFirebaseAnalyticsStatus(shouldLogEvents: true)
    }

    func disable() {
        updateFirebaseAnalyticsStatus(shouldLogEvents: false)
    }

    func setUserId(userId:String?){
        Analytics.setUserID(userId)
    }
    
    func transformParameters(parameters: Dictionary<String, String>) -> Dictionary<String, String> {
        return parameters
    }
    
    func logCustomEvent(eventName: String, transformedParams: Dictionary<String, String>) {
        Analytics.logEvent(eventName, parameters: transformedParams)
    }
    
    var providerName: String {
        return "FirebaseAnalyticsEventLogProvider"
    }
    
    var providerEventGroups: [AnalyticsEventGroup] {
        return [.All]
    }

    private func updateFirebaseAnalyticsStatus(shouldLogEvents: Bool) {
        Analytics.setAnalyticsCollectionEnabled(shouldLogEvents)
    }
}

9. Add in Online Marketplaces Support to make sure iOS can support Marketplace Actions.

10. Initialize Copilot.cx in your AppDelegate class setting it with a list of EventLogProviders as shown below (please refer the Managing providers section).

import CopilotCX

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: 
    [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
        Copilot.setup(analyticsProviders: [FirebaseAnalyticsEventLogProvider()])
            .enableDebugLogs()
        return true
}

💡 You may add other EventLogProviders per your need. Every event will be dispatched to every provider configured in the system. It is suggested to add a console log only event provider for event dispatching debugging purposes.

Copilot logs are disabled by default. To enable them, add the enableDebugLogs() command as shown in the example, Or by calling the function through the Copilot object: Copilot.instance.enableDebugLogs()

11. Add Google Firebase to your iOS project following this guide : Add firebase to your iOS Project. Make sure you will end up with GoogleService-Info.plist file in your project.

12. In every file you would like to use Copilot.cx make sure you import CopilotCX:

import CopilotCX

Updating the iOS SDK

The client SDK is backward compatible, but it should correlate with the versioning of Copilot.cx Cloud. Make sure you update the pod version after approving that current Copilot.cx Cloud version can support the latest SDK version.

1. In your project's podfile update Copilot.cx SDK with a new version number, Please refer the releases page for to get specific version.

# For example pod 'Copilot', '10.10.10'
pod 'Copilot', 'YOUR_COPILOT_IOS_SDK_VERSION_HERE'

2. Update the specific pod executing:

pod update 'Copilot'