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 Swift SDK version is at least 4.2.0

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

• A .p8 push certificate is required to enable Live Activity updates. Refer to the guide below for instructions on generating an Apple .p8 push certificate.

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.

Netmera Live Activity Sample

You can find a sample project below, which you may use as a reference for your implementation.

GitHub - Netmera/Netmera-LiveActivity-Sample: This project demonstrates iOS Live Activities with Netmera integration.GitHub

Step 1: Define the Live Activity Structure

1.1 Configure Info.plist for Live Activity Support

Ensure the following keys are added to your app’s Info.plist

<key>NSSupportsLiveActivities</key>
<true/>
<key>NSSupportsLiveActivitiesFrequentUpdates</key>
<true/>

1.2 Implement ActivityAttributes

Each Live Activity must define its own custom ActivityAttributes struct. For Netmera compatibility, it must conform to NetmeraLiveActivityAttributes.

• netmeraGroupId is required and must be unique per activity. It allows Netmera to group and update the same activity across multiple users with a single request.

• ActivityAttributes defines both static and dynamic properties.

• ContentState holds the dynamic fields that can be updated.

Example:

import Foundation
import ActivityKit
import NetmeraLiveActivity

struct MatchScoreAttributes: ActivityAttributes, NetmeraLiveActivityAttributes {

    var netmeraGroupId: String?
    
    var homeTeamName: String
    var awayTeamName: String
    var homeTeamLogo: String
    var awayTeamLogo: String
    
    public static var activityIdentifier: String = "MatchScoreAttributes"
    
    public struct ContentState: Codable, Hashable {
        var homeTeamScore: Int
        var awayTeamScore: Int
        var matchStatus: String
       
    }
}

Target Membership Requirement

• The file defining the ActivityAttributes struct (e.g., MatchScoreAttributes) must be included in both the main app target (e.g., NetmeraLiveActivitySample) and the widget extension target (e.g., NetmeraLiveActivitySampleWidget).

• In Xcode, select the file and verify under the File Inspector (right-hand panel) that both targets are checked in the Target Membership section.

• Failing to configure this correctly will result in the widget extension being unable to access the ActivityAttributes struct, causing a build error.

Target Membership Configurations

Step 2: Start a Live Activity

You can start an activity remotely or locally:

• Remote: You must call the Netmera.register(forType:name:) method early in your app’s lifecycle, before the push-to-start token is generated, then start an activity using the /rest/3.0/sendBulkNotification endpoint.

• Local: Create an instance of your Live Activity, then use the Netmera.observeActivity method to let Netmera manage token and state updates of your activity.

Remote

To use remote Live Activity registration, iOS 17.2 or later is required.

2.1. Register Activity Type

To enable Live Activity tracking in iOS 17.2 and later, you must register the Live Activity type with Netmera. This allows Netmera to track and associate push tokens for the specified activity type.

Registration Method

Use the Netmera.register(forType:name:) method to register your Live Activity type.

You can call this method:

• Inside application(_:didFinishLaunchingWithOptions:) in your AppDelegate, or

• At an appropriate point in your app’s lifecycle before showing the Live Activity.

Example use case: When a user adds a team to favorites, you can register the related activity type in advance to prepare for future updates.

Example:

if #available(iOS 17.2, *) {
    Netmera.register(forType: Activity<MatchScoreAttributes>.self, name: "MatchScoreAttributes")
}

Once registered, Netmera begins listening for push tokens linked to this activity type.

2.2. Start a Live Activity Remotely via Netmera REST API

You can trigger a Live Activity remotely on iOS devices using Netmera’s REST API. The example below demonstrates starting a Live Activity for tracking a football match score.

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": {
      "homeTeamScore": 0,
      "awayTeamScore": 0,
      "matchStatus": "1st Half"
    },
    "liveActAttr": {
      "homeTeamName": "Arsenal",
      "awayTeamName": "Liverpool",
      "homeTeamLogo": "barcelona_logo",
      "awayTeamLogo": "madrid_logo"
    },
    "liveActAttrType": "MatchScoreAttributes",
    "groupId": "ars-liv-2025"
  },
  "type": "LIVE_ACTIVITY",
  "target": {
    "sendToAll": true
  }
}'

Required Fields

All fields in the liveActAttr object are mandatory:

• groupID

• homeTeamName

• awayTeamName

• homeTeamLogo

• awayTeamLogo

If any of these fields (e.g., awayTeamLogo) are missing, the request will fail, and the Live Activity will not be shown.

Key Parameters

