Optimove iOS SDK Integration

Optimove's iOS SDK for native apps is a general-purpose suite of tools that is built to support multiple Optimove products.
The SDK is designed with careful consideration of the unpredicted behavior of the Mobile user and Mobile environment, taking into account limited to no networking and low battery or memory limitations.
While supporting a constantly rising number of products, the SDK's API is guaranteed to be small, coherent and clear. This is a developers’ guide for integrating the native Optimove mobile SDK with native iOS applications.

This guide covers the basic technical steps for configuring and installing the SDK, demonstrate common use cases, and provide usage guidelines.

Getting Started

There are a few important steps to get out of the way when integrating Optimove SDK with your app for the first time.

Please follow these instructions carefully to ensure that you’ll have an easy development experience.

Prerequisites

Before you can begin using Optimove SDK for iOS, you will need to perform the following steps.

• A tenant_information_suite provided during the initial integration with Optimove and contains the following: end-point url - The URL where the tenant configurations reside token - The actual token, unique per tenant config name - The name of the desired configuration
• Tenant has a paid development account, and valid certificates for remote notifications or APN Auth key.
• Deliver The APN Auth key (preferred) or APN Certificates was delivered to Optimove CSM.
• Deliver the Team ID
• Deliver the Appstore ID of the application
• Enable push notification and remote notification capabilities in your project

Setting up the SDK

Optimove SDK for iOS is provided as a group of files within a Folder named “OptimoveSDK”.

To install the SDK, drag the folder into your project.

If not all files inside the folder are members of the target application, add them.

In order to work with the Optimove SDK, you also need to download some modules from CocoaPods.
In your Podfile, add the following:

pod 'Firebase','~> 4.8.0'
pod 'FirebaseMessaging', '~> 2.0.8'
pod 'FirebaseDynamicLinks', '~> 2.3.1'
pod 'XCGLogger', '~> 6.0.2'
pod 'OptimovePiwikTracker'

In your AppDelegate class, inside the

application (_: didFinishLaunchingWithOptions:)

method, create a new OptimoveTenantInfo object. This object should cotain:

1. The end-point URL
   
2. Unique Optimove token.
   
3. Configuration key provided by Optimove CSM
   
4. Indication for exsiting Firebase module inside your application.
   

Use this Object as an argument for the SDK Function

 Optimove.sharedInstance.configure(info:) 

This call initializes the OptimoveSDK Singleton.

for example:

func application(_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
let info = OptimoveTenantInfo(url:"https://optimove.mobile.demo/sdk-configs/", // end-point url
token: "abcdefg12345678", // token
version: "myapp.ios.1.0.0", //config name
hasFirebase: false) // indication for tenant autonomous firebase
Optimove.sharedInstance.configure(info: info)

The initialization must be called as soon as possible, unless the tenant has its own Firebase SDK. In this case start the initialization right after calling FirebaseApp.configure().

State Registration

The SDK initialization process occurs asynchronously, off the Main Thread.
Before calling the Public API methods, make sure that the SDK has finished initialization by calling the register(stateDelegate:) method with an instance of OptimoveStateDelegate.

class AppDelegate: UIResponder,
    UIApplicationDelegate, OptimoveStateDelegate
  {
    var window: UIWindow?
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions:
                     [UIApplicationLaunchOptionsKey: Any]?) -> Bool
    {    
        let info = OptimoveTenantInfo(url:"https://optimove.mobile.demo/sdk-configs/",
                                      token: "abcdefg12345678",
                                      version: "myapp.ios.1.0.0",
                                      hasFirebase: false)
        
        Optimove.sharedInstance.configure(info: info)
        Optimove.sharedInstance.register(stateDelegate: self)
        return true
    }
  }

Do not forget to implement the OptimoveStateDelegate methods, and provide a unique Int id to any enitity that conform to the protocol.

Reporting User Activities and Events

Using the Optimove's iOS SDK, the hosting application can track events with analytical significance.
These events can range from basic Screen Visits to Visitor Conversion and Custom Events defined in the Optimove Configuration.
If you want to use optitrack capabilities as your analytics tool, you may use Optimove API such as:

Set User ID

Once the user has downloaded the application and the Optimove SDK run for the first time, the user is considered a Visitor, i.e. an unidentified person.
Once the user authenticates and becomes identified by a known PublicCustomerId, then the user is considered Customer.
As soon as this happens for each individual user, pass the CustomerId to the Optimove singleton like this:

Optimove.sharedInstance.set(userId:)

Note: the CustomerId is usually provided by the Server App that manages customers, and is the same ID provided to Optimove during the daily customer data transfer.

