Importing the iOS SDK

SDK versions compatibility and requirements

Please refer the releases page for to get specific version.

Installation

The Copilot 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 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. Since the pod is not directly available on CocoaPods website, you’ll need to specify the source URL at the top of your Podfile:

source 'https://github.com/CocoaPods/Specs.git'
source 'https://bitbucket.org/teamcopilot/copilot-sdk-ios-specs.git'

5. Add the Copilot 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.

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

$ pod install
$ open <your project>.xcworkspace

7. 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>CopilotConnect</string>
    </dict>
</plist>

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

9. 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 CopilotAPIAccess

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

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

import CopilotAPIAccess

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: 
    [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
        Copilot.setup(analyticsProviders: [FirebaseAnalyticsEventLogProvider()])
        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.

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 make sure you import CopilotApiAccess:

import CopilotAPIAccess

Updating the iOS SDK

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

1. In order to update the SDK version you'll need to update the local repository of Copilot's private pod. In order to do so, execute the following command in a terminal window:

pod repo update bitbucket-teamcopilot-copilot-sdk-ios-specs

2. In your project's podfile update Copilot 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'

3. Update the specific pod executing:

pod update 'Copilot'