In-app messages

Incorporate in-app messages to send dynamic, personalized content to people using your app. With in-app messages, you can speak directly to your app’s users when they use your app.

This page is part of a setup flow for the SDK. Before you continue, make sure you've implemented previous features—i.e. you can't receive in-app notifications before you identify people!

graph LR getting-started(Install SDK) -->B(Initialize SDK) B --> identify(identify people) identify -.-> track-events(Send events) identify -.-> register-token(Register
Device Token) register-token -.-> push(Receive push) register-token -.-> rich-push(Receive Rich Push) track-events --> test-support(Write tests) push --> test-support rich-push --> test-support identify -.-> in-app(Receive in-app) in-app --> test-support click getting-started href "/docs/sdk/ios/getting-started/#install" click B href "/docs/sdk/ios/getting-started/#initialize-the-sdk" click identify href "/docs/sdk/ios/identify" click track-events href "/docs/sdk/ios/track-events/" click register-token href "/docs/sdk/ios/push" click push href "/docs/sdk/ios/push" click rich-push href "/docs/sdk/ios/rich-push" click in-app href "/docs/sdk/ios/in-app" click test-support href "/docs/sdk/ios/test-support" style in-app fill:#B5FFEF,stroke:#007069

How it works

An in-app message is a message that people see within the app. To set up in app messaging, install and initialize the Tracking and MessagingInApp packages.

People won’t see your in-app messages until they open your app. If you set an expiry period for your message, and that time elapses before someone opens your app, they won’t see your message.

You can also set page rules to display your in-app messages when people visit specific pages in your app. However, to take advantage of page rules, you need to use screen tracking features. Screen tracking tells us the names of your pages and which page a person is on, so we can display in-app messages on the correct pages in your app.

graph LR a[app user triggers
in-app message]-->d{is the app open?} d-->|yes|f[user gets message] d-->|no|e[hold message
until app opens] e-->g{did the message
expire?} g-->|no, wait for user
to open the app|d g-->|yes|h[user doesn't
get the message]

Set up in-app messaging

Use Swift Package Manager to install the MessagingInApp package. See Getting Started for installation instructions. Initializing your app with the MessagingInApp package sets up your app to receive in-app messages.

 You no longer need your Organization ID

If you enabled in-app support before January 26, 2023, you used your organization-id when configuring our SDKs so that you could send in-app messages. You can leave this code in your SDK configuration, but it’s no longer necessary; you can send in-app messages without it.

Page rules

You can set page rules when you create an in-app message. A page rule determines the page that your audience must visit in your app to see your message. However, before you can take advantage of page rules, you need to:

  1. Track screens in your app. You can add $0.autoTrackScreenViews = true to your CustomerIO.config to automatically track screens or you can track screens manually.
  2. Provide page names to whomever sets up in-app messages in If we don’t recognize the page that you set for a page rule, your audience will never see your message.

The SDK automatically uses the class name of UIViewController, minus ViewController, as the name of each page. For example, if you wanted to display an in-app message on a class called EditProfileViewController, you would enter EditProfile as your page rule.

 Make sure your screens use the same names across your apps

If you have a screen called DashboardActivity in Android, and DashboardViewController in iOS, we’ll recognize Dashboard as the screen for both platforms, making it easier for you to set page rules and track events for users across platforms.

Set up page rules to limit in app messages by page
Set up page rules to limit in app messages by page

Keep in mind: page rules are case sensitive. If you’re targeting your mobile app, make sure your page rules match the casing of the name in your screen events. If you’re targeting your website, your page rules should always be lowercase.

The first page rule is Web contains /dashboard. The second page rule is iOS contains Dashboard.
The first page rule is Web contains /dashboard. The second page rule is iOS contains Dashboard.

Targeting people with in-app messages

Whoever composes messages in your system needs to know how you identify people—whether you recognize people by email address or ID.

When you set up a message in, you’ll set a To field. This field is the identifierThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace. that your app uses to identify people in When a person in your campaign or broadcast is identified by the value in the To field, they’ll receive your message. If your app doesn’t identify people using the value you select, we won’t deliver your message to the person. Your messages will appear as Sent, but never Opened or Clicked.

You can open deep links when a user clicks actions inside in-app messages. Setting up deep links for in-app messages is the same as setting up deep links for push notifications.

Handle responses to messages (event listeners)

You can set up event listeners to handle your audience’s response to your messages. For example, you might run different code in your app when your audience taps a button in your message or when they dismiss the message without tapping a button.

You can listen for four different events:

  • messageShown: a message is “sent” and appears to a user
  • messageDismissed: the user closes the message (by tapping an element that uses the close action)
  • errorWithMessage: the message itself produces an error—this probably prevents the message from appearing to the user
  • messageActionTaken: the user performs an action in the message.
import CioMessagingInApp
import CioTracking 

CustomerIO.initialize(siteId: workspaceId, apiKey: apiKey, region: Region.US)

MessagingInApp.initialize(eventListener: self)

extension YourClass: InAppEventListener {
    func messageShown(message: InAppMessage) {}
    func messageDismissed(message: InAppMessage) {}
    func errorWithMessage(message: InAppMessage) {}
    func messageActionTaken(message: InAppMessage, actionValue: String, actionName: String) {}

Handling custom actions

When you set up an in-app message, you can determine the “action” to take when someone taps a button, taps your message, etc. In most cases, you’ll want to deep link to a screen, etc. But, in some cases, you might want to execute some custom action or code—like requesting that a user opts into push notifications or enables a particular setting.

In these cases, you’ll want to use the messageActionTaken event listener and listen for custom action names or values to execute code. While you’ll have to write custom code to handle custom actions, the SDK helps you listen for in-app message events including your custom action, so you know when to execute your custom code.

  1. When you add an action to an in-app message in, select Custom Action and set your Action’s Name and value. The Name corresponds to the actionName, and the value represents the actionValue in your event listener.
    Set up a custom in-app action
    Set up a custom in-app action
  2. Register an event listener for MessageActionTaken, and listen for the actionName or actionValue you set up in the previous step.

     Use names and values exactly as entered

    We don’t modify your action’s name or value, so you’ll need to match the case of names or values exactly as entered in your Custom Action.

  3. When someone receives a message and invokes the action (tapping a button, tapping a message, etc), your app will perform the custom action.

Dismiss in-app message

You can dismiss the currently display in-app message with the following method. This can be particularly useful to dismiss in-app messages when your audience clicks or taps custom actions.

Copied to clipboard!
Current release
Is this page helpful?