Push Messaging

Push Notifications are messages that pop up on mobile devices. App publishers can send them at any time; even if the recipients aren’t currently engaging with the app or using their devices.

🚧

Before continuing, please ensure that you have completed all of the steps in Getting started.

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

WebEngage push messaging can be integrated using Apple Push Notification service. To integrate WebEngage in your iOS application, you need to be enrolled in Apple Developer Program.

In order to send push notifications to your iOS users, you will need to upload either your APNs Auth Key or APNs Certificate. We strongly recommend that you create and upload APNs Auth Key for the following reasons:

1. One auth key can be used for all your apps - hence there is no complication of maintaining different certificates for different apps
2. There is no need to re-generate the push certificate every year once it expires.

If you already support push notifications in your app, skip to the section below about uploading your auth key. Note that you may still need to enable background modes.

1. Enable Push and Background Modes Capabilities

Here's how you can go about it:

Step 1: Enter Project Navigator view.

Step 2: Select your main app target from the expanded sidebar or from the dropdown menu, then select the Capabilities tab.

Step 3: If Push Notifications isn't enabled, click the switch to add the "Push Notifications" entitlement to your app. If you are using Xcode 8 or above, ensure that a YOUR-APP-NAME.entitlements file has been added to your project.

Step 4: If Background Modes is not enabled, click the switch and then tick the Remote notifications checkbox. WebEngage uses background modes to track when push messages are received on a user's device before the message is opened.

2. Create APNs Auth Key

The documentation below covers the process of creating the APNs Auth Key to send push notifications to your users. If you intend to use the APNs Certificate instead, please refer to the documentation here.

Follow these steps to create an APNs Auth Key:

Step 1: Log in to the Apple Developer Console and go to Certificates, Identifiers & Profiles.

Step 2: Create a new Auth Key by clicking on the + button on the top right corner.

Step 3: Add a Key Name, and select APNs.

Step 4: Click the Confirm button.

Step 5: On this page, you will be able to download your Auth Key file. Please do not rename this file, and upload it as is to the WebEngage dashboard, as shown in the next section in the documentation below.

Step 6: Locate and copy your Team ID. To do this, click on your name/company name on the top right corner, then select View Account.

3. Upload APNs Auth Key

You need to upload the APNs Auth Key on WebEngage in order to enable WebEngage to send push notifications to your users on your behalf.

The documentation below covers the process of uploading the APNs Auth Key to send push notifications to your users. If you intend to use the APNs Certificate instead, please refer to the documentation here.

Step 1: Log in to your WebEngage dashboard and navigate to Data Platform > Integrations > Push Setup (Configure) > Channels.

Step 2: In Push tab, under the iOS section, select Auth Key as APNs Authentication Type. Upload the APNs Auth Key file that you had downloaded earlier, and paste your Team ID and your app’s Bundle ID. Your app’s Bundle ID can be found in Xcode.

Step 3: Select the default push mode for sending push notifications i.e. Production or Development and then Click Save.

4. Deep Linking

WebEngage SDK supports URL based deep linking. On WebEngage dashboard, you can enter any valid URI while creating your push campaign. It can be an http / https link or a valid custom URI like yourapp://detailpage/1234

To handle custom deep links for more advanced use cases, the app can implement WEGHandleDeeplink in its AppDelegate. If this method is implemented, WebEngage SDK will not handle any deep links (including external links) and will call this method instead. The method will receive the deep link string provided on the dashboard along with the whole push notification payload including any custom data sent via dashboard. You can then implement your own logic of handling deep links.

func WEGHandleDeeplink(_ deeplink: String, userData data: [AnyHashable: Any]) {
	// Your Handling Code
}

- (void)WEGHandleDeeplink:(NSString *)deeplink userData:(NSDictionary *)data;

5. Rich Push Notifications

Before continuing, please ensure that you have completed all steps in Getting started

Following requires iOS 10.0+ & WebEngage SDK Version 4.0.2+

1. Create Notification Service Extension

Here's how you can go about it:

Step 1: In Xcode, navigate to File > New > Target and select Notification Service Extension.

