In-app notifications SDK for iOS

This page details how to add in-app notification support with Ortto’s iOS software development kit (SDK). In-app notifications are capture widgets shown on mobile devices.

Because in-app notifications are a type of widget, they do not require the customer or contact to opt-in to receive them. You simply need to configure your app to support in-app notifications and create a popup widget configured to display on iOS devices in Ortto.

The following instructions assume you already have the Ortto SDK installed into your iOS application.

Prerequisites

The Ortto SDK for iOS (≥ v1.5). Installation instructions can be found here.

Prepare a popup widget in Ortto

In addition to following the in-app notification SDK guide below, you will need to create a new or configure an existing popup-type capture widget in Ortto.

The popup widget needs to be configured to include iOS under the Platform and pages setting. Learn more about configuring a popup widget for in-app notifications In-app notifications, under Creating a new capture widget.

Initialize the capture SDK

Depending on whether your application is using SwiftUI or UIKit/Storybook, you need to place the following code block into one of two places.

swift
 
try! OrttoCapture.initialize(
    dataSourceKey: "<Datasource ID>",
    captureJsURL: URL(string: "<Capture JS URL>"),
    apiHost: URL(string: "<API endpoint>")
)

In both cases, you will need to import OrttoCaptureSDK. Read the relevant section below to view the copyable code.

SwiftUI

Add the initialization call to the .onAppear callback of your ContentView.

swift
 
var body: some Scene {
        WindowGroup {
            ContentView()
                .onAppear {
                    try! OrttoCapture.initialize(
                        dataSourceKey: "<dataSourceKey>",
                        captureJsURL: URL(string: "<captureJsURL>"),
                        apiHost: URL(string: "<apiHost>")
                    )
                }
        }
    }

UIKit/Storybook

Add the initialization call to your AppDelegate callback didFinishLaunchingWithOptions.

swift
 
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // ...
		// Other initialization code


		try! OrttoCapture.initialize(
		    dataSourceKey: "<dataSourceKey>",
		    captureJsURL: URL(string: "<captureJsURL>"),
		    apiHost: URL(string: "<apiHost>")
		)


    return true
}

Trigger in-app notifications from push notifications

In-app notifications can be triggered from push notifications, when configured correctly within Ortto and via the SDK.

To trigger an in-app notification from a push notification, in Ortto you need to:

1. Create a popup-type capture widget.
2. Create a push notification.
3. In the push notification, set the primary action to Show widget and select the relevant popup widget.

For more detailed setup instructions, read In-app notifications, under Creating a new capture widget.

When both the push notification and popup widget are switched ON, they will be linked so that when a user clicks on the push notification, it will trigger the popup widget to show.

Manually show or queue in-app notifications

When you have created a popup-type capture widget in Ortto (and it is turned ON), you can choose to manually show or queue the widget.

You will need the widgetId, which you can find in the widget URL in Ortto. For example:

To queue a widget to be shown at a later time (e.g. when the user foregrounds the application):

swift
 
OrttoCapture.shared.queueWidget("<widgetId>")

To show a widget immediately:

swift
 
OrttoCapture.shared.showWidget("<widgetId>")

To start processing any queued widgets (they will begin to show after a short delay):

swift
 
OrttoCapture.shared.processNextWidgetFromQueue()