Send in-app messages

This article provides steps on how you can use Blueshift's SDK to send messages to your iOS app's users when they are using the app.

📘

Wait. Are you ready for this part?

In this article, we'll show you how you can use the SDK to send in-app messages with Blueshift. However, you cannot proceed until you already have the SDK in your project and you can use it in your app. In addition, we also need a .pem file to send notifications to your users. If you are not aware of any of it, then we suggest that you go through those things first, perform those steps, and then come back here to let us send in-app messages to your users.

If you have come this far, then you know that this works. :relaxed:

Enable in-app messaging

If you look at the get started article, we have described the values of the config class that you can use to configure the SDK. In the same class, you can add setEnableInAppNotification method and set its value to YES to enable in-app messages from our iOS SDK.

config.enableInAppNotification = true
[config setEnableInAppNotification:YES];

By default, this feature is disabled.

Show in-app messages on your app's pages

📘

Important

If you are using iOS SDK version 2.1.4 or later, you need to specifically register and unregister each page of your app for in-app messages. If you don't register each page for in-app messages, the in-app messages will stop showing up for pages that are not registered.

To show in-app messages on your app's pages, use the following method in the ViewController of those pages. When you use these methods in the ViewController of these pages, you register these pages with the SDK.

Use the following method to register a ViewController before using it.

override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    BlueShift.sharedInstance()?.registerFor(inAppMessage: String(describing: type(of: self)))  
}
- (void)viewDidAppear:(BOOL)animated {
    [super viewDidAppear:animated];
    [[BlueShift sharedInstance] registerForInAppMessage: NSStringFromClass([ViewControllerClass class])];
}

Use the following method to unregister the ViewController after using it:

override func viewDidDisappear(_ animated: Bool) {
    super.viewDidDisappear(animated)
    BlueShift.sharedInstance()?.unregisterForInAppMessage()
}
-(void) viewDidDisappear:(BOOL)animated {
    [super viewDidDisappear:animated];
    [[BlueShift sharedInstance] unregisterForInAppMessage];
}

You can also use the BaseViewController approach to implement this across the application. Refer to this sample swift project BaseViewController class to understand more.

Deep links

The Blueshift iOS SDK supports deep links for push and in-app notifications. If a deep-link URL is present in the push or in-app message payload, the Blueshift SDK calls the AppDelegate application:openURL:options: method on notification click/tap action and delivers the deep link there.
Write business logic in your app to process the delivered deep link and navigate to the respective screen or page inside the app.

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
     // Handle deep link url
    return true;
}
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options {
    // Handle deep link url
  return YES;
}

See the Identify Blueshift push and in-app deep links document to identify:

  • If the deep link comes from the Blueshift SDK or some other source
  • Other details such as the in-app notification type, clicked in-app notification button text, index etc.

Enable Background Modes

We highly recommend enabling Background fetch and Remote notifications background modes from the Signing & Capabilities. This will enable the app to fetch the in-app notifications if the app is in the background state.

If everything is configured correctly so far, you should start seeing in-app messages that are sent from our platform.

Advanced configuration

You can use the following sections to modify the default configuration of the SDK to better control the in-app messages.

Configure time intervals

By default, the time-interval between two in-app messages (the interval when a message is dismissed and the next message appears) is one minute. You can use the following method to configure this interval when the SDK is initialized in the AppDelegate:

//config.blueshiftInAppNotificationTimeInterval  = timeInSeconds 
config.blueshiftInAppNotificationTimeInterval = 120
//[config setBlueshiftInAppNotificationTimeInterval:timeinseconds];
[config setBlueshiftInAppNotificationTimeInterval:120];

❗️

Make sure you do not set the config.blueshiftInAppNotificationTimeInterval to 0 seconds. Setting it to 0 seconds will fail to initialize the in-app notification timer to recursively check and show the in-app notifications.

Disable fetch in-app message content in the background

Normally, the SDK fetches the content of the in-app message when a user launches your app. However, enabling this feature will allow the SDK to fetch the content of the message silently when a user is not using your app. This feature is enabled by default.

If you want to turn it off, you can set its value to NO (Objective-C) or false (Swift).

config.inAppBackgroundFetchEnabled = false
[config setInAppBackgroundFetchEnabled: NO];

When this feature is enabled, the SDK fetches the content, stores it locally, and triggers the in-app display. If you don't want the SDK to trigger the in-app display automatically, implement manual trigger of the in-app messages.

Trigger in-app messages manually