Parameter	Description
type	Must be "LIVE_ACTIVITY" to activate the Live Activity feature.
contentState	Contains dynamic values that can be updated throughout the activity (e.g. score, match status).
liveActAttr	Contains static metadata used in the widget. All fields are required.
netmeraGroupId	A unique ID that groups the same activity across different users.
homeTeamName	Name of the home team to be displayed in the widget.
awayTeamName	Name of the away team to be displayed.
homeTeamLogo	Media identifier for the home team logo.
awayTeamLogo	Media identifier for the away team logo.
liveActAttrType	Must match the name of your ActivityAttributes Swift class/struct.
sendToAll	Set to true to broadcast the activity to all users. You can replace this with custom targeting if needed.

Local

Step 3: Resume Activity Tracking

To ensure Netmera continues tracking Live Activities when the app is reopened:

• If the app is terminated, its connection with the Live Activity is lost.

• To resume tracking token updates or activity state changes, the existing Live Activity must be observed again when the app is relaunched.

• This should be handled inside the application(_:didFinishLaunchingWithOptions:) method of your AppDelegate.

• Doing so ensures that both locally and remotely started activities are properly re-observed on app launch.

Use the following method:

Netmera.resumeObservingActivities(ofType: Activity<MatchScoreAttributes>.self)

Example:

import UIKit
import ActivityKit
import NetmeraLiveActivity

@main
class AppDelegate: UIResponder, UIApplicationDelegate, UNUserNotificationCenterDelegate {

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        Netmera.initialize()
        ...
        
        if #available(iOS 16.1, *) {
            Netmera.resumeObservingActivities(ofType: Activity<MatchScoreAttributes>.self)
        }
        return true
    }
}

Step 4: Update a Live Activity via Netmera REST API

You can update the content of an ongoing Live Activity by sending a REST API request to Netmera:

curl --location 'https://restapi.netmera.com/rest/3.0/update-live-activity' \
--header 'X-netmera-api-key: your_rest_api_key' \
--header 'Content-Type: application/json' \
--data '{
    "groupId": "ars-liv-2025",
    "action": "UPDATE",
    "contentState": {
        "homeTeamScore": 1,
        "awayTeamScore": 0,
        "matchStatus": "2nd Half"
    },
    "priority": 10
}'

Step 5: End a Live Activity via Netmera's REST API

To stop a Live Activity, send an END action request via Netmera REST API:

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

Unregistering a Live Activity

You can stop tracking a specific Live Activity in your app by calling:

Netmera.unregister(name: matchActivity)

Important Notes:

• The name parameter must exactly match the identifier used during registration with Netmera.register(...).

• If the names do not match exactly, the unregistration will not take effect.

• Example use case: When a user removes a football match from their favorites and no longer wants updates on the lock screen or widget, call the unregister method.

You can stop tracking a specific Live Activity using the Netmera.unregister(name:) method.

Debugging Tip

If you encounter the error:

[LiveActivityManagerImpl.swift] 
Cannot observe activity, missing required attribute: netmeraGroupId

It indicates that the netmeraGroupId attribute is missing. Ensure it is correctly provided in your ActivityAttributes structure.

Live Activity Analytics

Netmera tracks three system events for Live Activities. These events help you debug the Live Activity lifecycle and analyse adoption and performance from the panel.

You can see all of these events under:

• Analytics → Event Insight (left navigation), or

• Targeting → User Details → Events tab for a specific user.

Event Overview

Event Name	Event Code	Trigger
LiveActivityStartToken	n:lst	A Live Activity is ready to start and the OS generates a Live Activity start token.
LiveActivityUpdateToken	n:lut	An active Live Activity’s push token changes (e.g., refresh/rotation by the OS).
LiveActivityClose	n:lac	The user closes the Live Activity or it is automatically ended by the system/app.

1. LiveActivityStartToken (n:lst)

Description This event is fired when a Live Activity is about to be started and the system creates a start token for that activity.

2. LiveActivityUpdateToken (n:lut)

Description This event is fired when an existing Live Activity’s push token changes.

3. LiveActivityClose (n:lac)

Description This event is fired when a Live Activity is closed by the user or automatically ended by the system or app (e.g., after a timeout, or when the scenario completes).

Viewing Live Activity Events in the Panel

Event Insight

1. Go to Analytics → Event Insight from the left menu.

2. In the Event filter, search by code:

   • n:lst for LiveActivityStartToken

   • n:lut for LiveActivityUpdateToken

   • n:lac for LiveActivityClose

User Details

1. Go to Targeting → Users and open a specific user profile.

2. Switch to the Events tab.

3. Filter or search within the event list for:

   • LiveActivityStartToken, LiveActivityUpdateToken, or LiveActivityClose