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**.
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](/developers/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](/docs/campaign/in-app-messages/creating-inapp-templates/creating-inapp-template), 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](/docs/campaign/in-app-messages/creating-inapp-templates/inapp-drag-and-drop). ### Good practices ### Campaign planning recommendations Using a large number of in-app messages in your application can impact rendering time, message delivery, and battery usage. To maintain optimal application performance when using in-app campaigns: - Avoid assigning more than 10 in-app messages to the same trigger event. - Avoid having more than 20 in-app messages active at the same time in your application. - Review and archive in-app campaigns that you no longer need. ### Template construction 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](/docs/campaign/in-app-messages/creating-inapp-templates/creating-inapp-template).
Discover how the predefined in-app templates have been used in [use cases](/use-cases/?ordering=DESC&sortBy=publishDate&filters=tags%3D%3D"predefined+in-app+templates").
3. If you want to create a message from scratch, click **New template**. - Select one of the following builders: - [Code editor](/docs/campaign/in-app-messages/creating-inapp-templates/creating-inapp-template) - [Basic drag & drop builder](/docs/campaign/in-app-messages/creating-inapp-templates/inapp-drag-and-drop) 5. Create the contents of your in-app message according to instructions of the builder selected in step 3 or 4.
If an in-app message contains inserts, it becomes *dynamic* and won't be displayed when the application is in offline mode.
6. Click **Next**. 7. 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. 8. 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. 8. 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.
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.
You must select the original parameter of the event - the event parameters [that were added by using event enrichment](/docs/assets/events/adding-event-parameters#enriching-events-with-data-from-catalogs) 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.
    Synerise performs best with real-time data. This is why you can’t schedule a message for more than 10 days in the future.
  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](/docs/assets/events/event-reference/inapp#inappcapping) 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](/docs/assets/events/event-reference/inapp#inappcapping) is generated. Capping isn't restarted after UUID changes.
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](#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](/docs/assets/events/event-reference/inapp#inappcapping) 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](#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. If the links aren't provided in the [preparelink insert](/developers/inserts/webpush#adding-utm-and-tracking-parameters-to-link), the parameters won't be added to the link in the 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 ---
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. 5. 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.
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, with 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**. The status of in-app messages is available on the list of in-app messages. In the [Communication statuses](/docs/campaign/statuses) article, you can check the statuses which can be assigned to in-app messages.