Live Activities de iOS

Las Live Activities muestran los datos más actuales de su aplicación en la pantalla de bloqueo del iPhone o iPad y en la Dynamic Island. Esta función permite a los usuarios ver información en vivo de un vistazo y realizar acciones rápidas relacionadas con la información mostrada.

Aquí hay algunos ejemplos del uso de Live Activities:

Mostrar el estado del pedido en una aplicación de entrega;
Proporcionar una cuenta regresiva en tiempo real en una aplicación de entrenamiento;
Mostrar información de seguimiento en una aplicación de taxi;
Mostrar estadísticas del juego y puntuaciones actuales en una aplicación de deportes;
Proporcionar pronósticos por hora en una aplicación del tiempo.

Puede habilitar las Live Activities utilizando el SDK de Pushwoosh para iOS como se describe a continuación. Para gestionar las Live Activities y actualizar su contenido, utilice el método /updateLiveActivity.

Configuración

Crear un nuevo target

Vaya a File > New > Target y seleccione Widget Extension.

Configuración de la Extensión de Widget Por favor, introduzca un nombre y asegúrese de seleccionar Include Live Activity y haga clic en Finish.

Configuración de Info.plist

Encuentre el archivo Info.plist en el target principal, inserte la clave “Supports Live Activities” y establezca su valor en YES.

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

Si su Live Activity se actualiza con frecuencia (por ejemplo, resultados deportivos en vivo), añada también NSSupportsLiveActivitiesFrequentUpdates con el valor true. Apple limita la cantidad de actualizaciones push de alta prioridad que una aplicación puede enviar por hora. Esta clave aumenta ese presupuesto. Consulte el parámetro apns_priority en la referencia de la API de Live Activities para ver cómo se controla la prioridad de entrega por actualización.

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

Habilitar las live activities desde la aplicación

Para habilitar las Live Activities, añada su código a su extensión de widget existente o cree una nueva si su aplicación aún no la tiene. Las Live Activities utilizan la funcionalidad de SwiftUI y WidgetKit para su interfaz de usuario. ActivityKit maneja el ciclo de vida de cada Live Activity: su API se utiliza para solicitar, actualizar y finalizar una Live Activity y para recibir notificaciones push de ActivityKit. Puede obtener más información sobre las Live Activities en la documentación de Apple.

Navegue al archivo ContentView de su proyecto en Xcode y cree un 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()
}

Cree un archivo LiveActivityManager.swift para gestionar las 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: - Send Push Token to Pushwoosh
                    Pushwoosh.LiveActivities.startLiveActivity(
                        token: pushTokenString,
                        activityId: "activity_id"
                    )
                }
            }
        } catch {
            print("Start Activity Error: \(error.localizedDescription)")
        }
    }
}

Eso es todo, ahora ejecutamos el proyecto y pulsamos el botón ‘Start Live Activity’. Luego navegamos a la pantalla de bloqueo y vemos la Live Activity creada.

Iniciar una Live Activity con una notificación push remota

Para iniciar una Live Activity a través de una Notificación Push Remota, necesita enviar el token pushToStartTokenUpdates a Pushwoosh.

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)")

                // Send `pushToStartTokenUpdates` token to Pushwoosh
                try await Pushwoosh.LiveActivities.sendPushToStartLiveActivity(token: token)
            }
        }
    }
}

Iniciar una Live Activity con una Notificación Push Remota

Gestionar Live Activities

El SDK de Pushwoosh para iOS proporciona los siguientes métodos para trabajar con Live Activities:

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

// Start Live Activity Methods with Activity ID
static func startLiveActivity(token: String, activityId: String)
static func startLiveActivity(token: String, activityId: String, completion: @escaping (Error?) -> Void)

// Stop Live Activity Methods
static func stopLiveActivity()
static func stopLiveActivity(completion: @escaping (Error?) -> Void)

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

// Schedule a Live Activity to start at a future date (iOS 26.0+)
static func schedule<Attributes: PushwooshLiveActivityAttributes>(attributes: Attributes, contentState: Attributes.ContentState, at startDate: Date, alertTitle: String, alertBody: String) throws -> Activity<Attributes>

