Creating in-app messages

In this article, you will learn how to create and activate an in-app message.

To find more information on in-app messages in Synerise, see Introduction to in-app messages.

Select audience

In this part of the process, define the conditions a user must meet to be included in the group of recipients of the in-app message.

  1. In the Audience section, click Define.
  2. Select one of the following tabs:
    Everyone - Selecting this option means that the message is directed to all app users (it doesn’t mean the whole customer base).
    • Segmentation - If you have prepared a segmentation or segmentations of recipients before, you can select them in this tab.
      1. Click Select segmentations.
      2. On the pop-up, select one or more segmentations.
      3. Confirm by clicking Apply.
      4. Optionally, if you want to check if a user still belongs to the segmentation right before rendering the in-app message, enable Dynamically check audience condition.
        Important: In such case, the in-app message won’t be available in offline mode.
    • New audience - If you want to define the conditions for the group of recipients from scratch, select this tab.

Create content

In this part of the process, prepare the message you want to display in your mobile application. You can use HTML, CSS, and JS to design the content and layout. If you want to personalize the content of the message, you can use inserts. Additionally, you may perform A/B testing of in-app messages. The message variant is assigned to an app user permanently, which means that the user will only receive one version of the in-app message.

Character limits

If you create a message in an in-app template builder, the message cannot exceed 60,000 characters (this includes the whole message code). This limit applies separately for each variant of a message.

However, there are no character limits to messages created in the basic drag & drop builder.

Good practices

When creating or editing in-app message content:

  • Place the the SRInApp.close() (or SRInApp.hide()) method at the beginning of the JS script.
  • Use try/catch to handle possible fatal errors in the JS script.
  • Handle situations where Jinjava inserts return empty data.
  • When adding external links to your message:
    • Only link to sites you trust.
    • Don’t link to large images that may negatively affect performance.
    • Don’t link to resources whose CSS/HTML may be blocked. If you have resources loaded from your own URLs, set Synerise.settings.inAppMessaging.contentBaseUrl and use relative paths in HTML/CSS.

Creating content

  1. In the Content section, click Define.
  2. Click Create message.
  3. If you want to use predefined in-app templates, go to the Predefined templates folder.
    • Select the template from the list.
      Result: You are redirected to the template editing mode in an in-app template builder.
      Note: Discover how the predefined in-app templates have been used in use cases.
  4. If you want to create a message from scratch, click New template.
  5. From the Display type dropdown list, select the in-app message layout. You can choose one of the following types:
    • Fullscreen
    • Bottom bar
    • Top bar
  6. Create the contents of your in-app message according to instructions of the builder selected in step 3 or 4.
    WARNING: If an in-app message contains inserts, it becomes dynamic and won’t be displayed when the application is in offline mode.
  7. Click Next.
  8. If you want to perform A/B/x test, you can create more variants by clicking the Plus icon icon.
    Message variants are assigned to user’s UUIDs. If a user is logged in on multiple devices, they may be assigned different variants. Resetting the UUID will result in a change of the assigned message variant.
  9. If you performed step 7, in the Allocation sub-section, you can enable:
    • Control group - This option allows you to set up a control group.
      The control group consists of users who will not receive any version of the in-app message. Users are assigned to the control group based on their UUID. If a user is logged in on multiple devices, they may receive the message on some devices if they do not belong to the control group on those devices. Resetting the UUID will result in excluding the user’s UUID from the control group.
    • Equal allocation - Using the slider, you can adjust the size of each variant and the control group.
  10. Confirm by clicking Apply.

Define trigger for the message

In this part of the process, you define which user or system activities launch the in-app message.

