App In-line Content

App In-line Content allows you to insert content directly into your app's screen without disturbing the user experience. It also allows you to dynamically update your app's content and run relevant and contextual campaigns.

You may use the In-line Campaigns to change areas of your app or show banner ads based on live triggers and segmentation.

This capability is provided in WebEngage Personalization SDK, a child SDK that handles Inline campaigns.

Installation

For WebEngage Personalization SDK to support inline campaign processing, the parent WebEngage SDK version must be 6.2.0 or higher.

Step 1: Integrate WebEngage SDK by following steps mentioned in this doc.

Step 2: Add WebEngage Personalization SDK to your project.
For installation, add the WebEngage Personalization SDK in your Podfile under your project's target.

pod 'WEPersonalization'

InitializationImport and initialise WebEngage Personalization SDK unit

Add the following initialization code inside the didFinishLaunchingWithOptions method of your AppDelegate class

Note: Initialize post WebEngage iOS SDK initialization.

// Import SDK 
import WEPersonalization
// ..
// ..
// ..
// Initialise SDK
WEPersonalization.shared.initialise()

#import <WEPersonalization/WEPersonalization.h>

[[WEPersonalization shared] initialise];

Configuring property in your application

There are two ways to configure inline properties, which are as follows:

Using WebEngage/Native Views

This implementation will allow you to use WebEngage pre-defined templates (Banner (hyperlink) & Text (hyperlink)) right out of the box, with the SDK handling campaign rendering and tracking stats. In the case of the Custom (hyperlink)template, you can easily obtain data via callbacks(hyperlink) and render your own UI in the same placeholder.

To configure the property on your screen, follow the steps below:

• You can add a placeholder/property to your screen by using WebEngage’s custom view WEInlineView (extends UIView).
  • Create a view in iOS then add a view and then give custom class Class as WEInlineView and Module as WEPersonalization.
  • You can also create a WEInlineView programatically.
  • Give ID/Tag to the view. This identifier will be referred to as Property ID on the dashboard.
    For example, a placeholder view has been added in Interface builder, placeholder_id has been given to the View.

weInlineView.tag = iosPropertyId
weInlineView.load(tag: iosPropertyId, callbacks: self)

[weInlineView loadWithTag:10 callbacks:self];

Recommendation
Declare the view's height, as this will ensure that the resulting campaign is rendered inside the stated height.

Tag your screen

Because properties are attached to screens ViewController, tagging screens with appropriate screen names is a required step for Inline personalization to function properly.

@Override
override func viewWillAppear(_ animated: Bool) {
    weAnalytics?.navigatingToScreen(withName: "screen_name")
    //Callbacks to be configured after screen navigation step.
}

- (void)viewWillAppear:(BOOL)animated{
    id weAnalytics = [WebEngage sharedInstance].analytics;
    [weAnalytics navigatingToScreenWithName:@"screen"];
}

Without adding property in interface builder and rendering complex UI

Another method for creating complex views is to use WebEngage's Custom (hyperlink) template option from the dashboard. This allows you to register your property (not necessary a part of your XML) with WebEngage and obtain campaign data to build your own UI; however, this only allows you to obtain data; you must still track impressions and clicks by referring the steps mentioned here (link to impression tracking and click).

Note: This is not supported for Banner and Text templates rendering through P-SDK.

To configure the property on your screen, follow the steps below:

• Implement WEPlaceholderCallback inside your class

• SwiftObjective C

  extension ClassName : WEPlaceholderCallback{
      public func onRendered(data: WEGCampaignData) {
      
      }
  
      public func onDataReceived(_ data: WEGCampaignData) {
          
      }
  
      public func onPlaceholderException(_ campaignId: String?, _ targetViewId: String, _ exception: Error) {
          
      }
              
  }
  

  //inside viewcontroller.h
  @interface ViewController : UIViewController<WEPlaceholderCallback>
  @end
  
  //inside viewcontroller.m
  -(void)onDataReceived:(WECampaignData *)data{
     
  }
  
  - (void)onRenderedWithData:(WECampaignData *)data{
     
  }
  
  -(void)onPlaceholderException:(NSString *)campaignId :(NSString *)targetViewId :(NSError *)exception{
  }
  
  

• Register your property by passing the ID/TAG (or any other unique property identifier) through WEPlaceholderCallbacks (hyperlink), inside the viewWillAppear method and after calling screenNavigated

