Skip to main content

Documentation Index

Fetch the complete documentation index at: https://moengage-getz-tagging-workspace-status.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

MoEngage Transactional Live Activities provide real-time, 1:1 updates on the iPhone Lock Screen and Dynamic Island. Unlike Broadcast Live Activities, which send the same update to many users, Transactional Live Activities deliver personalized updates for time-sensitive user journeys. This feature informs users about food delivery tracking, ride-hailing status, or service appointments without requiring them to unlock their phone or open the app. This article explains how to use MoEngage Inform to create, manage, and analyze these real-time experiences for your transactional use cases. TransactionalLA11.png TransactionalLA22.png TransactionalLA33.png MoEngage supports Live Activities on the following devices:
  • iOS
  • iPad OS
  • Watch OS
  • Ensure your app supports iOS 18 or later. Live Activities do not work on devices running iOS versions earlier than 18.
  • SDK Version: Integrate the MoEngage SDK version 10.02.1 or later. This specific version is required to support Transactional Live Activities.
  • Configure an APNs (Apple Push Notification Service) Auth Key (.p8 file) in your MoEngage account to enable sending.
  • Inform Access: Ensure your MoEngage account has access to the Inform product, as this feature is exclusive to Inform campaigns.
  • Dashboard Permissions: The marketer or user creating the campaign must have role access/permissions enabled for both the Inform and Push modules.
  • Your app developers must implement client-side logic to:
    • Enable Push-to-Start token (PTS token) tracking. Inform uses these tokens to initiate a Live Activity through the API.
      A PTS token is a unique identifier used in push notification systems that allows app servers to send notifications to a device to start a live activity.
    • Define the Live Activity widget UI and unique Attribute Type within the app. MoEngage uses this identifier to target the correct widget for updates.

​
Use Cases

Transactional Live Activities enable various real-time service and engagement scenarios:
  • Delivery and Logistics: Show real-time order status, driver location, and estimated time of arrival (ETA) for food or package deliveries.
  • Service Appointments: Track the arrival of a technician or service provider (e.g., plumber, electrician).
  • Ride Hailing: Display driver details, car make/model, and arrival countdowns.
  • Finance: Visualize the status of a time-sensitive transfer, loan processing step, or authentication request.

​
How Transactional Live Activities Work

Transactional Live Activities display dynamic updates from ongoing events. The system delivers event-based notifications and allows users to track progress directly from their Lock Screen or Notification Center.

​
User Interaction and UI

  • Opt-in: Unlike Broadcast activities, where a user explicitly follows an event, users typically initiate Transactional activities through an action, whether within the app (e.g., placing an order or booking a cab) or outside the app (e.g., initiating offline KYC).
  • Display: The activity appears on the Lock Screen and in the Dynamic Island. A long press on the Dynamic Island expands the view.
  • UI: Your development team customizes the interface, which updates in real time with text, images, and progress indicators based on data sent via MoEngage.

​
Permissions

Live Activities use a separate permission from push notifications. This permission is turned on by default when users install the app. iOS regularly monitors whether Live Activities remain relevant. If a user rarely interacts with them, they might see an option to turn them off. End users must perform the following steps to manage this setting:
  1. Open Settings on their device.
  2. Scroll down and select [App Name].
  3. Tap Live Activities.
  4. Toggle the setting on or off.
image.png Adjusting this setting does not affect other notification preferences.
  • MoEngage tracks Live Activity PTS tokens and permission statuses as device attributes.
  • The MoEngage SDK automatically monitors and updates the Live Activity permission status as a device attribute. This check occurs each time the app is opened in the foreground.
  • Events such as Unsubscribed to Live activity and Subscribed to Live activity are triggered when this permission status changes (the initial permission grant does not trigger Subscribed to Live activity as it is the default state).
  • This feature is not tied to push notification permissions; it is granted by default. The iOS system regularly reviews the usage of Live Activities, and users can disable them at any time.

​
Lifecycle of a Transactional Live Activity

Managing the lifecycle of a Live Activity ensures users receive timely information without screen clutter. Here is how the stages work in practice:
  • Start (Initiation)
    A live activity can be initiated in two ways:
    • You or your developer can initiate a Live Activity remotely via the Inform API (Server-side).
    • The end user can initiate it locally from their device (e.g., immediately upon a button tap). This uses the App SDK in the backend.
Example: A user places a coffee order. The app instantly starts a Live Activity on the device, or your server triggers the Inform API to start the live activity. The widget appears on the Lock Screen showing “Order Placed - Preparing.”
  • Update (Real-Time Status)
    As the event progresses, you send updates to refresh the data on the screen. Updates must be performed exclusively via the Inform API.
Even if the end user started an activity locally via the app, only you or your developer can update it via the API once the token is synced.
Example: The barista finishes the drink. Your backend triggers an Update via the Inform API. The widget updates instantly to show “Ready for Pickup.”
  • End (Completion)
    When the transaction concludes, you must end the activity to remove it from the user’s screen. You or your developer must end the activity exclusively via the Inform API; otherwise, it will be terminated automatically upon reaching the configured dismissal_date.
    Example: The user collects their coffee. Your backend triggers an End API call. The widget displays “Enjoy your coffee!” and then disappears from the screen based on the dismissal time logic.
“Transaction ID” is the key attribute for a live activity for its entire lifecycle. In the example of placing a coffee order, if the order ID is 123, you must use the same transaction ID (123) in the start, update, and end requests to ensure that the same live activity is managed.

​
Types of Transactional Live Activities