The user interface allows selecting up to 3 trigger events, however, in Android, only for 5.8.1 SDK version (released on 28.08.2023) or higher all triggers are considered altogether. For older SDK versions in Android, only the last event from the trigger list will be considered.
These limitations don’t apply in iOS.

  1. In the Trigger events section, click Define.
  2. Click Add event….
  3. From the dropdown list, select an event.
    Important: You must select the events connected with a mobile application. Otherwise, an in-app message may not be displayed to any app user.
  4. Define conditions that the event must meet:
    1. Click where.
    2. From the dropdown list, select an event parameter.
      WARNING: You must select the original parameter of the event - the event parameters that were added by using event enrichment will not trigger the message.
    3. Using logical operators, define the condition of the parameter’s value.
  5. To add more events, repeat steps 2-4.
  6. Confirm by clicking Apply.

Schedule the message display

In this part of the process, plan the time when the in-app message is active and displayed.

  1. In the Schedule section, click Define.
  2. Select one of the following options:
    Run immediately

    1. From the dropdown list, select the time zone consistent with the time zone of your workspace.
    2. If you want to display the message on particular week days, enable Set time windows.
    3. Select the days of the week. To select more than one day, press shift or ctrl (cmd for Mac users).
    4. To select the time of the display on the selected day or days, enable Add time.
    5. In the left field, enter the start time.
    6. In the right field, enter the end time.
    7. Confirm by clicking Apply.

    Scheduled

    1. In the Start field, select the date of in-app message activation.
    2. In the End field, select the date until which the in-app message will be active.
    3. From the dropdown list, select the time zone consistent with the time zone selected for your workspace.
    4. If you want to display the message on particular week days, enable Set time windows.
    5. Select the days of the week. To select more than one day, press shift or ctrl (cmd for Mac users).
    6. To select the time of the display on the selected day or days, enable Add time.
    7. In the left field, enter the start time.
    8. In the right field, enter the end time.
    9. Confirm by clicking Apply.

Define the display settings

In this part of the process, you can set up the priority of the in-app message and define the limits of displaying it.

Priority

The mobile application restricts the display of in-app messages to one at a time. It means that, if several in-app messages are triggered, the system must choose only one to display. In such case, the system chooses the in-app message for display based on the priority assigned to the message (1 being the highest). If several in-app messages with the same priority are triggered, the most recently edited in-app message is displayed.

The rest of in-app messages will be kept in memory, but they may be displayed if:

  • The event that triggers them occurs and they are active
  • The capping limit is not exceeded

Frequency

By default, an in-app message is displayed every time the conditions for its display are fulfilled. To avoid upsetting users, you can define the general frequency of displaying any in-app message or set a limit for a specific in-app message, especially if the trigger conditions are likely to occur often. If the message cannot be displayed to the user due to the frequency limit, the inApp.capping event is generated.

Capping

Capping lets you define a limit on the total number of times a specific in-app message will be shown to a user. Capping is counted separately for each device used by the customer, so if capping is set to 3, the message can be shown 3 times on each customer’s device. If the message cannot be displayed to the user due to capping, the inApp.capping event is generated.
Capping isn’t restarted after UUID changes.

Important: You cannot change capping settings for active and paused in-app message campaigns.

Configuration of display settings

  1. In the Display settings section, click Define.

  2. In the Delay display field, enter the time after which the in-app message will be rendered. The counting starts with the trigger event.

  3. In the Priority index field, enter the priority of the in-app message (choose between 1 and 1000, 1 being the highest).

  4. Optionally, you can specify the frequency of in-app message display within a defined time period.

    • When the message is triggered, the system checks how many times the message has been displayed within the specified period, counting back from the current date.
    • Regardless of which type of time interval you choose (hour, day, week), the time is analyzed in terms of hours. For example, if you select a 1 day period, the last 24 hours are analyzed, if you select 2 days, the last 48 hours are analyzed, and so on.
    • Example: You configured the message to be displayed a maximum of 2 times within 1 day, so the system will track the number of times the message has been displayed in the past 24 hours. If a user was first shown the in-app message on March 3, at 08:23 and then at 14:45, the next in-app can be displayed after March 4, 08:23. If the in-app conditions are met before March 4, 08:23, the message won’t be shown and the inApp.capping event will be generated.
    1. Enable Frequency limit.
    2. In the Show maximum field, enter how many times you want to display the message to a user.
    3. In the In period of field, enter the time span for the limit set in Show maximum.

  5. Optionally, you can set capping on the in-app message. To do so:

    1. Enable Capping limit.
    2. In the Show maximum field, enter the number.

  6. Confirm by clicking Apply.