Enable the setInAppManualTriggerEnabled configuration to stop the SDK from fetching in-app content and displaying messages automatically.

config.inAppManualTriggerEnabled = true
[config setInAppManualTriggerEnabled: YES];

You can implement the following methods to manually fetch content from the Blueshift platform with or without enabling the above flag. However, we recommend that you enable the above flag when the SDK is initialized to get a full control on manual in-app messaging.

To perform an in-app API call:

BlueShift.sharedInstance()?.fetchInAppNotification(fromAPI: (() -> Void)? {}, failure: ((Error?) -> Void)?{_ in       
})
[[BlueShift sharedInstance] fetchInAppNotificationFromAPI:^(){
     } failure:^(NSError *error){
}];

To manually display content in-app:

BlueShift.sharedInstance()?.displayInAppNotification()
[[BlueShift sharedInstance] displayInAppNotification]

Override actions

You can use the SDK to implement callbacks to an action a user performs on the in-app message. To use the options of the SDK to get callbacks for in-app events and override default actions of the in-app messages, create a class that inherits from BlueShiftInAppNotificationDelegate. For example, we create BlueshiftInAppDelegate class to receive the callbacks of in-app messages.

let inappNotificationDelegate :BlueshiftInAppDelegate = BlueshiftInAppDelegate()
config.inAppNotificationDelegate = inappNotificationDelegate
BlueshiftInAppDelegate *inAppNotificationDelegate = [[BlueshiftInAppDelegate alloc] init];
[config setInAppNotificationDelegate: inAppNotificationDelegate];

Implement the following callback methods for in-app actions.

  • (void)inAppNotificationDidDeliver:(NSDictionary *)payload:
    Use this method to get a callback when SDK receives an in-app notification and fires delivered event.

  • (void)inAppNotificationDidOpen:(NSDictionary *)payload:
    Use this method to get a callback when SDK displays an in-app notification on the screen and fires the open event

  • (void)inAppNotificationDidClick:(NSDictionary *)payload:
    Use this method to get a callback when the user performs action on an in-app notification on the screen and SDK fires the click event

Implement the following callback methods for the in-app lifecycle events.

  • (void)inAppNotificationWillAppear;
    Use this method to get a callback before the in-app message/notification appears to the user.

  • (void)inAppNotificationDidAppear;
    Use this method to get a callback when the in-app message/notification appears.

  • (void)inAppNotificationWillDisappear;
    Use this method to get a callback when the in-app message/notification is getting dismissed.

  • (void)inAppNotificationDidDisappear;
    Use this method to get a callback after the in-app message/notification is dismissed.

Implement the following method to override the in-app action.

  • (void)actionButtonDidTapped:(NSDictionary *)payloadDictionary :
    Use this method to implement a logic to deep-link pages or show the options to share content when a user taps on an action button of the in-app message/notification. The payload dictionary provides options such as button type and deep-linking URL.
    Implementing this method will override the SDK default behaviour of delivering the deep link in the AppDelegate's application:openURL:options: method and deep link will be delivered under ios_link key in the payloadDictionary parameter of this function. Make sure you process the deep link using values from the payloadDictionary.
    The payloadDictionary should look like below.
    { “ios_link” : “https://google.com”, “type” : “open”}

FAQs

I want to control when the app displays the in-app messages. How do I do that?
To control when your app displays the in-app messages, perform the following steps:

  1. Enable the manual mode to let SDK know that it should not display the in-app messages automatically.
  2. Call the method for displaying the in-app to show in-app message whenever you want the app to show them.
    For more information, see Trigger in-app messages manually.

What happens when I turn the manual mode ON?
When you turn on the manual mode:

  • The SDK does not fetch the content for in-app messages when a customer launches the app
  • The SDK fetches the content for in-app messages
  • The SDK doesn't display an in-app message after it fetches new content on silent push
  • The SDK displays an in-app message only when the host app calls the SDK's displayInAppMessage method. For more information, see Trigger in-app messages manually.

What is background fetch or silent push for in-app messages?
When a new in-app message is available for a customer, the Blueshift server sends a push notification to the device. The push notification tells the SDK to call the in-app API and fetch the latest content. This push notification is called a silent push for in-app messages and this entire process is called background fetch.

What happens if the user revokes the notification permission? Will I be able to get silent push messages for fetching in-app messages?
In case the customer denies the permission for push notifications, the app still receives the silent push notifications. Just that the customer does not see the notifications since the system doesn't add it in the notification tray.


Did this page help you?