Live Activities iOS

Conseil

Regardez une vidéo sur les Live Activities iOS

Vidéo Youtube : Live Activities iOS

Les Live Activities affichent les données les plus récentes de votre application sur l’écran de verrouillage de l’iPhone ou de l’iPad et dans la Dynamic Island. Cette fonctionnalité permet aux utilisateurs de voir des informations en direct d’un seul coup d’œil et d’effectuer des actions rapides liées aux informations affichées.

Voici quelques exemples d’utilisation des Live Activities :

• Afficher le statut d’une commande dans une application de livraison ;
• Fournir un compte à rebours en temps réel dans une application d’entraînement ;
• Afficher les informations de suivi dans une application de taxi ;
• Afficher les statistiques de jeu et les scores actuels dans une application de sport ;
• Fournir des prévisions horaires dans une application météo.

Vous pouvez activer les Live Activities à l’aide du SDK iOS de Pushwoosh comme décrit ci-dessous. Pour gérer les Live Activities et mettre à jour leur contenu, utilisez la méthode /updateLiveActivity.

Configuration

Important

Les Live Activities dans Pushwoosh ne prennent en charge que la configuration basée sur un jeton. La configuration basée sur un certificat n’est pas prise en charge.

Ajouter une extension de widget

1. Créer une nouvelle cible

Allez dans File > New > Target et sélectionnez Widget Extension.

2. Configuration de l’extension de widget Veuillez entrer un nom et assurez-vous de sélectionner Include Live Activity puis cliquez sur Finish.

Configuration d’Info.plist

Trouvez le fichier Info.plist dans la cible principale, insérez la clé “Supports Live Activities” et définissez sa valeur sur YES.

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

Mises à jour fréquentes

Si votre Live Activity est mise à jour souvent (par exemple, les scores sportifs en direct), ajoutez également NSSupportsLiveActivitiesFrequentUpdates avec la valeur true. Apple limite le nombre de mises à jour push à haute priorité qu’une application peut envoyer par heure. Cette clé augmente ce budget. Consultez le paramètre apns_priority dans la référence de l’API Live Activities pour savoir comment la priorité de livraison est contrôlée par mise à jour.

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

Activer les Live Activities depuis l’application

Pour activer les Live Activities, ajoutez leur code à votre extension de widget existante ou créez-en une nouvelle si votre application n’en a pas déjà. Les Live Activities utilisent les fonctionnalités de SwiftUI et WidgetKit pour leur interface utilisateur. ActivityKit gère le cycle de vie de chaque Live Activity : son API est utilisée pour demander, mettre à jour et terminer une Live Activity et pour recevoir des notifications push ActivityKit. Vous pouvez en apprendre davantage sur les Live Activities dans la documentation d’Apple.

1. Accédez au fichier ContentView de votre projet dans Xcode et créez un bouton

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()
}

2. Créez un fichier LiveActivityManager.swift pour gérer les 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)")
        }
    }
}

3. C’est tout, maintenant nous lançons le projet et appuyons sur le bouton ‘Start Live Activity’. Ensuite, nous naviguons vers l’écran de verrouillage et voyons la Live Activity créée.

Démarrer une Live Activity avec une notification push à distance

1. Pour lancer une Live Activity via une notification push à distance, vous devez envoyer le jeton pushToStartTokenUpdates à 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)
            }
        }
    }
}

2. Lancer une Live Activity avec une notification push à distance

Conseil

Suivez notre référence de l’API Pushwoosh pour des instructions et des exemples sur la manière de faire une requête pour démarrer une Live Activity à distance.

Gérer les Live Activities

Le SDK iOS de Pushwoosh fournit les méthodes suivantes pour travailler avec les 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)

Vous pouvez également mettre à jour les Live Activities par segments en utilisant le paramètre Activity ID. Lors de la création d’une activité, vous devez passer un paramètre Activity ID unique dans la méthode, qui sera pertinent pour un segment d’utilisateurs spécifique.