Define UTM and URL parameters

In this part of the process, you may define UTM and URL parameters which will be attached to the links embedded in the content of the in-app message.

  1. To define UTM parameters, in the UTM & URL parameters section, click Define. If you don’t want to define these parameters, click Skip step.
    1. Fill in the following fields: UTM campaign, UTM medium, UTM source, and UTM term.
    2. Optionally, you can add URL parameters by clicking Add parameters.
    3. Confirm by clicking Apply.

Testing

Important: To test an in-app message, you must integrate with Firebase.

In this part of the process, you may test any variant of your in-app message.

  • For testing purposes, the message is sent to the device by using Google Firebase in order to omit the trigger conditions. This means you can send the test message only to profiles with the has_mobile_push_devices attribute set to true.
  • You can send a test message to up to 15 profiles.
  • The test in-app message always has a greater priority than any active in-app message, so testing serves only for checking the content of the message. It is not meant for testing segmentation conditions, frequency of display, limits, and so on.
  • Test messages are not counted towards capping limits.
  1. In the Test section, click Define.
  2. If your message has more than one variant, select the variant of the message which you would like to use for testing.
  3. In the Select the user you want to send the test message to searchbox, search the recipients by name, surname, email address, custom ID, or UUID.
    Result: A dropdown list with search results appears.
  4. On the dropdown list:
    • if you have saved list of recipients in the past, click the Saved lists tab.
    • if you want to define a one-off list of recipients, select the users to include in your list.
  5. Confirm your choice by clicking Add in the searchbox.
  6. Optionally, to save the list of recipients for future use, click Save list.
    Result: A pop-up appears.
    1. In the List name field, enter the name of the list of recipients.
    2. Confirm by clicking Apply.
      Result: The list is available in the Saved lists tab on the dropdown of searchbox when it’s clicked.
  7. To send the message, click Send test.
    Result: The message is sent immediately.

Adding custom parameters

You can add up to 10 parameters which will be added to every event generated by this communication. Their values are the same for every event in the communication. You can use this, for example, to create a common parameter for events from different types of communication that belong to one marketing campaign.

The list below contains the events to which additional parameters are added:

  • inApp.show,
  • inApp.click,
  • inApp.discard,
  • inApp.capping,
  • inApp.controlGroup,
  • inApp.hide
  • inApp.customHook
  • inApp.renderFail

  1. To define the custom event parameters, in the Additional parameters section, click Define.

  2. Click Add parameter.

  3. In the Parameter field, enter the name of the parameter.
    The following parameters cannot be sent:

    • modifiedBy
    • apiKey
    • eventUUID
    • ip
    • time
    • businessProfileId
    • correlationId
    • clientId
    • uuid

  4. In the Value field, enter the parameter value.
    The value is always sent as a string when the event’s JSON payload is generated. The maximum length of the string is 230 characters.

    WARNING: Dynamic values are not supported in the Parameter and Value fields.

  5. If you want to add more parameters, click Add parameter, and repeat steps 3-4.
    Result: the parameters will be added to all events listed above with the values you entered. This is an example event saved in the database. The custom parameter season is located in the params object: 

    {
  "action": ...
  ...
  "params": {
    "clientId": 1111111111,
    "season": "autumn",
    "campaignName": "Back to school",
    "time": 1662392318050,
    "title": "Have you prepared for coming back to school?",
    "businessProfileId": "xxx"
  }
}

  6. Confirm the settings by clicking Apply.

Activating the message

To activate the message, in the upper right corner click Activate.

😕

We are sorry to hear that

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

😉

Awesome!

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

Close modal icon Placeholder alt for modal to satisfy link checker