iOS Live Activities

Live Activities zeigen die aktuellsten Daten Ihrer App auf dem iPhone- oder iPad-Sperrbildschirm und in der Dynamic Island an. Diese Funktion ermöglicht es Benutzern, Live-Informationen auf einen Blick zu sehen und schnelle Aktionen im Zusammenhang mit den angezeigten Informationen durchzuführen.

Hier sind einige Beispiele für die Verwendung von Live Activities:

Bestellstatus in einer Liefer-App anzeigen;
Einen Echtzeit-Countdown in einer Trainings-App bereitstellen;
Tracking-Informationen in einer Taxi-App anzeigen;
Spielstatistiken und aktuelle Spielstände in einer Sport-App anzeigen;
Stündliche Vorhersagen in einer Wetter-App bereitstellen.

Sie können Live Activities mit dem Pushwoosh iOS SDK wie unten beschrieben aktivieren. Um Live Activities zu verwalten und deren Inhalt zu aktualisieren, verwenden Sie die Methode /updateLiveActivity.

Einrichtung

Ein neues Ziel erstellen

Gehen Sie zu Datei > Neu > Ziel und wählen Sie Widget Extension.

Konfiguration der Widget Extension Bitte geben Sie einen Namen ein und stellen Sie sicher, dass Sie Include Live Activity auswählen und auf Fertig stellen klicken.

Konfiguration der Info.plist

Suchen Sie die Datei Info.plist im primären Ziel, fügen Sie den Schlüssel “Supports Live Activities” ein und setzen Sie dessen Wert auf YES.

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

Wenn Ihre Live Activity oft aktualisiert wird (z. B. Live-Sportergebnisse), fügen Sie auch NSSupportsLiveActivitiesFrequentUpdates mit dem Wert true hinzu. Apple begrenzt die Anzahl der hochprioren Push-Updates, die eine App pro Stunde senden kann. Dieser Schlüssel erhöht dieses Budget. Informationen zur Steuerung der Lieferpriorität pro Update finden Sie im Parameter apns_priority in der Live Activities API-Referenz.

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

Live Activities aus der App aktivieren

Um Live Activities zu aktivieren, fügen Sie deren Code zu Ihrer bestehenden Widget Extension hinzu oder erstellen Sie eine neue, falls Ihre App noch keine hat. Live Activities verwenden die Funktionalität von SwiftUI und WidgetKit für ihre Benutzeroberfläche. ActivityKit handhabt den Lebenszyklus jeder Live Activity: Die API wird verwendet, um eine Live Activity anzufordern, zu aktualisieren und zu beenden sowie um ActivityKit-Push-Benachrichtigungen zu erhalten. Mehr über Live Activities erfahren Sie in der Apple-Dokumentation.

Navigieren Sie zur ContentView-Datei Ihres Projekts in Xcode und erstellen Sie einen Button

import SwiftUI

struct ContentView: View {
    var body: some View {
        VStack(spacing: 20) {

            Button(action: {
                LiveActivityManager.shared.startActivity()
            }, label: {
                Text("Start Live Activity")
                    .foregroundColor(.white)
                    .padding()
                    .background(Color.blue)
                    .cornerRadius(10)
            })
        }
        .padding()
    }
}

#Preview {
    ContentView()
}

Erstellen Sie eine LiveActivityManager.swift-Datei zur Verwaltung von Live Activities

import Foundation
import ActivityKit
import UIKit
import PushwooshFramework
import PushwooshLiveActivities

class LiveActivityManager: NSObject, ObservableObject {
    public static let shared: LiveActivityManager = LiveActivityManager()

    private var currentActivity: Activity<FoodDeliveryAttributes>? = nil

    override init() {
        super.init()
    }

    func startActivity() {
        guard ActivityAuthorizationInfo().areActivitiesEnabled else {
            print("You can't start live activity.")
            return
        }
        do {
            let pushwooshData = PushwooshLiveActivityAttributeData(activityId: "activity_id")
            let atttribute = FoodDeliveryAttributes(orderNumber: "1234567", pushwoosh: pushwooshData)
            let initialState = FoodDeliveryAttributes.ContentState(
                status: "Preparing your meal",
                estimatedTime: "25 min",
                emoji: "👨‍🍳",
                pushwoosh: nil
            )
            let activity = try Activity<FoodDeliveryAttributes>.request(
                attributes: atttribute,
                content: .init(state:initialState , staleDate: nil),
                pushType: .token
            )
            self.currentActivity = activity

            Task {
                for await pushToken in activity.pushTokenUpdates {
                    let pushTokenString = pushToken.reduce("") {
                        $0 + String(format: "%02x", $1)
                    }
                    print("Activity:\(activity.id) push token: \(pushTokenString)")

                    // MARK: - Push-Token an Pushwoosh senden
                    Pushwoosh.LiveActivities.startLiveActivity(
                        token: pushTokenString,
                        activityId: "activity_id"
                    )
                }
            }
        } catch {
            print("Start Activity Error: \(error.localizedDescription)")
        }
    }
}