Step 2: Click Next, fill out the Product Name as NotificationService, and click Finish.

Step 3: Click Activate on the prompt shown to activate the service extension. Xcode will now create a new top-level folder in your project with the name NotificationService

2. Create Notification Content Extension

Here's how you can go about it:

Step 1: In Xcode, navigate to File > New > Target and select Notification Content Extension.

Step 2: Click Next, fill out the Product Name as NotificationViewController, and click Finish

Step 3: Click Activate on the prompt shown to activate the content extension. Xcode will now create a new top-level folder in your project with the name NotificationViewController

3. Add WebEngage to all the Targets

Add the following in your Podfile above the 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'
end

# ServiceExtension Target
target 'NotificationService' do
    platform :ios, '10.0'
    pod 'WebEngageBannerPush'
end

# ContentExtension Target
target 'NotificationViewController' do
  platform :ios, '10.0'
  pod 'WebEngageAppEx/ContentExtension'
end

4. Reinitialize the Pods

Navigate to your Xcode project directory and run the following commands to reinitialize the pods.

# Remember to avoid use_frameworks! declaration in your Podfile. Contact us at [email protected] if you face any issue.
# While using Swift, Add Brigding Header as documented here - https://docs.webengage.com/docs/ios-getting-started#section-4-support-for-swift

$ pod deintegrate
$ pod install

5. Update Service and Content Extension Classes

🚧

Bridging Header Required if Extension Targets are using Swift

If you are using Swift in your Extensions Targets, you need to add a Bridging Header file to the Extension Target as described here.

Please ensure that you replace NotificationService.swift & NotificationViewController.swift files in Extension Targets with the names you create, in case you choose different names.

Here's how you can update service and content extension classes:

Step 1: Replace NotificationService with the below code.

// Remember to Add Brigding Header as documented here - https://docs.webengage.com/docs/ios-getting-started#section-4-support-for-swift
// NotificationService.swift file

import UserNotifications
import WebEngageBannerPush

class NotificationService: WEXPushNotificationService { }

// NotificationService.h file
#import <UserNotifications/UserNotifications.h>
#import <WebEngageBannerPush/WEXPushNotificationService.h>

@interface NotificationService : WEXPushNotificationService

@end
 
  
// NotificationService.m file
#import "NotificationService.h"

@implementation NotificationService
    
@end

Step 2: Replace NotificationViewController with the below code.

// Remember to Add Brigding Header as documented here - https://docs.webengage.com/docs/ios-getting-started#section-4-support-for-swift
// NotificationViewController.swift file

import UIKit
import UserNotifications
import UserNotificationsUI
import WebEngageAppEx

class NotificationViewController: WEXRichPushNotificationViewController { }

// NotificationViewController.h file
#import <UIKit/UIKit.h>
#import <UserNotifications/UserNotifications.h>
#import <UserNotificationsUI/UserNotificationsUI.h>
#import <WebEngageAppEx/WEXRichPushNotificationViewController.h>

@interface NotificationViewController : WEXRichPushNotificationViewController

@end

  
// NotificationViewController.m file
#import "NotificationViewController.h"

@implementation NotificationViewController

@end

5.1 Addition step for swift users

WebEngageBannerPush & WebEngageAppEx Both libraries are developed in Objective c from Webengage

If you want to import this both libraries inside your swift project There are 2 ways as mentioned below

Solution 1 (Bridging Header): Create Bridging header inside your Target respectively (NotifcationSevice, NotificationViewController) Folder linked to Target
Import Objective c Webengage Header inside Bridging header
All Banner related class will be automatically accessible inside NotificationService class

Solution 2 (use_framworks!): You can include use_frameworks! Inside your pod file under all Targets
This will allow you to import Objective C modules from the Pods Without creating Bridging header
In this approach you need to write import statement in swift file itself as shown in below code

6. Create App Groups for all Targets

Here's how you can go about it:

Step 1: Enter Project Navigator view.

Step 2: Select your main app target from the expanded sidebar or from the dropdown menu, then select the Capabilities tab.

