Live Activities

Live Activities enable apps to display dynamic, real-time updates directly on glanceable areas like the Lock Screen, iPhone StandBy, Dynamic Island, and Apple Watch’s Smart Stack, allowing users to monitor ongoing events, activities, or tasks without constantly reopening the app.

Ideal for tracking short-to-medium-length tasks, Live Activities present prioritized information such as live sports scores, delivery updates, or fitness metrics, and can offer interactive options for user control. For best practices, ensure a concise layout suited to all display locations, avoid sensitive information, and refrain from using Live Activities for advertising, preserving them as a tool for useful, timely updates.

Netmera and Live Activities

To facilitate this feature, Netmera has integrated additional functionalities into the existing message delivery framework specifically designed for Live Activity.

Prerequisites and Setup ⚠️

• Ensure your iOS SDK version is at least 3.24.0

• A .p8 push certificate is required to enable Live Activity updates.

• Starting with iOS 17.2, you can remotely initiate Live Activities via Netmera.

Apple Materials

• Starting and updating Live Activities with ActivityKit push notifications
• Displaying live data with Live Activities
• Human Interface Guidelines for Live Activities

This guide outlines the steps to initiate, update, and end Live Activity with Netmera’s API, enabling dynamic notifications on iOS devices. Below are the essential setup instructions, endpoint examples, and details on how to manage the lifecycle of a Live Acxtivity.

Overview of the Live Activity Process

1. Starter Token Transmission to Netmera

2. Starting the Live Activity

3. Updating the Live Activity with an Update Token

4. Modifying or Ending the Live Activity

   1. Monitoring the Close Event

Step 1: Transmit the Starter Token to Netmera

To initiate a Live Activity, Netmera requires the Starter Token provided by Apple. This token is obtained once the activity is ready to begin and is transmitted to Netmera using the LiveActivityStartToken event.

• Starter Token: This token is essential to start a Live Activity on the user’s device.

Step 2: Start the Live Activity

Using Netmera’s REST API, you can initiate a Live Activity with either sendBulkNotification or sendNotification. Here are examples and descriptions of the parameters used.

2.1 Using sendBulkNotification

The following curl example demonstrates how to start a Live Activity for iOS:

curl --location 'https://restapi.netmera.com/rest/3.0/sendBulkNotification' \
--header 'X-netmera-api-key: your_restapi_key' \
--header 'Content-Type: application/json' \
--data '{
    "message": {
        "title": "Live Activity Start",
        "text": "Here your live activity",
        "platforms": [
            "IOS"
        ],
        "contentState": {
            "emoji": "Apple"
        },
        "liveActAttr": {
            "name": "Constant Value"
        },
        "liveActAttrType": "LiveActivityAttributes"
    },
    "type": "LIVE_ACTIVITY",
    "target": {
        "sendToAll": true
    }
}'

Parameter Descriptions

• contentState: This dynamic, stateful section of the Live Activity is used for updates. In this example, the emoji is set as "Apple". Defined in Swift as:

  struct LiveActivityAttributes: ActivityAttributes {
    public struct ContentState: Codable, Hashable {
      var emoji: String
    }
    var name: String
  }

• liveActAttrType: Specifies the model class used in Swift to define the activity, here set as "LiveActivityAttributes".

• liveActAttr: Contains static content that remains fixed for the Live Activity lifecycle, such as name.

2.2 Using sendNotification

For individual Live Activity notifications, use the createNotificationDefinition API to define the notification, then send it via sendNotification.

1. Define the Notification:

   curl --location 'https://restapi.netmera.com/rest/3.0/createNotificationDefinition' \
   --header 'X-netmera-api-key: your_restapi_key' \
   --header 'Content-Type: application/json' \
   --data '{
       "title": "Live Activity Start",
       "message": "Here your live activity",
       "platforms": [
           "IOS"
       ],
       "contentState": {
           "emoji": "Apple"
       },
       "liveActAttr": {
           "name": "Constant Value"
       },
       "liveActAttrType": "LiveActivityAttributes"
   }'

2. Send the Notification:

   curl --location 'https://restapi.netmera.com/rest/3.0/sendNotification' \
   --header 'X-netmera-api-key: your_restapi_key' \
   --header 'Content-Type: application/json' \
   --data '{
       "notificationKey": "your_notification_key",
       "target": {
           "extId": "your_xid"
       }
   }'

After executing these commands, the Live Activity will appear on the user’s device.

Step 3: Transmit the Update Token to Netmera

Update Token: This token is used to modify an ongoing Live Activity. Once the Live Activity is started, Apple provides an update token. Transmit this token to Netmera using the LiveActivityUpdateToken event, including the group_id.

Step 4: Update or End the Live Activity

Use the update-live-activity API to either modify the content of an existing Live Activity or end it based on the action specified.

Example: Update a Live Activity

curl --location 'https://restapi.netmera.com/rest/3.0/update-live-activity' \
--header 'X-netmera-api-key: your_restapi_key' \
--header 'Content-Type: application/json' \
--data '{
    "groupId": "psg-om",
    "action": "UPDATE",
    "contentState": {
        "emoji": "PSG 3:1 OM"
    },
    "priority": 10
}'

• groupId: Identifier of the Live Activity group.

• action: Defines the operation type (either "UPDATE" or "END").

• contentState: Specifies the updated information within the Live Activity.

Example: End a Live Activity

To end a Live Activity, set the action to END:

curl --location 'https://restapi.netmera.com/rest/3.0/update-live-activity' \
--header 'X-netmera-api-key: your_restapi_key' \
--header 'Content-Type: application/json' \
--data '{
    "groupId": "psg-om",
    "action": "END",
    "priority": 10
}'

Step 5: Monitor Live Activity Closure

When the end-user closes the Live Activity in the notification center, this action should be tracked and reported to Netmera using the LiveActivityClose event with the associated group_id.

Note:

Both the starter and update tokens may change over the lifecycle of the Live Activity. Always ensure Netmera receives the latest token data to maintain updates.