Due to its high importance, set (userId:) may be called at any time, regardless of the SDK’s state.

Report Screen Event

To track which screens the user has visited in your app, send a setScreenEvent message to the shared Optimove instance:.

Optimove.sharedInstance.setScreenEvent(viewControllersIdentifiers:url)

The viewControllersIdentifiers argument should include an array that represents the path to the current screen.
To support more complex view hierarchies, you may also specify a screen URL in the second parameter.

Report Custom Event

To report a Custom Event (one defined by you and the Optimove Integration Team and already configured in your Optimove site), you must implement the OptimoveEvent protocol.
The protocol defines 2 properties:

1. name: String - Declares the custom event's name
2. parameters: [String:Any] - Defines the custom event's parameters.
   Then send that event through the reportEvent(event:) method of the Optimove singleton.

override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
Optimove.sharedInstance.reportEvent(event: MyCustomEvent())
}

Note:

• All Custom Event must be declared in the Tenant Configurations.
  
• Custom Event reporting is only supported when OptiTrack Feature is enabled.
  
• The usage of reportEvent function depends on your needs.
  This function may include a completion handler that will be called once the report has finished, the default value for this argument is nil.

Optipush:

Optipush is Optimove’s mobile push notification delivery add-in module, powering all aspects of preparing, delivering and tracking mobile push notification communications to customers, seamlessly from within Optimove.
Optimove SDK for iOS includes built-in functionality for receiving push messages, presenting notifications in the app UI and tracking user responses.

In order for Optipush to be able to deliver push notifications to your iOS app, Optimove SDK for iOS must receive an APN token from your app. This is accomplished by the following steps: Inside the application AppDelegate class

application(_:didRegisterForRemoteNotificationsWithDeviceToken:)

call

 Optimove.sharedInstance.application(didRegisterForRemoteNotificationsWithDeviceToken:)

And in

application(_:didReceiveRemoteNotification:fetchCompletionHandler:)

call

 Optimove.sharedInstance.handleRemoteNotificationArrived(userInfo:fetchCompletionHandler)

example:

 
  func application(_ application: UIApplication,
                     didReceiveRemoteNotification userInfo: [AnyHashable : Any],
                     fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void)
    {
        Optimove.sharedInstance.handleRemoteNotificationArrived(userInfo: userInfo,
                                                        fetchCompletionHandler: completionHandler)
      
    }
    
    func application(_ application: UIApplication,
                     didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data)
    {
        Optimove.sharedInstance.application(didRegisterForRemoteNotificationsWithDeviceToken: deviceToken)
    }
 

Deep Link:

Other than UI attributes, an Optipush Notification can contain metadata linking to a specific screen within your application, along with custom (screen specific) data.

To support deep linking, you should:

• Enable Associated Domains: In your project capabilities, add the dynamic link domain with applinks: prefix and without any https:// prefix

Any ViewControler should recieve DynamicLink data callback, should implement didReceive(dynamicLink:), thus conforming to DynamicLinkCallback protocol .
DynamicLinkCallback protocol has one method:

didReceive(dynamicLink:)

A dynamicLinkComponent struct contains two properties:

· ScreenName: for the required viewcontroller you need to segue to.

· Query: That contain the content that should be included in that view controller.

example:

func didReceive(deepLink: OptimoveDeepLinkComponents?) {
    if let deepLink = deepLink {
    DispatchQueue.main.asyncAfter(deadline: .now()+2.0)
    {
        if let vc = self.storyboard?.instantiateViewController(withIdentifier: deepLink.screenName) {
            self.navigationController?.pushViewController(vc, animated: true)
            }
        }
    }
}

Test Optipush Templates

t is usually desirable to test an Optipush Template on an actual device before sending an Optipush Campaign to users.
To enable "test campaigns" on one or more devices, call the Optimove.sharedInstance.subscribeToTestMode() method.
To stop receiving "test campaigns" call Optimove.sharedInstance.unSubscribeFromTestMode().

class ViewController: UIViewController {
    
    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        Optimove.sharedInstance.subscribeToTestMode()                              
    }
}

Special Use Cases

The Hosting Application Uses Firebase

Installation

The Optimove iOS SDK is dependent upon the Firebase iOS SDK.
If your application already uses Firebase SDK or has a dependency with Firebase SDK, a build conflict or runtime exception may occur, due to backwards compatibility issues.
Therefor, it is highly recommended to match the application's Firebase SDK version to Optimove's Firebase SDK version as detailed in the following table.

Optimove SDK Version	Firebase Version	Firebase Messaging Version	FirebaseDynamicLinks
1.0.3.1	4.8.0	2.0.8	2.3.1