Step 3: If App Groups isn't enabled, click the switch to add the "App Groups" entitlement to your app. If you are using Xcode 8 or above, ensure that an YOUR-APP-NAME.entitlements file has been added to your project.

Step 4: Add an App Group container and specify its name. We recommend using this format: group.<your-bundle-identifier>.WEGNotificationGroup. Make sure this App Group is in use by ticking the checkbox against it.

Step 5: Select the NotificationService target from the expanded sidebar or from the dropdown menu, then select the Capabilities tab. Click on the checkbox against the added App Group and tick it.

Step 6: Do the same for NotificationViewController target. Select the NotificationViewController target from the expanded sidebar or from the dropdown menu, then select the Capabilities tab. Click on the checkbox against the added App Group and tick it.

7. Configure ServiceExtension-Info.plist

Here's how you can go about it:

Step 1: Add App Transport Security Settings key under Information Property List in both NotificationService Info.plist files.

Step 2: Set Allow Arbitrary Loads to YES under App Transport Security Settings.

• Not required if you are sure that image URLs provided on WebEngage dashboard will always use https.

Here's a final Screenshot of ServiceExtension-Info.pilst:

8. Configure ContentExtension-Info.plist

Here's how you can go about it:

Step 1: Open the Info.plist file for NotificationViewController

• Expand NSExtension > NSExtensionAttributes

• Look for UNNotificationExtensionCategory under NSExtensionAttributes. Add it if it is not present and set the type as Array In the Array items, add:
  a. WEG_CAROUSEL_V1
  b. WEG_RATING_V1
  c. WEG_RICH_V1
  d. WEG_RICH_V2
  e. WEG_RICH_V3
  f. WEG_RICH_V4
  g. WEG_RICH_V5
  h. WEG_RICH_V6
  i. WEG_RICH_V7
  j. WEG_RICH_V8

Step 2: Set UNNotificationExtensionDefaultContentHidden under NSExtensionAttributes to YES

Step 3: Add App Transport Security Settings key under Information Property List in both NotificationService and NotificationViewController Info.plist files. Set Allow Arbitrary Loads to YES under App Transport Security Settings in both these files.

• Not required if you are sure that image URLs provided for push on WebEngage dashboard will always use https.

🚧

Please Note

Keys declared in ServiceExtension-Info.plist & ContentExtension-Info.plist are different.

Avoid the common error of declaring NSExtension keys under ServiceExtension-Info.plist
NSExtension keys should only be in ContentExtension-Info.plist.

ServiceExtension-Info.plist should only contain Allow Arbitrary Loads keys (if required).

Source Code snippet of ContentExtension-Info.pilst:

<key>NSExtension</key>
	<dict>
		<key>NSExtensionAttributes</key>
		<dict>
			<key>UNNotificationExtensionCategory</key>
			<array>
				<string>WEG_CAROUSEL_V1</string>
				<string>WEG_RATING_V1</string>
				<string>WEG_RICH_V1</string>
				<string>WEG_RICH_V2</string>
				<string>WEG_RICH_V3</string>
				<string>WEG_RICH_V4</string>
				<string>WEG_RICH_V5</string>
				<string>WEG_RICH_V6</string>
				<string>WEG_RICH_V7</string>
				<string>WEG_RICH_V8</string>
			</array>
			<key>UNNotificationExtensionDefaultContentHidden</key>
			<true/>
			<key>UNNotificationExtensionInitialContentSizeRatio</key>
			<real>1</real>
		</dict>
		<key>NSExtensionMainStoryboard</key>
		<string>MainInterface</string>
		<key>NSExtensionPointIdentifier</key>
		<string>com.apple.usernotifications.content-extension</string>
	</dict>

FinalScreenshot of ContentExtension-Info.pilst:

🚧

Please Note

If you are using WebEngage iOS SDK version below 3.5.8, add WEG_APP_GROUP key in the Info.plist files of all the three targets: main app, NotificationService and NotificationViewController. Set the App Group name created in Create App Groups step for all targets step as the value of this key.

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!