Getting Started

1. Install the SDK


The easiest way to use WebEngage in your iOS project is with CocoaPods. Before you begin, please ensure that you are using Ruby v2.0.0 or higher (knowledge of Ruby syntax isn’t needed to install the SDK).

Step 1: Download CocoaPods

CocoaPods is a dependency manager for Swift and Objective-C projects. You can install CocoaPods by running the following command.

$ sudo gem install cocoapods


Please refer to the CocoaPods Troubleshooting Guide in case you have trouble using CocoaPods.

Step 2: Add a Podfile

In the terminal, navigate to your Xcode project directory and create a Podfile by running the following command.

$ pod init

Step 3: Edit your Podfile

Add the following in your Podfile under your project's target.

# Avoid use_frameworks! declaration in your Podfile. Contact us at [email protected] if you face any issue.

target 'YourAppTarget' do
  pod 'WebEngage'

Step 4: Install WebEngage SDK

To install the WebEngage SDK, navigate to your Xcode project directory and run the following command.

$ pod install

Step 5: Stop using your project file, YOUR-PROJECT-NAME.xcodeproj. And start using the project workspace file created by CocoaPods, YOUR-PROJECT-NAME.xcworkspace from now on.

  • Doing so will ensure that the WebEngage SDK is properly loaded.

Step 6: Under Target -> General -> Linked Frameworks and Libraries, add AdSupport.framework with Status as Required.

2. Initialize the SDK

Step 1: 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

class AppDelegate: UIResponder, UIApplicationDelegate {
  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 {
  [[WebEngage sharedInstance] application:application didFinishLaunchingWithOptions:launchOptions];
  return YES;

3. Configure Info.plist

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

WEGLicenseCodeStringYour WebEngage license codeMandatory

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

Required only if you want to track location updates in the background.
WEGEnableLocationAuthorizationRequestStringALWAYS / IN_USE / NOOptional

- Enables WebEngage SDK to request the user for location tracking authorization on behalf of the app.

- If property is absent or value is not set to ALWAYS or IN_USE, then WebEngage SDK will track location updates only if the app itself has sought relevant permissions from the user.
NSLocationAlwaysUsageDescriptionStringApp specific descriptionMandatory if:

- The app makes authorization request to always use location.

- Value of WEGEnableLocationAuthorizationRequest is set as ALWAYS.
NSLocationWhenInUseUsageDescriptionStringApp specific descriptionMandatory if:

- The app makes authorization request to use location when the app is in use.

- Value of WEGEnableLocationAuthorizationRequest is set as IN_USE.
WEGLogLevelStringDEFAULT / VERBOSEOptional

- Available from SDK version 3.2.

- VERBOSE mode logs are a superset of DEFAULT mode logs. It provides detailed SDK logs.
WEGEnvironmentStringDEFAULT / IN/ KSAMandatory

- At WebEngage, you can choose to host all your data at three data centers, US, Saudi Arabia or India. By default, your data is stored in our US (or Global) Data Center. However, you can choose to host it at our India or Saudi Arabia Data Center by specifying the same in your contractual agreement.

For Global/ Default/ US Data Center:

- If your WebEngage dashboard URL starts with, then it means you're using our Global Data Center.

- Specify DEFAULT as the value for WEGEnvironment.

For India Data Center:

- If your WebEngage dashboard URL starts with, then it means you're using our India Data Center.

- Specify IN as the value for WEGEnvironment.

For Saudi Arabia Data Center:

- If your WebEngage dashboard URL starts with, then it means you're using our India Data Center.
- Specify KSA as the value for WEGEnvironment.
WEGAlternateAppSupportBooleanYES / NOOptional

- WebEngage supports running multiple apps with the same License Code.

- To enable multi app support in your app's Info.plist file, enter WEGAlternateAppSupport key as Boolean type & set it to YES.

Please note:

- This should not be used for Staging & Production builds of the same app.

- If enabled, ensure that you are using Auth Keys instead of APNS Certificates for Push Notifications.

4. Support for Swift



Please follow this step if you are using Swift for writing your application. If you have already done this for another framework, the please skip it.

A demo Swift based app showcasing the integration of WebEngage SDK is available on GitHub.

This is the general method for integrating Objective-C frameworks in a Swift project:

Step 1: Navigate to File > New and select File.... Select Objective-C File under iOS Source and click Next.

Step 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.)

Step 3: Select the Group as your main project and target as your main app target.

  • Click Create to proceed.

Step 4: 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 Create Bridging Header to proceed.

Step 5: Above step will create two files in your main project’s Supporting Files folder with the following name formats:
b. <YOUR_PROJECT_NAME>-Bridging-Header.h

  • Delete the file, <YOUR_FILE_NAME>.m.

Step 6: Add the following imports to the <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.
// <YOUR_PROJECT_NAME>-Bridging-Header.h
#import <WebEngage/WebEngage.h>
#import <WebEngage/WEGUser.h>
#import <WebEngage/WEGAnalytics.h>
// ServiceExtension-Bridging-Header.h (Optional)
// Required if ServiceExtension Target is in Swift

#import <UserNotifications/UserNotifications.h>
#import <WebEngageBannerPush/WEXPushNotificationService.h>
// ContentExtension-Bridging-Header.h (Optional)
// Required if ContentExtension Target is in Swift

#import <WebEngageAppEx/WEXRichPushNotificationViewController.h>

If you are using WebViews in your iOS app, check out WebEngage JavaScript bridge. For other advanced integration options such as location tracking, please 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 increase the likelihood of successful uploads. The upload cycle is based on the number of data points in the local database and the last synced time. This local database size is capped, and data 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. If the user force kills the app and relaunches it 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.

Configuring Session timeout limit


Configure Session timeout limit

Session inactivity time limit can be configured upto 60 min. To configure this time kindly update to SDK v5.2.9 post which you can either reach out to us on [email protected] or you can follow the steps mentioned below

Note: This capability is currently supported for Native - Android and iOS, React native and Flutter.

To update your session timeout limit kindly update your Android SDK to v5.2.9 or above and follow the step below:

WebEngage.sharedInstance().sessionTimeOut = 25
[[WebEngage sharedInstance] setSessionTimeOut:25];

Note : The system puts strict limits on the total amount of time that you can prevent suspension using background tasks. iOS 13 beta has reduced the from-the-foreground value to 30 seconds. On current systems you can expect values like:
a. 3 minutes, when your app has moved from the foreground to the background
b. 30 seconds, when your app was resumed in the background

Hence, in order to set session timeout > 30 seconds, "Background Processing" key must be set under "Background Modes" capability.



You have successfully integrated the WebEngage SDK with your iOS app and are sending user session and system events data to your WebEngage account. Please note that it may take a up to few minutes for your data to reflect on your dashboard.

Please feel free to drop in a few lines at [email protected] in case you have any further queries. We're always just an email away!

So, what's next?

We recommend that you implement the following integrations before releasing your app with WebEngage SDK for the first time: