# Mobile Push Campaign

## Overview

Using Engage Studio’s Mobile Push Notification feature, you can send notifications to Android and iOS app users via Firebase Cloud Messaging (FCM).
This guide explains how to configure, send, and verify Android push notifications through the following steps:

1. Define your delivery target and objective
2. Create and configure a campaign
3. Send test messages and verify on devices
4. Confirm delivery, open, and click tracking (Mobile App development is required.)


## Prerequisite

Your Android and iOS app must already be configured with FCM integration and event delivery to Treasure Data.
For implementation details, please refer to the Developer Guide.

- Firebase Cloud Messaging Account
- Apple Developer Account


div
iframe
script
## How to Create a Campaign

In Engage Studio, you can create a new Mobile Push campaign from the Campaigns screen. This section walks you through the process of setting up your first push campaign.

### Creating a Campaign

- Navigate to **Messaging -> Campaigns** from the left navigation bar.
- Click **+ New Campaign** in the upper right corner.
- In the **Create Campaign** dialog:
  - Select **Mobile Push Notification** as the delivery channel.
  - Enter a **Campaign Name** (e.g., “Android Promo Push”).
- Click Create to open the Mobile Push Campaign.


![](/assets/screenshot-2025-11-08-at-22.47.41.f4157888dcca595640ada8b8343b062d3b8f48d3fc940cf0a7df283ac6ccb78b.5be018a0.png)

### Selecting Target Audience

In the Target Audience tab, select Audience Segment.

- Choose an existing Parent Segment from the list and choose Target Segment
- Review the total number of target devices and click Apply.


### Configuring Notification Content

Once the campaign is created, you’ll be taken to the Mobile Push Editor screen.
Here you can define the notification’s appearance, content, and behavior when tapped.

| **Field** | **Description** | **Example** |
|  --- | --- | --- |
| **Title** | The title displayed in the notification bar. Keep concise and clear. | "Exclusive Offer for You!" |
| **Message** | The main message text displayed under the title (1–2 lines recommended). | "Tap to get 20% off your next order." |
| **Image (optional)** | A thumbnail or rich image displayed in the notification. Must be a valid HTTPS URL. | https://cdn.example.com/banner.png |
| **On-Click Behavior** | The On-Click Behavior setting defines what happens when the user taps the notification. | - Open App (default)
- Open Deep Link
- Open Web URL

 |
| **Tips** | - **Emoji Support:** You can insert Unicode emojis directly (e.g., 🎉). Avoid platform-dependent icons.
- Liquid Support: You can insert your attributes defined in output mapping into the content.

 | "{{profile.first_name}}" |


App Implementation Required
For deep links or custom actions, your mobile app must implement link handling logic.
On Android, confirm that the URI scheme is declared in the AndroidManifest.xml (`<intent-filter>`).
On iOS, ensure the scheme or universal link is registered under Associated Domains in Xcode.

![Campaign-Details](/assets/campaign-details.02895a37a2490614734f68ca72ed148baef72af0d5d90e9cecbd65d8086dd9a9.5be018a0.png)

![Mobile Push Notification Editor](/assets/mobile-push-notification-editor.dc73797ed02946998ca0ba4119e95c368b8ea555d2767415eeee47d3b17f6f07.5be018a0.png)

### Selecting Delivery Schedule

In the **Delivery Schedule** tab, under **Schedule**, you’ll find two delivery timing options:

| Option | Description | Typical Use Case |
|  --- | --- | --- |
| **As soon as the campaign is launched** | Sends immediately after you click **Publish** or the activation triggers. | Real-time announcements, flash sales, alerts |
| **At a designated time** | Sends the campaign at a specific future date and time. | Planned promotions or time-based notifications |


💡 Tip
For large campaigns, schedule delivery at least several minutes in advance to allow queue preparation and FCM token validation.

You can optionally receive an email notification once the campaign is sent or completed.

| Field | Description |
|  --- | --- |
| **Email notifications to** | Add one or more recipient email addresses to receive delivery updates. |


![](/assets/notification-settings.311abd9eb0fd7503d7c246c15fccc5f4f9525e7df737fa5d1cd6f89f49eba789.5be018a0.png)

### Selecting Activation

#### Details

The **Activation Details** section defines how Engage Studio connects your Mobile Push campaign to the delivery pipeline.
Here, you specify the technical configuration for message delivery, including authentication, data structure, and parallelism settings.