override func viewWillAppear(_ animated: Bool) {
  weAnalytics?.navigatingToScreen(withName: "screen")
  WEPersonalization.shared.registerWEPlaceholderCallback(iosPropertyId, self)
}

- (void)viewWillAppear:(BOOL)animated{
    id weAnalytics = [WebEngage sharedInstance].analytics;
    [weAnalytics navigatingToScreenWithName:@"screen"];
    [[WEPersonalization shared] registerWEPlaceholderCallback:iosPropertyId :self];
}

• After registering the property, you can obtain the data (key-value) pairs inside onDataReceived function of WEPlaceholderCallbacks, post that you can render your own UI using the same data (hyperlink to WECampaignData). Do track the Impression and configure Click (hyperlink) according to your use case.

@Override
public func onDataReceived(_ data: WEGCampaignData) {
  //Build your own UI using the data
}

-(void)onDataReceived:(WECampaignData *)data{
   //Build your own UI using the data
}

Callbacks

There are two types of callbacks available in Personalization SDK

WECampaignCallback: Campaign callbacks

Callbacks can be registered globally in the AppDelegate or locally in the Controller. This will be triggered throughout the campaign's lifecycle.

Register your callback whether in AppDelegate or viewDidLoad method of your screen Controller.

WEPersonalization.shared.registerWECampaignCallback(self)

[[WEPersonalization shared]registerWECampaignCallback:self];

Following are the callback methods available in WECampaignCallback

• onCampaignPrepared : This is the first callback method that is triggered when data for the qualified campaign is retrieved from the WebEngage servers. You can also stop rendering the campaign by calling stopRendering() method of WECampaignData, generally this can come handy if you want to just retrieve some data and render on your own for templates like Banner and Text also. While this will always be called for your templates (banner, text and custom).
• SwiftObjective C

  func onCampaignPrepared(_ data: WEGCampaignData) -> WEGCampaignData {
    // You will get data received for campaign  
    return data
  }
  

  -(WECampaignData *)onCampaignPrepared:(WECampaignData *)data{
    // You will get data received for campaign
      return data;
  }
  

• onCampaignShown : When the SDK displays the Campaign on the screen, this callback is triggered. This will only be triggered for Banner and Text templates, not Custom templates, because they are handled by your application, and in cases where you have called stopRendering.

func onCampaignShown(data: WEGCampaignData) {
  //Campaign Shown
}

-(void)onCampaignShown:(WECampaignData *)data{
  //Campaign Shown
}

• onCampaignClicked : This callback will get triggered when clicked on the campaign view rendered by the SDK. This will only be triggered for Banner and Text templates, not Custom templates, because they are handled by your application. Handle your deeplinks in this method; returning false results in automatic redirection because the SDK will handle and attempt to open the link, whereas returning true instructs the SDK not to perform any redirection because the application will handle the same.

func onCampaignClicked(actionId: String,
                       deepLink: String,
                       data: WEGCampaignData) -> Bool{
      // Returning true would not redirect automatically to action Url. Write your redirection code here and return false. 
      // Returning false would open Action Url in Browser
    return false; 
}

- (BOOL)onCampaignClickedWithActionId:(NSString *)actionId deepLink:(NSString *)deepLink data:(WECampaignData *)data{
    return true;
}

• onCampaignException : This callback will get triggered when the campaign retrieval/showing will get failed.

func onCampaignException(_ campaignId: String?,
                         _ targetViewId: String,
                        _ exception: Error)
  // Exception occurred
}

- (void)onCampaignException:(NSString *)campaignId :(NSString *)targetViewId :(NSError *)exception{
    
}

WEPlaceholderCallback: Placeholder Callbacks

You can subscribe to the callbacks basis on placeholder views created with property id to receive updates and respective data in the callback methods. This callback is generally recommended for registering properties as mentioned above (Without adding property in interface builder and rendering complex UI) and if you want to get property wise updates.

Register your callback/property by passing the ID/TAG (or any other unique property identifier) through WEPlaceholderCallback (hyperlink), inside the viewWillAppear method of your Controller and after calling screenNavigated.

@Override
override func viewWillAppear(_ animated: Bool) {
     weAnalytics?.navigatingToScreen(withName: "Screen_Name")
     WEPersonalization.shared.registerWEPlaceholderCallback(iosPropertyId,self)
}

