Integration

WebEngage Core SDK Integration

This document assumes you have already obtained a APNS certificate from Apple Developer Portal and uploaded to your WebEngage Account. Refer to Preparing the SDK for APNS for the same, or skip for later.

iOS SDK Setup

Minimum SDK Requirements

Webengage SDK is supported for iOS7 and above only. We needs the following frameworks to be linked as part of the XCode project(Direct Integration). Specifically:

1. CoreLocation.framework
2. SystemConfiguration.framework
3. -lsqlite3

Integration Methods

There are two ways of integrating Webengage to your existing/new XCode Project.

Cocoapods Integration (Recommended)

  1. Add the below lines to your Podfile under your project's target:

target 'WebEngageExample' do (Look for Similar lines in your Podfile)

For Xcode 8 and above:

pod 'WebEngage'

For XCode 7:

pod 'WebEngage/Xcode7' 

In case you would like to try out the latest beta releases(things might still break) for new features, add the source to github repo before the above lines in your Podfile:

source 'https://github.com/WebEngage/podspecs.git' 
source 'https://github.com/CocoaPods/Specs.git'

Learn about Podfile Specifications here

Direct Integration

  1. Download the SDK file here. Extract the downloaded zip file. In the extracted zip there would be two directories - xc7 and xc8. If you are using XCode 7 use the Webengage.framework within the xc7 directory. For Xcode 8 and above use the one in xc8. Save the appropriate Webengage.framework it in a location on your computer.

  2. Select the name of the project in the project navigator. The project editor appears in the editor area of the Xcode workspace window.

  3. Click on the General Tab at the top of project editor.

  4. In the section Embedded Libraries click on + button. It will open up the file chooser for your project. Open WebEngage.framework and select Copy if needed option. This will copy the framework to your project directory.

  5. Below Embedded Libraries, there is Linked Frameworks and Libraries click the + button and add the following frameworks:

    SystemConfiguration.framework 
    CoreLocation.framework
    
  1. Go to 'Build Settings' tab on the top of the project editor. Search for Other Linker Flags option.
    Add -lsqlite3 and -ObjC under it.

At this point, Webengage SDK integration is complete and your project should build successfully.

Info.plist Changes

Add the following keys with their required values to the Info.plist file of your app:

  1. WEGLicenseCode The value(string) for this would be a your license code obtained from the accounts section in the dashboard.
  2. UIBackgroundModes Add if not already using in the app. This is a known property in iOS.

    The value of this key is an array and it requires the following values:

     a) remote-notification
     b) fetch
     c) location(optional, but required if you want to track location updates in background)
    
  3. WEGEnableLocationAuthorizationRequest (optional) The allowed values(string) for this are ALWAYS, IN_USE and NO.
    Default is NO.

    This property enables Webengage to request user to authorize for location on behalf of the app. If this is absent or the value is anything other than
    ALWAYS and IN_USE(including NO), Webengage would not make any authorization requests on behalf of the app and track location updates only if the app itself has sought relevant permissions from the user.

  4. NSLocationAlwaysUsageDescription (optional and if not added already) Would be required if

     Either the app makes a authorization request to always use location, or
     The above key's value is ALWAYS.
    
  5. NSLocationWhenInUseUsageDescription(optional and if not added already) Would be required if

     Either the app makes a authorization request to use location when the app is in use, or
     The above key's value is IN_USE.
    
  6. WEGLogLevel (Optional, Available from Version: 3.2) The current supported values are: DEFAULT, VERBOSE. If you skip it, or provide any value other than VERBOSE, it is treated as DEFAULT.

    In VERBOSE mode, you get detailed logs of what's going behind the scenes in the iOS SDK.
    VERBOSE mode logs are a superset of DEFAULT mode logs.

Support for Swift

If you're using Apple's new programming language Swift for writing your application, you need to take small additional steps to integrate Webengage.

  1. Go to File -> New -> File and choose Objective-C File from the window that appears next. Click Next to continue. <br/><br/>
  1. Name the file without any extension.

Note:
This is the general method for integrating Objective C frameworks in a Swift Project. You'll not be required to repeat this for any other Objective C frameworks that you use in your codebase(or skip this step if you have already done this for another framework). Name your file accordingly so that you can use it generically and not specific to WebEngage.

  1. Next it will give you a promt and ask you to create a Bridging Header. Bridging Header is a file that makes available Objective C imports to Swift and vice-versa. Click on the blue button to proceed. <br/><br/>
  1. The above step will create two files in your project with the following name formats:

    • <YOUR_FILE_NAME>.m (The one that you chose earlier, BridgingHeader.m in this case)
    • <YOUR_PROJECT_NAME>-<YOUR_FILE_NAME>.h (WebengageSDKWithSwift-Bridging-Header.h in this case)

      Delete the *<YOUR_FILE_NAME>.m file.

  2. Go to the <YOUR_PROJECT_NAME>-<YOUR_FILE_NAME>.h file and add the following imports:

#import <WebEngage/WebEngage.h>
#import <WebEngage/WEGUser.h>
#import <WebEngage/WEGAnalytics.h>

Initialising the SDK

After integrating the SDK, it needs to be initialised for tracking events and obtaining the WebEngage instance for using other APIs.

To initialise the SDK, make a call to WebEngage's application:didFinishLaunchingWithOptions: from your application delegate's application:didFinishLaunchingWithOptions:. It is recommended to make the call before doing your own stuff in the delegate's method.

#import <WebEngage/WebEngage.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application 
                  didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  
  [[WebEngage sharedInstance] application:application 
                                didFinishLaunchingWithOptions:launchOptions];
  /**
    <i>YOUR CODE GOES HERE</i>
  **/
  return YES;
}

You can use alternate APIs for initialisation in case you want to handle the APNS registration for remote notifications manually(or with an alternate SDK) or want to set a delegate for In-App Notification Callbacks.

For Swift Applications:

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(application: UIApplication, 
        didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
        
        WebEngage.sharedInstance().application(application, 
                    didFinishLaunchingWithOptions: launchOptions);
                    
        /**
            <i>YOUR CODE GOES HERE</i>
        **/
        return true
    }

Learn how to integrate WebEngage with Swift application. For a general understanding on how to use objective C APIs in Swift Code, visit here.


What's Next

iOS 10 Rich Push Notifications Integration

iOS 10 Rich Push Notifications Integration

Integration

WebEngage Core SDK Integration