Dev Docs

    

Getting started

Suggest Edits

1. Install the SDK

The easiest way to use WebEngage in your iOS project is with CocoaPods.

Before beginning this process please ensure that you are using Ruby version 2.0.0 or greater. Knowledge of Ruby syntax isn’t necessary to install this SDK.

  1. Download CocoaPods
    CocoaPods is a dependency manager for Swift and Objective-C projects. Install CocoaPods by running the following command.
$ sudo gem install cocoapods

If you face issues with CocoaPods, please refer to the CocoaPods Troubleshooting Guide.

  1. Add a Podfile
    In the terminal, navigate to your Xcode project directory. Create a Podfile by running the following command.
$ pod init
  1. Edit your Podfile
    Add the following in your Podfile under your project's target.

For Xcode 9 and above:

target 'YourAppTarget' do
  platform :ios, '8.0'
  pod 'WebEngage'
end

For Xcode 8:

target 'YourAppTarget' do
  platform :ios, '8.0'
  pod 'WebEngage/Xcode8'
end

WebEngage pod uses a dynamic framework. If you need to use a static binary (e.g. if you support iOS 7) then use the below pod.

For Xcode 9 and above:

target 'YourAppTarget' do
  platform :ios, '7.0'
  pod 'WebEngage', '= 3.5.8'
end

For Xcode 8:

target 'YourAppTarget' do
  platform :ios, '7.0'
  pod 'WebEngage/Xcode8', '= 3.5.8'
end
  1. Install WebEngage SDK
    To install the WebEngage SDK, navigate to your Xcode project directory and run the following command.
$ pod install
  1. Use the project workspace file created by CocoaPods (YOUR-PROJECT-NAME.xcworkspace) from now on instead of your project file (YOUR-PROJECT-NAME.xcodeproj) to ensure that the WebEngage SDK is properly loaded.
  2. Under Target -> General -> Linked Frameworks and Libraries, add AdSupport.framework with Status as Required.

2. Initialize the SDK

Call WebEngage's application:didFinishLaunchingWithOptions: from the application:didFinishLaunchingWithOptions: of your AppDelegate. We recommended that you make this call at the end of didFinishLaunchingWithOptions:.

You can use alternate APIs for initialization in case you want to handle the APNs registration for push notifications manually, with an alternate SDK, or to set a delegate for in-app notification callbacks.

import WebEngage

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
	var window: UIWindow?
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
                
        WebEngage.sharedInstance().application(application, didFinishLaunchingWithOptions: launchOptions)
        
        return true
}
 
#import <WebEngage/WebEngage.h>

@implementation AppDelegate

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

3. Configure Info.plist

Add the following properties to the Info.plist file of your project.

Key
Type
Value
Description

WEGLicenseCode

String

Your WebEngage license code

Mandatory

If you have multiple apps, you can use the same license code for all of them.

UIBackgroundModes

Array

fetch, location

Optional

Required if you want to track location updates in background.

WEGEnableLocationAuthorizationRequest

String

ALWAYS / IN_USE / NO

Optional

Enables WebEngage SDK to request user to authorize for location on behalf of the app. If this is absent or the value is anything other than
ALWAYS or IN_USE, WebEngage SDK would not make any authorization request on behalf of the app. It will track location updates only if the app itself has sought relevant permissions from the user.

NSLocationAlwaysUsageDescription

String

App specific description

Required if:
The app makes authorization request to always use location, or
Value of WEGEnableLocationAuthorizationRequest is ALWAYS.

NSLocationWhenInUseUsageDescription

String

App specific description

Required if:
The app makes authorization request to use location when the app is in use, or
Value of WEGEnableLocationAuthorizationRequest is IN_USE.

WEGLogLevel

String

DEFAULT / VERBOSE

Optional

Available from SDK version 3.2. In VERBOSE mode, you get detailed SDK logs. VERBOSE mode logs are a superset of DEFAULT mode logs.

4. Support for Swift

If you are using Swift for writing your application, follow this step. This is the general method for integrating Objective-C frameworks in a Swift project. If you have already done this for another framework, skip this step.

  1. Navigate to File > New and select File.... Select Objective-C File under iOS Source and click Next.
  2. Name the file without any extension. Click Next.

Name this file such that you can use it generically for all frameworks, and not specific to WebEngage.

  1. Select the Group as your main project and target as your main app target. Click Create.
  2. You will now be prompted to create a Bridging Header. Bridging Header is a file that makes Objective-C frameworks available to Swift and vice-versa. Click on Create Bridging Header to proceed.
  3. Above step will create two files in your main project’s Supporting Files folder with the following name formats:
    a. <YOUR_FILE_NAME>.m
    b. <YOUR_PROJECT_NAME>-Bridging-Header.h
    Delete the <YOUR_FILE_NAME>.m file.
  4. Add the following imports to <YOUR_PROJECT_NAME>-Bridging-Header.h file. You only need to specify this in Objective-C even if you are using Swift for your project.
#import <WebEngage/WebEngage.h>
#import <WebEngage/WEGUser.h>
#import <WebEngage/WEGAnalytics.h>

If you are using WebViews in your iOS app, check out WebEngage JavaScript bridge. For other advanced integration options such as location tracking, refer the Advanced section.

Session lifecycle

WebEngage SDK automatically starts tracking user data (e.g., device model, OS version, device IDs) and engagement with the basic setup above. This data is stored on the device and is periodically uploaded in batches to reduce network and power usage, and to increase the likelihood of successful uploads. The upload cycle is based on the number of datapoints in local database and last synced time. This local database size is capped and is deleted as soon as it is successfully uploaded.

WebEngage SDK also starts tracking user sessions with this basic setup. Upon app backgrounding, the SDK marks the current time. If the user returns to the app after more than 15 seconds since the user had last backgrounded the app, the SDK will close the previous session. If the user foregrounds the app within 15 seconds of the previous backgrounding, the previous session is resumed as if the user did not leave the app at all. Also, if the user force kills the app and launches it again after being force killed (irrespective of the time duration between force kill and launch), the SDK will close the previous session upon force-kill and start a new session upon app launch.

Next steps

Congratulations! You have now successfully integrated WebEngage SDK with your iOS app and are now sending user session and system event data to WebEngage.

Note that it may take a few minutes for your data to show up on the WebEngage dashboard. We suggest you meanwhile proceed to read the next sections to learn how to:

  1. Track user properties as attributes
  2. Track user actions as events
  3. Integrate push messaging
  4. Integrate in-app messaging

We recommend doing these integrations before releasing your app for the first time with WebEngage.