- (void)viewWillAppear:(BOOL)animated{
    id weAnalytics = [WebEngage sharedInstance].analytics;
    [weAnalytics navigatingToScreenWithName:@"screen"];
    [[WEPersonalization shared] registerWEPlaceholderCallback:1002 :self];
}

Following are the callback methods available in WEPlaceholderCallback

• onDataReceived : This callback will get triggered when the campaign data will be received for Placeholder View. For Custom templates, you can obtain the data (key-value) pairs and can render your own UI using the same data (hyperlink to WECampaignData). Do track the Impression and configure Click (hyperlink) according to your use case. This will be called for all the templates Banner, Text and Custom available in WebEngage’s dashboard.

public func onDataReceived(_ data: WEGCampaignData) {
  //Build your own UI using the data
}

-(void)onDataReceived:(WECampaignData *)data{
    
}

• onRendered : When the SDK displays the Campaign on the screen, this callback is triggered. This will only be triggered for Banner and Text templates, not Custom templates, because they are handled by your application, and in cases where you have called stopRendering through WECampaignCallback.

@Override
public func onRendered(data: WEGCampaignData) {
 // This will be executed when a placeholder view with campaign will be shown
}

- (void)onRenderedWithData:(WECampaignData *)data{
   
}

• onPlaceholderException : This callback will get triggered when the campaign showing for this Property or Placeholder will get failed. If the property is already visible, use this method to hide it or to display some default UI. Kindly refer to Exceptions (hyperlink) for types of exceptions.

public func onPlaceholderException(_ campaignId: String?,
                                   _ targetViewId: String,
                                   _ exception: Error) 
       // This will executed once exception occured
}

-(void)onPlaceholderException:(NSString *)campaignId :(NSString *)targetViewId :(NSError *)exception{
 // This will executed once exception occured
}

Exceptions

You will receive exception details in onCampaignException of WECampaignCallback & onPlaceholderException of WEPlaceholderCallback.

Types of Exception:

WECampaignData

You can access the Campaign Id and Placeholder details like name (id) and content. It consists of the following members

WECampaignContent

The Personalization SDK renders the Banner, Text view through this data. Through this, you can access the custom key-value pairs.

WEInlineView

This is a WebEngage custom view for rendering campaigns and can be directly included in layout XML or can also be initialized programmatically.

Following are the methods available

Unregister the callbacks

This step is just as important as registering for the placeholder and campaign callbacks.

Implement the following code inside viewWillDisappear of your Controller.

override func viewWillDisappear(_ animated: Bool) {

//Unregister Placeholder callback
 WEPersonalization.shared.unregisterWEPlaceholderCallback(ios_property_id)

//Unregister Campaign callback
WEPersonalization.shared.unregisterWECampaignCallback(self)
}

- (void)viewWillDisappear:(BOOL)animated{
     [[WEPersonalization shared] unregisterWECampaignCallback:self];
     [[WEPersonalization shared] unregisterWEPlaceholderCallback:ios_property_id];
}

Record Campaign Viewed and Clicked Event for Custom Views

For Custom Views, Personalization SDK will pass the custom data WECampaignData, which should be managed/rendered by your application only.

Please Note

To record Impression and click data, you must add the below: Record Viewed Impression and Record Click Impression.

Record Viewed Impression

Impression tracking is simply tracking the number of views each campaign receives.
For example, if a user visits the screen and sees a campaign and visits the screen again then they will see the exact same campaign again, two impressions would be counted.

Now, trackImpression will allow you to track impressions for your campaign. Kindly, use the mentioned method of WEGCampaignData once the custom view has been shown on the screen by the application.

Recommendation

WEGCampaignData will be received both in onDataReceived of WEPlaceholderCallback and onCampaignPrepared of WECampaignCallback.

//attributes: any custom dictionary [:] of data you want to record with this event
//data: WEGCampaignData
data.trackImpression(attributes: nil)

//attributes = (NSDictionary<NSString *,id> * _Nullable)
[data trackImpressionWithAttributes:nil];

Record Click Impression

You can track click impressions whenever the user clicks on the campaign view on the screen.

//attributes: any custom dictionary [:] of data you want to record with this event
//data: WEGCampaignData
data.trackClick(attributes: nil)

//attributes = (NSDictionary<NSString *,id> * _Nullable)
[data trackClickWithAttributes:nil];