Before you begin

This article covers how to use the SDK to send in-app messages with Blueshift. To proceed, you must have the SDK set up in your project and configured in your app. You also need a .pem file to send notifications to your users. Complete those steps before continuing.

Enable in-app messaging

As described in the get started article, you can use the config class to configure the SDK. Add the setEnableInAppNotification method to the same class and set its value to YES to enable in-app messages.

config.enableInAppNotification = true

[config setEnableInAppNotification:YES];

By default, this feature is disabled.

Enable Background Modes

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

Share silent push notification payload to SDK

When an in-app notification is sent from Blueshift, a silent push notification is also sent to the user's device to indicate that a new in-app notification is available. When the app is in the background or foreground state, the SDK fetches the latest in-app notifications upon receiving the silent push and displays them on the device immediately.

Add the following code to your AppDelegate's application(_:didReceiveRemoteNotification:fetchCompletionHandler:) method. This is also covered in the Get Started with SDK document.

extension AppDelegate {
  
    func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
         BlueShift.sharedInstance()?.appDelegate?.handleRemoteNotification(userInfo, for: application, fetchCompletionHandler: completionHandler)
    }
}

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult result))handler {
    [[BlueShift sharedInstance].appDelegate handleRemoteNotification:userInfo forApplication:application fetchCompletionHandler:handler];
}

If you skip this step, the SDK will not show in-app notifications immediately after they are sent from the Blueshift platform. In-app notifications will appear only after the app is closed and reopened.

Show in-app messages on your app's pages

Important

If you are using iOS SDK version 2.1.4 or later, you must register and unregister each page of your app for in-app messages. If you don't register a page, in-app messages will not appear on that page.

To show in-app messages on your app's pages, use the following methods in the ViewController of those pages.

Register the 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])];
}

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 for reference.

SwiftUI support for in-app messages (optional)

If your app uses SwiftUI, use SDK version 2.7.0 or higher to render in-app messages natively within the SwiftUI lifecycle.

Before you begin, ensure your project meets the following minimum requirements:

Requirement	Minimum version
iOS	13.0+
Blueshift iOS SDK	2.7.0+

Step 1: Update your dependency manager

Depending on how you manage packages, follow the relevant instructions below.

CocoaPods

Update your Podfile to use the SwiftUI subspec instead of the core pod:

# Before
pod 'BlueShift-iOS-SDK'

# After
pod 'BlueShift-iOS-SDK/SwiftUI'

Note: The /SwiftUI subspec automatically includes the Core SDK. You do not need both.

Swift Package Manager (SPM)

Open your project settings in Xcode.
Navigate to Package Dependencies.
Ensure BlueShift-iOS-SDK is updated to version 2.7.0 or higher.
Go to Target → Frameworks, Libraries, and Embedded Content and select BlueShift_iOS_SDK_SwiftUI.

Step 2: Enable SwiftUI rendering in App Delegate

To configure the SDK to use SwiftUI rendering instead of the default UIKit overlays, add the following to your App Delegate:

// Enable SwiftUI rendering for In-App messages
if #available(iOS 13.0, *) {
     config?.useSwiftUIForInApp = true
}

Step 3: Register and unregister views

Register your view to receive in-app messages when it appears:

.onAppear {
        BlueShift.sharedInstance()?.registerFor(inAppMessage: String(describing: type(of: self)))
 }

Unregister your view when it disappears:

.onDisappear {
       BlueShift.sharedInstance()?.unregisterForInAppMessage()
 }

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 Identify Blueshift push and in-app deep links to identify:

Whether the deep link comes from the Blueshift SDK or another source.
Other details such as the in-app notification type, clicked button text, and button index.

If everything is configured correctly, you should start seeing in-app messages sent from the Blueshift platform.

Advanced configuration

Use the following sections to modify the default SDK configuration and better control in-app message behavior.

Configure time intervals

By default, the time interval between two in-app messages — from when a message is dismissed to when the next one appears — is one minute. Use the following method to configure this interval during SDK initialization:

//config.blueshiftInAppNotificationTimeInterval  = timeInSeconds 
config.blueshiftInAppNotificationTimeInterval = 120

//[config setBlueshiftInAppNotificationTimeInterval:timeinseconds];
[config setBlueshiftInAppNotificationTimeInterval:120];

Warning: Do not set blueshiftInAppNotificationTimeInterval to 0. Setting it to 0 will cause the in-app notification timer to fail to initialize, and in-app notifications will not be shown.

Trigger in-app messages manually

The SDK fetches in-app notifications from the Blueshift server and displays them on registered screens automatically. To disable automatic display and control it manually, enable the setInAppManualTriggerEnabled configuration during SDK initialization:

config.inAppManualTriggerEnabled = true

[config setInAppManualTriggerEnabled: YES];

To display an in-app notification manually, call the following method on a registered screen. Each call shows one in-app notification to the user.

BlueShift.sharedInstance()?.displayInAppNotification()

[[BlueShift sharedInstance] displayInAppNotification]

Override actions

To receive callbacks for in-app events and override the SDK's default actions, create a class that inherits from BlueShiftInAppNotificationDelegate. In the example below, BlueshiftInAppDelegate is used to receive in-app message callbacks:

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: — Called when the SDK receives an in-app notification and fires the delivered event.
(void)inAppNotificationDidOpen:(NSDictionary *)payload: — Called when the SDK displays an in-app notification on the screen and fires the open event.
(void)inAppNotificationDidClick:(NSDictionary *)payload: — Called when the user performs an action on an in-app notification and the SDK fires the click event.

Implement the following method to override the default in-app action behavior:

(void)actionButtonDidTapped:(NSDictionary *)payloadDictionary: — Called when the user taps an action button on an in-app message. The payload dictionary includes details such as the button type and deep-linking URL. Implementing this method overrides the SDK's default behavior of delivering the deep link via the AppDelegate's application:openURL:options: method. The deep link is instead delivered under the ios_link key in the payloadDictionary parameter. Make sure you process the deep link using values from payloadDictionary.

The payloadDictionary will look like this:

{ "ios_link" : "https://google.com", "type" : "open"}

FAQs

I want to control when the app displays in-app messages. How do I do that?

To control when your app displays in-app messages, do the following:

Enable manual mode to prevent the SDK from displaying in-app messages automatically.
Call the display method whenever you want to show an in-app message.

For more information, see Trigger in-app messages manually.

What happens when I turn manual mode ON?

When you turn on manual mode:

The SDK does not fetch in-app message content when the app launches.
The SDK fetches the content for in-app messages when triggered.
The SDK does not display an in-app message after fetching new content on silent push.
The SDK displays an in-app message only when the host app calls the 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 silent push notification to the device. This 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 the entire process is called background fetch.

What happens if the user revokes notification permission? Will silent push still work for in-app messages?

Yes. Even if a customer denies permission for push notifications, the app still receives silent push notifications. The customer simply does not see them, as the system does not add them to the notification tray.