Das war’s, jetzt starten wir das Projekt und drücken den ‘Start Live Activity’-Button. Dann navigieren wir zum Sperrbildschirm und sehen die erstellte Live Activity.

Erstellte Live Activity auf dem Sperrbildschirm

Live Activity mit einer Remote-Push-Benachrichtigung starten

Um eine Live Activity über eine Remote-Push-Benachrichtigung zu initiieren, müssen Sie das pushToStartTokenUpdates-Token an Pushwoosh senden.

func getPushToStartToken() {
    if #available(iOS 17.2, *) {
        Task {
            for await data in Activity<LiveActivityAttributes>.pushToStartTokenUpdates {
                let token = data.map {String(format: "%02x", $0)}.joined()
                print("Activity PushToStart Token: \(token)")

                // Senden Sie das `pushToStartTokenUpdates`-Token an Pushwoosh
                try await Pushwoosh.LiveActivities.sendPushToStartLiveActivity(token: token)
            }
        }
    }
}

Initiieren Sie eine Live Activity mit einer Remote-Push-Benachrichtigung

Verwalten von Live Activities

Das Pushwoosh iOS SDK bietet die folgenden Methoden zur Arbeit mit Live Activities:

// Senden Sie das Live Activity Push To Start Token an Pushwoosh
static func sendPushToStartLiveActivity(token: String)
static func sendPushToStartLiveActivity(token: String, completion: @escaping (Error?) -> Void)

// Starten Sie Live Activity Methoden mit Activity ID
static func startLiveActivity(token: String, activityId: String)
static func startLiveActivity(token: String, activityId: String, completion: @escaping (Error?) -> Void)

// Stoppen Sie Live Activity Methoden
static func stopLiveActivity()
static func stopLiveActivity(completion: @escaping (Error?) -> Void)

static func stopLiveActivity(activityId: String)
static func stopLiveActivity(activityId: String, completion: @escaping (Error?) -> Void)

// Planen Sie den Start einer Live Activity zu einem zukünftigen Zeitpunkt (iOS 26.0+)
static func schedule<Attributes: PushwooshLiveActivityAttributes>(attributes: Attributes, contentState: Attributes.ContentState, at startDate: Date, alertTitle: String, alertBody: String) throws -> Activity<Attributes>

// Brechen Sie eine geplante oder laufende Live Activity anhand ihrer Activity ID ab (iOS 16.2+)
static func cancel<Attributes: PushwooshLiveActivityAttributes>(_ activityType: Attributes.Type, activityId: String)

Sie können Live Activities auch nach Segmenten über den Parameter Activity ID aktualisieren. Beim Erstellen einer Aktivität müssen Sie einen eindeutigen Activity ID-Parameter in der Methode übergeben, der für ein bestimmtes Benutzersegment relevant ist.

Zum Beispiel haben N Benutzer dasselbe Ereignis in einer Live Activity abonniert. Es ist notwendig, dass der Activity ID-Parameter für alle diese N Benutzer eindeutig ist.

Wenn Sie die Arbeit mit einer Live Activity beenden, verwenden Sie diese Methoden:

static func stopLiveActivity()
static func stopLiveActivity(completion: @escaping (Error?) -> Void)

Planen des Starts einer Live Activity zu einem zukünftigen Zeitpunkt

Anstatt eine Live Activity sofort zu starten, können Sie sie für einen zukünftigen Zeitpunkt planen. alertTitle und alertBody werden dem Benutzer in der lokalen Benachrichtigung angezeigt, die ausgelöst wird, wenn die geplante Aktivität tatsächlich startet:

if #available(iOS 26.0, *) {
    let startDate = Date().addingTimeInterval(3600) // startet in 1 Stunde

    do {
        let activity = try Pushwoosh.LiveActivities.schedule(
            attributes: atttribute,
            contentState: initialState,
            at: startDate,
            alertTitle: "Game starting!",
            alertBody: "The match is about to begin"
        )
        self.currentActivity = activity
    } catch {
        print("Schedule Activity Error: \(error.localizedDescription)")
    }
}

startDate muss in der Zukunft liegen, andernfalls löst der Aufruf eine Ausnahme aus. Rufen Sie schedule im Hauptthread auf, während die App im Vordergrund ist. Es gibt keine Anfrage an Pushwoosh zur Planungszeit: Der Server erfährt von der Aktivität, sobald sie tatsächlich startet und ihr Push-Token über denselben Token-Beobachter erhält, der von der setup()-Methode installiert wurde (siehe unten).

Abbrechen einer Live Activity nach Activity ID

Verwenden Sie cancel(_:activityId:), um eine Live Activity anhand ihrer Activity ID abzubrechen, ohne eine Referenz auf die Activity-Instanz zu halten:

if #available(iOS 16.2, *) {
    Pushwoosh.LiveActivities.cancel(FoodDeliveryAttributes.self, activityId: "activity_id")
}

cancel beendet die Aktivität auf dem Gerät sofort und benachrichtigt den Pushwoosh-Server. Dies unterscheidet sich von stopLiveActivity(activityId:), das nur den Server benachrichtigt und die Aktivität nicht direkt auf dem Gerät beendet. cancel funktioniert auch für eine Live Activity, die mit schedule geplant, aber noch nicht gestartet wurde – sie wird abgebrochen, bevor sie überhaupt beginnt.

`Setup()`-Methode.

Pushwoosh vereinfacht die Übertragung von Activity IDs durch die Einführung der Funktion PushwooshLiveActivities.setup, die den gesamten Lebenszyklus einer Live Activity innerhalb der Anwendung handhabt. Diese Funktion lauscht automatisch auf pushToStart- und pushToUpdate-Token-Updates. Durch die Verwendung dieser Methode muss die Anwendung nicht mehr manuell den Start von Live Activities verfolgen oder Token-Updates für Aktivitätsaktualisierungen verwalten.

Wir empfehlen die Verwendung dieser Methode, da sie die gesamte Token-Verwaltung auf unserer Seite übernimmt und so die Menge an Code reduziert, die Sie auf Ihrer Seite pflegen müssen. Dies vereinfacht die Integration und sorgt für eine reibungslosere, effizientere Erfahrung für Ihre App.

Stellen Sie im AppDelegate sicher, dass Sie PushwooshFramework und PushwooshLiveActivities importieren und die setup-Methode aus dem Pushwoosh.LiveActivities-Modul aufrufen.

AppDelegate.swift

if #available(iOS 16.1, *) {
    Pushwoosh.LiveActivities.setup(FoodDeliveryAttributes.self)
}

FoodDeliveryAttributes

import WidgetKit
import SwiftUI
import ActivityKit
import PushwooshFramework
import PushwooshLiveActivities

struct FoodDeliveryAttributes: PushwooshLiveActivityAttributes {
    public struct ContentState: PushwooshLiveActivityContentState {
        var status: String
        var estimatedTime: String
        var emoji: String
        var pushwoosh: PushwooshLiveActivityContentStateData?
    }

    var orderNumber: String
    var pushwoosh: PushwooshLiveActivityAttributeData
}

FoodDeliveryAttributes: Diese Struktur entspricht dem PushwooshLiveActivityAttributes-Protokoll. Sie wird verwendet, um die Attribute einer Live Activity innerhalb der App zu definieren.

Migrationsleitfaden

Ab Version 6.8.0 des Pushwoosh iOS SDK haben wir die SDK-Struktur aktualisiert. Die Methoden für Live Activities sind jetzt über das PushwooshLiveActivities-Modul zugänglich.

Wenn Sie eine Version des Pushwoosh iOS SDK vor 6.8.0 verwendet und die unten aufgeführten Methoden aufgerufen haben und seitdem auf Version 6.8.0 oder höher aktualisiert haben, beachten Sie bitte die folgenden Änderungen:

static func setup<Attributes: PushwooshLiveActivityAttributes>(_ activityType: Attributes.Type)
static func defaultSetup()
static func defaultStart(_ activityId: String, attributes: [String: Any], content: [String: Any])

Um auf diese Methoden zuzugreifen, sollten Sie jetzt das LiveActivity-Modul verwenden.

import PushwooshFramework
import PushwooshLiveActivities

Pushwoosh.LiveActivities.setup(FoodDeliveryAttributes.self)
Pushwoosh.LiveActivities.defaultSetup()
Pushwoosh.LiveActivities.defaultStart("activity_id",
                            attributes: ["key_attribute": "value_attribute"],
                            content: ["key_content": "value_content"])

Wir haben auch die Unterstützung für die Methoden über Pushwoosh.sharedInstance() wie unten aufgeführt beibehalten, aber bitte beachten Sie, dass diese Methoden in zukünftigen Versionen veraltet sein werden.

// Senden Sie das Live Activity Push To Start Token an Pushwoosh
static func sendPushToStartLiveActivity(token: String)
static func sendPushToStartLiveActivity(token: String, completion: @escaping (Error?) -> Void)

// Starten Sie Live Activity Methoden mit Activity ID
static func startLiveActivity(token: String, activityId: String)
static func startLiveActivity(token: String, activityId: String, completion: @escaping (Error?) -> Void)

// Stoppen Sie Live Activity Methoden
static func stopLiveActivity()
static func stopLiveActivity(completion: @escaping (Error?) -> Void)

static func stopLiveActivity(activityId: String)
static func stopLiveActivity(activityId: String, completion: @escaping (Error?) -> Void)