Par exemple, N utilisateurs se sont abonnés au même événement dans une Live Activity. Il est nécessaire que le paramètre Activity ID soit unique pour tous ces N utilisateurs.

Lorsque vous avez terminé de travailler avec une Live Activity, utilisez ces méthodes :

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

Note

Vous pouvez gérer les Live Activities iOS via l’API Pushwoosh.

Planifier le démarrage d’une Live Activity à une date ultérieure

Note

Nécessite iOS 26.0+.

Au lieu de démarrer une Live Activity immédiatement, vous pouvez la planifier pour qu’elle démarre à une date ultérieure. alertTitle et alertBody sont affichés à l’utilisateur dans l’alerte de notification locale qui se déclenche lorsque l’activité planifiée démarre réellement :

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 doit être dans le futur, sinon l’appel lève une exception. Appelez schedule sur le thread principal pendant que l’application est au premier plan. Il n’y a pas de requête de planification à Pushwoosh : le serveur prend connaissance de l’activité une fois qu’elle démarre réellement et reçoit son jeton push via le même observateur de jeton installé par la méthode setup() (voir ci-dessous).

Annuler une Live Activity par son ID d’activité

Note

Nécessite iOS 16.2+.

Utilisez cancel(_:activityId:) pour annuler une Live Activity par son ID d’activité sans détenir de référence à l’instance Activity :

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

cancel met fin à l’activité sur l’appareil immédiatement et notifie le serveur Pushwoosh. Cela diffère de stopLiveActivity(activityId:), qui notifie uniquement le serveur et ne met pas fin à l’activité sur l’appareil directement. cancel fonctionne également pour une Live Activity qui a été planifiée avec schedule mais qui n’a pas encore commencé — elle est annulée avant même de démarrer.

Méthode Setup()

Pushwoosh simplifie le transfert des ID d’activité en introduisant la fonction PushwooshLiveActivities.setup, qui gère l’ensemble du cycle de vie d’une Live Activity au sein de l’application. Cette fonction écoute automatiquement les mises à jour de jetons pushToStart et pushToUpdate. En utilisant cette méthode, l’application n’a plus besoin de suivre manuellement le lancement des Live Activities ou de gérer les mises à jour de jetons pour les mises à jour d’activité.

Nous recommandons d’utiliser cette méthode car elle gère toute la gestion des jetons de notre côté, réduisant la quantité de code que vous devez maintenir de votre côté. Cela simplifie l’intégration et assure une expérience plus fluide et plus efficace pour votre application.

Dans l’AppDelegate, assurez-vous d’importer PushwooshFramework et PushwooshLiveActivities et d’appeler la méthode setup du module 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 : Cette structure est conforme au protocole PushwooshLiveActivityAttributes. Elle est utilisée pour définir les attributs d’une Live Activity au sein de l’application.

Note

Vous pouvez gérer les Live Activities et mettre à jour leur contenu en utilisant la méthode /updateLiveActivity de l’API Pushwoosh. Pour plus d’informations, veuillez lire ce guide

Guide de migration

À partir de la version 6.8.0 du SDK iOS de Pushwoosh, nous avons mis à jour la structure du SDK. Les méthodes des Live Activities sont désormais accessibles via le module PushwooshLiveActivities.

Si vous utilisiez une version du SDK iOS de Pushwoosh antérieure à la 6.8.0 et que vous appeliez les méthodes listées ci-dessous, et que vous avez depuis mis à jour vers la version 6.8.0 ou ultérieure, veuillez noter les changements suivants :

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

Maintenant, pour accéder à ces méthodes, vous devez utiliser le module 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"])

Nous avons également maintenu la prise en charge des méthodes via Pushwoosh.sharedInstance() comme indiqué ci-dessous, mais veuillez noter que ces méthodes seront obsolètes dans les futures versions.

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