MoEngage Inform supports two message types (supported only for iOS) for handling delivery and user reachability:
In this mode, the system attempts to start a Live Activity. If the user is ineligible (e.g., missing PTS token), the request fails, and no notification is shown.Example Scenario: A user orders a meal through a food delivery app and has a valid token.
TimeOrder StatusSystem Actions (Inform API)Widget State
7:00 PMOrder PlacedTrigger Start API with transaction_id: "order_123"The widget appears on the Lock Screen displaying “Preparing your food.”
7:20 PMPicked UpTrigger Update API with transaction_id: "order_123"The widget updates to display “Driver is on the way.”
7:40 PMDeliveredTrigger End API with transaction_id: "order_123"The widget displays “Enjoy your meal!” and is dismissed automatically.

​
Step-by-Step Instructions for Using MoEngage Live Activities

This section details how to set up and utilize MoEngage Transactional Live Activities. You must understand these steps to collaborate effectively with your development teams during implementation.

​
Step 1: Live Activity Registration and PTS Token Management (iOS App Developer Task)

Your application development team must configure Live Activities initially. For more information, refer here.
  1. Enable Live Activity Token Tracking:
    App developers must enable the tracking of Push-to-Start (PTS) tokens. Inform requires these tokens to initiate a Live Activity through the API.
  2. Choose Token Registration Method:
    Developers have two options for managing PTS token registration:
    • Allow the MoEngage SDK to automatically handle PTS token registration and updates.
    • Implement a self-handled PTS token registration process and pass the generated PTS token to the MoEngage SDK.
  3. Define Widget Attribute Types:
    For each distinct Live Activity widget (e.g., order_tracking, ride_status), developers must assign a unique Attribute Type. You will use this identifier in your Inform campaign to target the intended widget.
  • MoEngage tracks Live Activity PTS tokens and permission statuses as device attributes.
  • The MoEngage SDK automatically monitors and updates the Live Activity permission status as a device attribute.

​
Step 2: Create Inform Campaign (Marketer Task)

Unlike Broadcast campaigns, Transactional Live Activities require a configured template in the Inform dashboard before you trigger them. For more information, refer to Create Alert.

​
Step 3: Send Live Activities via API (Developer Task)

Once you configure the Inform campaign, your backend development team can use the Inform API to trigger real-time updates. For more information, refer to the Inform API.
  1. Initiate a Live Activity:
    Send an API request to MoEngage including the live_activity_attributes object with la_type = "start" to initiate a Live Activity for a specific user. Include a unique transaction_id and the required personalization attributes.
  2. Update an Ongoing Live Activity:
    To update an active Live Activity, send an API request with la_type = "update" inside live_activity_attributes, using the same transaction_id. Include the new dynamic content in the request.
  3. End a Live Activity:
    To stop a Live Activity, send an API request with la_type = "end" inside live_activity_attributes, using the same transaction_id. Live Activities also terminate automatically upon reaching the specified dismissal_date.

​
Step 4: Analyze Live Activity Performance in the MoEngage UI

You can track and analyze the performance of your Transactional Live Activity campaigns in the MoEngage Inform Analytics dashboard. This view provides a comprehensive breakdown of delivery funnels, errors, and user engagement metrics. For more info, refer to Analyze Inform.
  • Event Tracking: The system tracks successful initiations on the device via the MOE\_LIVE\_ACTIVITY\_STARTED SDK event. However, Update and End requests do not generate device-level confirmation events; their success is measured by the Sent metric (APNs acceptance).
  • Logs: Live Activity requests in the Inform UI logs will show DELIVERY INFO NA, as the system does not track granular delivery status for individual update/end API calls.

​
FAQs

The fallback push notification is triggered when the tokens required to deliver a Live Activity are unavailable. This behavior applies in the following scenarios:
  • Start Requests: When a valid Push-to-Start (PTS) token is unavailable for the user (for example, if the device is running an unsupported iOS version or the token has not synced).
  • Update/End Requests: When the start request with the same transaction ID did not result in a successful request to start live activity with APNS.
Note: The fallback is not triggered if valid tokens exist, but the delivery fails due to errors returned by APNs (such as payload rejections).
No. A transactional live activity started via MoEngage integration can only be updated or ended via the Inform API.
No. MoEngage does not perform asynchronous retries for Live Activity requests, as the iOS push client handles immediate retries for delivery.
End users must have iOS 18 or a later version installed on their devices to view Live Activities sent through MoEngage.
No. MoEngage acts as the data pipeline. Your iOS developers build the visual design of the widget using SwiftUI within the app. You map data to that widget using the Attribute Type and Key-Value pairs in the MoEngage Dashboard.
A/B testing is not supported for Live Activities in the current version. This also applies to other advanced features like Locales, Global Control Group, and Campaign Control Group.
Your app developers can either allow the MoEngage SDK to manage PTS token registration and maintenance automatically or handle this process themselves and then pass the token to the SDK. MoEngage tracks the PTS token as a device attribute.
A staleDate is the time when the system marks your activity’s content as outdated. When reached, the UI can change to a stale state, like grayed-out text or a message such as “Update needed.” The activity remains visible and active but signals that the information may no longer be current.
A dismissDate is the time you set for the Operating system to automatically remove a Live Activity from the Lock Screen and Dynamic Island. The system dismisses a Live Activity when:
  • The user swipes it away.
  • The dismissDate is reached. By default, the system dismisses it 4 hours after the Live Activity ends or 12 hours after it starts.
A staleDate triggers a UI change to indicate outdated content, while a dismissDate removes the activity entirely. The staleDate keeps the activity visible but with a different look, whereas the dismissDate ends and dismisses it from the screen.
A Live Activity runs for a total of 12 hours, with up to 8 hours of active updates and up to 4 hours of post-end activity without updates. After that, the system automatically removes it.

​
Next Steps