// Cancel a scheduled or running Live Activity by its Activity ID (iOS 16.2+)
static func cancel<Attributes: PushwooshLiveActivityAttributes>(_ activityType: Attributes.Type, activityId: String)

También puede actualizar las live activities por segmentos utilizando el parámetro Activity ID. Al crear una actividad, necesita pasar un parámetro único de Activity ID en el método, que será relevante para un segmento de usuarios específico.

Por ejemplo, N usuarios se han suscrito al mismo evento en una Live Activity. Es necesario que el parámetro Activity ID sea único para todos estos N usuarios.

Cuando termine de trabajar con una Live Activity, utilice estos métodos:

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

Programar una Live Activity para que comience en una fecha futura

En lugar de iniciar una Live Activity inmediatamente, puede programarla para que comience en una fecha futura. alertTitle y alertBody se muestran al usuario en la alerta de notificación local que se dispara cuando la actividad programada realmente comienza:

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

    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 debe ser en el futuro, de lo contrario la llamada lanza un error. Llame a schedule en el hilo principal mientras la aplicación está en primer plano. No hay una solicitud a Pushwoosh en el momento de la programación: el servidor se entera de la actividad una vez que realmente comienza y recibe su token push a través del mismo observador de tokens instalado por el método setup() (ver más abajo).

Cancelar una Live Activity por su ID de Actividad

Use cancel(_:activityId:) para cancelar una Live Activity por su ID de Actividad sin mantener una referencia a la instancia de Activity:

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

cancel finaliza la actividad en el dispositivo de inmediato y notifica al servidor de Pushwoosh. Esto difiere de stopLiveActivity(activityId:), que solo notifica al servidor y no finaliza la actividad en el dispositivo directamente. cancel también funciona para una Live Activity que fue programada con schedule pero que aún no ha comenzado — se cancela antes de que comience.

Método `Setup()`.

Pushwoosh simplifica la transferencia de IDs de actividad introduciendo la función PushwooshLiveActivities.setup, que maneja todo el ciclo de vida de una Live Activity dentro de la aplicación. Esta función escucha automáticamente las actualizaciones de tokens tanto de pushToStart como de pushToUpdate. Al usar este método, la aplicación ya no necesita rastrear manualmente el inicio de las Live Activities ni gestionar las actualizaciones de tokens para las actualizaciones de la actividad.

Recomendamos usar este método porque maneja toda la gestión de tokens de nuestro lado, reduciendo la cantidad de código que necesita mantener en el suyo. Esto simplifica la integración y asegura una experiencia más fluida y eficiente para su aplicación.

En el AppDelegate, asegúrese de importar PushwooshFramework y PushwooshLiveActivities y llamar al método setup desde el módulo Pushwoosh.LiveActivities.

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: Esta estructura se ajusta al protocolo PushwooshLiveActivityAttributes. Se utiliza para definir los atributos de una live activity dentro de la aplicación.

Guía de migración

A partir de la versión 6.8.0 del SDK de Pushwoosh para iOS, hemos actualizado la estructura del SDK. Los métodos de Live Activities ahora se acceden a través del módulo PushwooshLiveActivities.

Si estaba utilizando una versión del SDK de Pushwoosh para iOS anterior a la 6.8.0 y llamaba a los métodos que se enumeran a continuación, y desde entonces ha actualizado a la versión 6.8.0 o posterior, tenga en cuenta los siguientes cambios:

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

Ahora, para acceder a estos métodos, debe usar el módulo LiveActivity.

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"])

También hemos mantenido el soporte para los métodos a través de Pushwoosh.sharedInstance() como se enumera a continuación, pero tenga en cuenta que estos métodos serán obsoletos en futuras versiones.

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

// Start Live Activity Methods with Activity ID
static func startLiveActivity(token: String, activityId: String)
static func startLiveActivity(token: String, activityId: String, completion: @escaping (Error?) -> Void)

// Stop Live Activity Methods
static func stopLiveActivity()
static func stopLiveActivity(completion: @escaping (Error?) -> Void)

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