| **Field** | **Description** | **Example / Notes** |
|  --- | --- | --- |
| **Activation name** | System-generated unique identifier for the activation. Used internally in logs, event tracking, and API calls. | engage_campaign_019a63d178bd748584588f368563db8d |
| **Enable activation actions** | Toggles whether this activation can execute deliveries. When disabled, the campaign remains in Draft even if published. |  |
| **Authentication** | Specifies which authentication (Engage connector) is used for delivery logging. |  |
| **Event ID** | Unique event identifier for tracing logs and delivery events across systems such as delivery-api and Plazma. | 019a63d1-78bd-7485-8458-8f368563db8d |
| **JSON columns** | Defines one or more audience columns that contain JSON-formatted data used for personalized content rendering in Engage Studio. These columns allow dynamic objects (arrays, maps) to be passed directly into message templates. | product_items |
| **Batch size** | Number of records processed per batch when sending notifications. Larger batches increase throughput but may affect reliability. | 1000 (default and max), 1 (min) |
| **Thread count** | Number of parallel threads used for concurrent message sending. Increase for high-volume campaigns. | 1 (default), 10 (max) |


![Activation Details](/assets/activation-details.488324a0b6cedad08fa715659fba1b6d21d60f305d34c4c499ad3b26a4697433.5be018a0.png)

#### Output Column Mapping

Before sending a Mobile Push campaign, Engage Studio must know which audience attributes should be passed to Firebase Cloud Messaging (FCM) or Apple Push Notification Service (APNs). This is configured in the Output Column Mapping section of the campaign editor. Output mapping defines how audience data columns (from the segment or workflow) correspond to delivery payload fields. During campaign execution, Engage Studio dynamically replaces these fields with user-specific values for each recipient record through Liquid syntax (`{{profile.attribute_name}}`).

⚙️ Important Note
The token column in output column name is mandatory for delivery.
FCM and APNs require this field to uniquely identify each target device.

![Output Mapping](/assets/output-mapping.a683a1d5ee64f249ea76b77728a2db3aec171867c9ddd4a605ef6827031f8d28.5be018a0.png)

#### Actions

### Selecting UTM Tracking

- In the campaign editor, open the **UTM Tracking** tab.
- Toggle **Enable Auto UTM Tracking** to **ON**. Once Enabled, all URL link in the content and Web URL link will have URL parameters with these UTM parameters.
- Review or customize the available fields:


| Field | Description | Default Value | Editable |
|  --- | --- | --- | --- |
| utm_id | Internal campaign identifier | campaign_id | ❌ |
| utm_medium | Fixed channel type | push | ❌ |
| utm_source_platform | Identifies Treasure Data as the origin system | treasuredata | ❌ |
| utm_source | Custom source descriptor (e.g., "app", "android") | treasuredata | ❌ |
| utm_campaign | Logical campaign name for analytics grouping | (empty) | ✅ |
| utm_marketing_tactic | Optional tag for marketing objective | (empty) | ✅ |


![UTM Tracking](/assets/utm-tracking.572ab9cdd39fc5d2269a47b523b0006d8af21254cd7bf797711fa7b05e6fa8f9.5be018a0.png)

## Launch Behavior (Campaign Delivery Flow)

When you **click Save and Launch**, Engage Studio automatically prepares and sends your Mobile Push campaign based on the configurations you’ve set.
The following steps describe what happens behind the scenes — and what you, as a marketer, can expect to see in the Console.

### Campaign Delivery Flow

| Step | What Happens | What You Can See / Do |
|  --- | --- | --- |
| 1.Validation | Engage Studio automatically checks all campaign settings before launch — audience, device tokens, authentication, content, and schedule. | If an error is found, the system displays a clear message guiding you to fix it. |
| 2.Audience Preparation | The platform loads your target audience data and prepares each recipient's information for message delivery. | The campaign status changes to **Launching**. |
| 3.Message Generation | Engage Studio builds personalized push notifications for each recipient, combining static content with audience attributes or JSON column data (e.g., product recommendations). | You can preview personalized examples using the **Preview** function. |
| 4.Delivery Execution | Notifications are sent according to your defined schedule — either immediately or at the selected date/time. | The campaign status updates to **Running**. |
| 5.Completion | Once all notifications have been sent, Engage Studio marks the campaign as complete. | The status changes to **Completed**. |
| 7.Email Notification (Optional) | If email notifications are enabled, a delivery summary is automatically sent to your team members. | Useful for sharing delivery results internally. |