In-App Messaging for iOS

Note

This guide applies to in-app messages sent via In-App Automation.

In-app messaging can improve your engagement strategy by providing messages that can be customized to be visually consistent with the the rest of your app. Most customization can be accomplished through the dashboard workflow, however more advanced customization can be obtained by modifying the Urban Airship SDK. This guide outlines how to customize iOS in-app messages.

Feature enablement

Disabling the manager:

[[UAirship inAppMessageManager] setEnabled:false];

The in-app messaging manager can be enabled or disabled. When the manager is disabled it prevents any in-app messages from displaying and pausing the automation engine counting. The manager is enabled by default.

Display interval

Setting the display interval to 10 seconds:

[UAirship inAppMessageManager].displayInterval = 10;

The display interval controls the amount of time to wait before the manager is able to display the next triggered in-app message. The default value is set to 30 seconds but can be adjusted to any amount of time in seconds.

Implementing the UAInAppMessagingDelegate protocol

Example delegate:

-(void)messageWillBeDisplayed:(UAInAppMessage \*)message scheduleID:(NSString \*)scheduleID {
  // Message displayed

}

-(void)messageFinishedDisplaying:(UAInAppMessage \*)message scheduleID:(NSString \*)scheduleID resolution:(UAInAppMessageResolution \*)resolution {
  // Message finished
}

The UAInAppMessagingDelegate can be implemented to receive messages when a message is displayed and finished displaying. This is useful for adding analytic events outside of Urban Airship as well as for further processing of the in-app message.

Fonts

Fonts added to the app bundle are available for use with in-app messaging. To add fonts, please read the The UIKit Custom Fonts Guide.

Customization

In-app messages are fully customizable. Advanced customizations can be provided by implementing the UAInAppMessageAdapterProtocol. The adapter protocol allows one to control how in-app message are created and how they behave during their display lifecycle.

Custom adapters

Example custom adapter:

\@implementation CustomInAppMessageAdapter

+(instancetype)adapterForMessage:(UAInAppMessage \*)message {
    return [[CustomInAppMessageAdapter alloc] initWithMessage:message];
}

-(instancetype)initWithMessage:(UAInAppMessage \*)message {
    self = [super init];

    if (self) {
        // Initialize the adapter
    }

    return self;
}

-(void)prepare:(void (^)(UAInAppMessagePrepareResult))completionHandler {
    // Download any resources for the in-app message before displaying

    // Call the completion handler with the correct result
    completionHandler(UAInAppMessagePrepareResultSuccess)
}

-(BOOL)isReadyToDisplay {
    // Return ready state
    return true
}

-(void)display:(void (^)(UAInAppMessageResolution \*))completionHandler {
    // Display the in-app message

    // Create a message resolution object corresponding to the correct resolution type
    UAInAppMessageResolution \*messageResolution = [UAInAppMessageResolution messageClickResolution];

    // Call the completion handler with the correct resolution
    completionHandler(messageResolution)
}

@end

Set the factory block on the UAInAppMessageManager instance to provide the new adapter:

[self setFactoryBlock:^id<UAInAppMessageAdapterProtocol> \_Nonnull(UAInAppMessage \* \_Nonnull message) {
    return [CustomInAppMessageAdapter adapterForMessage:message];
} forDisplayType:UAInAppMessageDisplayTypeCustom];

Providing an adapter allows defining the behavior of the custom type or overriding any of the default message types. The adapter will be created by the in-app messaging manager when a message's schedule is triggered. Once created, the adapter will be called to first prepare the in-app message, giving the adapter time to download any resources such as images. After the adapter prepares the message, the adapter will be called to display the message.

After the message is displayed, display must be notified that the message is finished displaying by passing a UAInAppMessageResolution into the display method's completion handler. This will allow for subsequent in-app messages to be displayed.

Standard In-App Messages

Implementing the UALegacyInAppMessageFactoryDelegate protocol - example delegate:

\@implementation MessageFactoryDelegate

+(instancetype)messageFactoryDelegate {
    return [[MessageFactoryDelegate alloc] init];
}

-(instancetype)init {
    self = [super init];

    if (self) {
       // Initialize delegate
        [UAirship legacyInAppMessaging].factoryDelegate = self;
    }

    return self;
}

-(UAInAppMessageScheduleInfo \*)scheduleInfoForMessage:(UALegacyInAppMessage \*)message {
    // Provide any changes to the builder
}

\@end

Standard in-app messages delivered through push messages are managed by the legacy in-app message manager. The UALegacyInAppMessageFactoryDelegate provides the requisite functionality for mapping standard messages onto in-app message schedules.

For more information on how to customize this conversion process, see the In-App Messages Migration guide.

Tutorials