Blog

Timer con Live Activity in Expo

1 maggio 2025 12 min di lettura

Implementare le Live Activities nelle applicazioni Expo. Scopri come creare widget interattivi e aggiornamenti in tempo reale per la schermata di blocco di iOS e la Dynamic Island.

Timer con Live Activity in Expo
ExpoiOSLive ActivitiesWidgetReact Native

Creare un timer con Live Activity in Expo

Le Live Activities su iOS cambiano le regole del gioco: permettono alle app di mostrare aggiornamenti in tempo reale direttamente sulla schermata di blocco o nella Dynamic Island. Naturalmente ho iniziato a immaginare quanto sarebbe stato bello avere lì un timer di allenamento, che tenesse motivati gli utenti senza nemmeno sbloccare il telefono. Ma c'era un problema: le Live Activities si costruiscono con gli strumenti nativi di Apple, come Swift e ActivityKit. È allora che ho scoperto uno strumento chiamato expo-apple-targets, che mi ha evitato di scrivere interi moduli da zero e ha reso il processo molto più semplice di quanto mi aspettassi. In questo articolo ti racconto come ho costruito una Live Activity per iOS basata su un timer, i passi che ho seguito e cosa ho imparato strada facendo.

Perché le Live Activities sono diventate la mia ossessione

Le Live Activities non sono solo un trucco carino: cambiano le regole del gioco per il coinvolgimento degli utenti. Le Human Interface Guidelines di Apple le descrivono come un modo per fornire "informazioni attuali, leggibili a colpo d'occhio" per attività legate al tempo. Immagina un'app di fitness che mostra il tempo del tuo plank a metà allenamento, un'app di consegne che segue il viaggio della tua pizza o un'app di ride sharing che aggiorna l'orario di arrivo dell'autista, tutto direttamente sulla schermata di blocco o, da iPhone 14 Pro in poi, nella Dynamic Island. È come dare agli utenti un pass VIP per gli aggiornamenti più importanti della tua app, senza che debbano sbloccare il telefono.

Volevo che gli utenti vedessero il timer di allenamento avanzare durante una serie, così da restare concentrati senza dover aprire l'app. È il tipo di cura che fa sembrare un'app professionale, e mi ci sono buttato a capofitto. Ma tutto questo non si può fare senza toccare il livello nativo, quindi sapevo che mi sarei tuffato in Swift e avrei lottato con Xcode. Poi ho scoperto expo-apple-targets, un pacchetto che colma il divario tra il mondo JavaScript di Expo e le funzioni native di iOS. Tanto di cappello a Evan Bacon: questo strumento ha preso un compito scoraggiante e l'ha trasformato in un rompicapo impegnativo ma fattibile.

Il quadro generale: Live Activities in un'app Expo

Le Live Activities sono una festa riservata a iOS. Sono basate su ActivityKit, un framework in Swift, il che significa che scriverai codice nativo che ti piaccia o no. Per un'app Expo è come convincere un pesce ad arrampicarsi su un albero: si può fare, ma richiede un certo impegno. expo-apple-targets interviene come una guida esperta e offre un framework per creare moduli nativi ed estensioni widget senza partire da zero. Si basa sul sistema di moduli di Expo (Expo Modules API), che permette di scrivere codice nativo in Swift ed esporlo a JavaScript, e rende tutto il processo molto meno simile a una devitalizzazione dal dentista.

Configurare il progetto

Iniziare non è stata proprio una passeggiata, ma expo-apple-targets ha reso tutto gestibile. Ecco come sono partito:

  • Installare expo-apple-targets: un rapido npm install expo-apple-targets e sono partito. Il README del pacchetto è una miniera d'oro: ti guida nell'aggiunta di un'estensione widget in Xcode e nell'aggiornamento di app.json con l'entitlement per le Live Activity (com.apple.developer.activitykit).

  • Configurare il modulo nativo: ho usato il sistema di moduli di Expo per creare un modulo Swift che comunica con ActivityKit. La documentazione di Expo Modules insiste sul definire firme di funzione ed eventi chiari, e questo mi ha aiutato a esporre a JavaScript metodi come startActivity senza fatica.

  • Estensione widget: qui è entrato in gioco SwiftUI, che mi ha permesso di disegnare l'aspetto della Live Activity per la schermata di blocco e la Dynamic Island. expo-apple-targets fornisce un template per il widget, ma ho dovuto personalizzarlo per mostrare un timer che scorre e pulsanti interattivi.

  • Intent: permettono agli utenti di toccare i pulsanti del widget per mettere in pausa o riprendere il timer. expo-apple-targets semplifica la configurazione degli intent, ma ho comunque dovuto fare debug di qualche colpo a vuoto prima che le notifiche arrivassero nel modo giusto.

Un timer che si aggiorna ogni secondo?

Uno sviluppatore implementa entusiasta un aggiornamento del timer ogni secondo, e il timer manda il sistema nel caos più totale. (Generata da gpt-4o)Uno sviluppatore implementa entusiasta un aggiornamento del timer ogni secondo, e il timer manda il sistema nel caos più totale. (Generata da gpt-4o)

Quando ho affrontato il timer per la prima volta, il mio cervello ha detto: "Aggiorna semplicemente la Live Activity ogni secondo con l'ora corrente". Sembra lineare, vero? Sbagliato. Mi sono imbattuto in un thread su Reddit in cui alcuni sviluppatori discutevano della possibilità di aggiornare il timer di una Live Activity. Il verdetto era unanime: aggiornare ogni secondo è un disastro. È come alimentare un'astronave con la ruota di un criceto: si muove, ma si esaurisce in fretta. Gli aggiornamenti continui martellano la CPU e consumano la batteria, rendendo l'app lenta.

Quel thread su Reddit è stato un campanello d'allarme. Ho trovato Text(timerInterval:) di SwiftUI nella documentazione di SwiftUI di Apple, ed è stata una rivelazione. Questa vista gestisce gli aggiornamenti del timer in modo nativo, scorrendo senza bisogno di aggiornare l'intera Live Activity. È come delegare a iOS la parte noiosa per concentrarti su quella divertente.

Così ho abbandonato il piano dell'aggiornamento ogni secondo e ho scelto un approccio con startedAt/pausedAt. Ecco perché è vincente:

  • Prestazioni: invece di inviare aggiornamenti ogni secondo, salvo l'ora di inizio del timer (startedAt) e l'ora della pausa (pausedAt, se è in pausa). Il widget usa Text(timerInterval:) per mostrare un timer dal vivo basato su startedAt e, quando è in pausa, mostra un tempo statico usando pausedAt. Così le chiamate all'API scendono quasi a zero.

  • Efficienza della batteria: gli aggiornamenti frequenti sono un vampiro per la batteria. Lasciare che sia SwiftUI a far scorrere il timer mantiene l'app leggera e i telefoni degli utenti contenti.

  • Rispetto delle API: le API delle Live Activity di Apple non sono fatte per lo spam in tempo reale. L'approccio startedAt/pausedAt rispetta le aspettative di iOS e riduce la probabilità di finire sotto rate limiting.

  • Semplicità del codice: gestire due timestamp è molto più semplice che destreggiarsi con un flusso di aggiornamenti. Il codice resta pulito e il mio livello di stress sotto controllo.

Questo approccio mi è sembrato come trovare una scorciatoia segreta in un videogioco. Il timer scorre fluido, ha un bell'aspetto e non divora risorse. Il thread su Reddit (eccolo di nuovo) merita una medaglia per avermi indicato la strada giusta.

Il cuore della Live Activity

Non ti annoierò con ogni riga di codice: concentriamoci sugli snippet chiave che fanno funzionare questo timer. Alla fine dell'articolo condividerò su GitHub il codice sorgente completo.

La struct LiveActivityAttributes

Questa struct è la spina dorsale della Live Activity: ne definisce i dati e il modo in cui evolvono.

    struct LiveActivityAttributes: ActivityAttributes {
      public struct ContentState: Codable, Hashable {
        var startedAt: Date
        var pausedAt: Date?

        func getElapsedTimeInSeconds() -> TimeInterval {
          if let pausedAt = pausedAt {
            return pausedAt.timeIntervalSince(startedAt)
          } else {
            return Date().timeIntervalSince(startedAt)
          }
        }
        func isRunning() -> Bool {
          return pausedAt == nil
        }
        func getFormattedElapsedTime() -> String {
          let elapsed = getElapsedTimeInSeconds()
          let totalSeconds = Int(elapsed)
          let hours = totalSeconds / 3600
          let minutes = (totalSeconds % 3600) / 60
          let seconds = totalSeconds % 60
          if hours > 0 {
            return String(format: "%d:%02d:%02d", hours, minutes, seconds)
          } else {
            return String(format: "%d:%02d", minutes, seconds)
          }
        }
        func getFutureDate() -> Date {
          return Date().addingTimeInterval(365 * 24 * 60 * 60)
        }
      }
      var activityName: String
      var activityIcon: String
    }

È come il DNA della Live Activity. La LiveActivityAttributes esterna contiene la parte statica, activityName (per esempio "Workout") e activityIcon (per esempio "RUNNING"), impostati quando l'attività parte. Il ContentState interno è dove succede l'azione: tiene traccia di startedAt (quando è partito il timer) e pausedAt (quando è stato messo in pausa, se lo è). I metodi di supporto sono i veri protagonisti:

  • getElapsedTimeInSeconds() calcola da quanto tempo il timer è in funzione, fermandosi a pausedAt se è in pausa o usando l'ora corrente se è attivo. Così la logica resta compatta e riutilizzabile.

  • isRunning() è un semplice controllo: se pausedAt è null, il timer è attivo. È un modo pulito per evitare controlli di state disordinati altrove.

  • getFormattedElapsedTime() trasforma i secondi in una bella stringa "MM:SS" o "HH:MM:SS" per il widget. Ho aggiunto il supporto alle ore dopo aver capito che alcuni utenti potrebbero fare allenamenti lunghissimi, come le maratone.

  • getFutureDate() imposta una data a un anno di distanza, che passo a Text(timerInterval:) per lasciare scorrere il timer all'infinito senza preoccuparmi di una data di fine.

Adoro come questa struct tenga tutto in ordine. È come uno zaino preparato bene: tutto quello che ti serve, niente di superfluo. La conformità a Codable e Hashable la rende facile da serializzare per gli aggiornamenti e da usare in SwiftUI, e mi ha salvato quando dovevo sincronizzare lo state tra il modulo e il widget.

Avviare la Live Activity

La funzione startActivity è dove inizia la magia: avvia una nuova Live Activity.

    AsyncFunction("startActivity") { (activityName: String, activityIcon: String) -> String in
        if #available(iOS 16.2, *) {
            await self.endAllActivities()
            self.startedAt = Date()
            self.pausedAt = nil
            if !ActivityAuthorizationInfo().areActivitiesEnabled {
                return ""
            }
            let attributes = LiveActivityAttributes(activityName: activityName, activityIcon: activityIcon)
            let contentState = LiveActivityAttributes.ContentState(startedAt: self.startedAt!, pausedAt: nil)
            do {
                let activity = try Activity.request(attributes: attributes, content: .init(state: contentState, staleDate: nil), pushType: nil)
                self.currentActivityId = activity.id
                self.sendTimerUpdateEvent()
                return activity.id
            } catch {
                throw error
            }
        }
        return ""
    }

Questa funzione è la scintilla che accende il fuoco. È esposta a JavaScript tramite il sistema di moduli di Expo, così la mia app React Native può chiamarla con un nome e un'icona. Ecco cosa fa:

  • Controlla che ci sia iOS 16.2 o successivo: prima le Live Activities non esistono.

  • Chiama endAllActivities() per eliminare eventuali attività esistenti. iOS permette più Live Activities, ma io ne volevo una alla volta per evitare confusione.

  • Imposta startedAt all'ora corrente e azzera pausedAt, preparando il timer a partire.

  • Verifica che le Live Activities siano attive (gli utenti possono disattivarle nelle Impostazioni, e all'inizio questo mi ha mandato in confusione).

  • Costruisce un LiveActivityAttributes con il nome e l'icona forniti, e un ContentState con l'ora di inizio.

  • Richiede una nuova attività tramite Activity.request, che mi restituisce un oggetto Activity con un ID univoco.

  • Salva l'ID, invia un evento di aggiornamento a JavaScript e restituisce l'ID, così l'app può seguirla.

Mettere in pausa il timer

La pausa del timer è gestita da performPause, che aggiorna lo state della Live Activity.

    private func performPause(activityId: String?) async -> Bool {
        guard #available(iOS 16.2, *), self.pausedAt == nil else {
            return false
        }
        let targetId = activityId ?? self.currentActivityId
        guard let targetId = targetId else {
            return false
        }
        guard let activity = await self.findActivityById(targetId) else {
            return false
        }
        guard let currentStartedAt = self.startedAt else {
            return false
        }
        let now = Date()
        self.pausedAt = now
        let contentState = LiveActivityAttributes.ContentState(startedAt: currentStartedAt, pausedAt: self.pausedAt)
        await activity.update(using: contentState)
        self.sendTimerUpdateEvent()
        return true
    }

È qui che l'approccio startedAt/pausedAt dà il meglio. Quando l'utente mette in pausa il timer (dall'app o dal widget), questa funzione:

  • Controlla che siamo su iOS 16.2 e che il timer non sia già in pausa (niente doppie pause).

  • Prende l'ID dell'attività, ripiegando su currentActivityId se non ne viene fornito uno.

  • Trova l'attività con findActivityById, che cerca tra le attività in corso.

  • Imposta pausedAt all'ora corrente, congelando il timer.

  • Crea un nuovo ContentState con lo startedAt originale e il nuovo pausedAt.

  • Aggiorna l'attività con activity.update, dicendo al widget di mostrare il tempo in pausa.

  • Invia un evento a JavaScript per tenere sincronizzata la UI dell'app.

Qui la logica punta tutto sulla precisione: ogni controllo (come pausedAt == nil) serve a evitare casi limite strani, come mettere in pausa un'attività che non esiste. Per la gestione degli eventi mi sono appoggiato alla documentazione di Expo Modules, usando sendEvent per inviare aggiornamenti a JavaScript. Le prime versioni di questa funzione non validavano startedAt, e questo ha portato a timer visualizzati in modo bizzarro. Lezione imparata: proteggi sempre il tuo state.

La vista sulla schermata di blocco

La LockScreenLiveActivityView è quello che gli utenti vedono quando il telefono è bloccato, e deve avere un bell'aspetto.

Live Activity sulla schermata di bloccoLive Activity sulla schermata di blocco

    struct LockScreenLiveActivityView: View {
        let context: ActivityViewContext<LiveActivityAttributes>
        var body: some View {
            ZStack {
                Color.black.opacity(0.8)
                    .clipShape(RoundedRectangle(cornerRadius: 16))
                HStack(spacing: 16) {
                    VStack(alignment: .leading, spacing: 12) {
                        HStack(spacing: 8) {
                            ActivityIcon(activityIcon: mapJSIconToSFSymbol(context.attributes.activityIcon),
                                        themeColor: .white,
                                        size: 18)
                            Text(context.attributes.activityName)
                                .font(.headline)
                                .foregroundColor(.white)
                        }
                        VStack(alignment: .leading, spacing: 4) {
                            if !context.state.isRunning() {
                                Text(context.state.getFormattedElapsedTime())
                                    .font(.system(size: 34, weight: .semibold, design: .rounded))
                                    .foregroundColor(.white)
                                    .fontWeight(.medium)
                                    .monospacedDigit()
                            } else {
                                Text(timerInterval: context.state.startedAt...context.state.getFutureDate(),
                                     pauseTime: nil,
                                     countsDown: false,
                                     showsHours: false)
                                    .font(.system(size: 34, weight: .semibold, design: .rounded))
                                    .foregroundColor(.white)
                                    .fontWeight(.medium)
                                    .monospacedDigit()
                            }
                        }
                    }
                    .frame(maxHeight: .infinity, alignment: .center)
                    Spacer()
                    VStack {
                        Spacer()
                        if context.state.isRunning() {
                            Button(intent: PauseIntent()) {
                                ZStack {
                                    Circle()
                                        .fill(Color(hex: "#007bff"))
                                        .frame(width: 44, height: 44)
                                    Image(systemName: "pause.fill")
                                        .font(.system(size: 18, weight: .bold))
                                        .foregroundColor(.white)
                                }
                            }
                            .buttonStyle(PlainButtonStyle())
                        } else {
                            HStack(spacing: 8) {
                                Button(intent: CompleteIntent()) {
                                    ZStack {
                                        Circle()
                                            .fill(Color(hex: "#28a745"))
                                            .frame(width: 44, height: 44)
                                        Image(systemName: "checkmark")
                                            .font(.system(size: 16, weight: .bold))
                                            .foregroundColor(.white)
                                    }
                                }
                                .buttonStyle(PlainButtonStyle())
                                Button(intent: ResumeIntent()) {
                                    ZStack {
                                        Circle()
                                            .fill(Color(hex: "#007bff"))
                                            .frame(width: 44, height: 44)
                                        Image(systemName: "play.fill")
                                            .font(.system(size: 18, weight: .bold))
                                            .foregroundColor(.white)
                                    }
                                }
                                .buttonStyle(PlainButtonStyle())
                            }
                        }
                        Spacer()
                    }
                }
                .padding(16)
            }
        }
    }

Questo è il cuore visivo della Live Activity, ed è qui che SwiftUI mostra i muscoli. La vista è divisa in due lati:

  • Lato sinistro: mostra il nome dell'attività, l'icona e il timer. Se il timer è in funzione, il lavoro pesante lo fa Text(timerInterval:), che conta da startedAt fino a un anno dopo (grazie a getFutureDate). Se è in pausa, mostra un tempo statico ottenuto da getFormattedElapsedTime. Il modificatore .monospacedDigit() mantiene i numeri nitidi, e ho ritoccato il font per renderlo in grassetto e leggibile.

  • Lato destro: gestisce i pulsanti. Quando il timer è in funzione c'è un pulsante blu di pausa. Quando è in pausa ci sono un segno di spunta verde per aprire l'app e un pulsante blu di play per riprendere. Ogni pulsante attiva un intent, che il modulo nativo intercetta ed elabora.

Alla scoperta della Dynamic Island

Vista della Dynamic IslandVista della Dynamic Island

Questo snippet definisce come appare la Live Activity nelle tre modalità della Dynamic Island: expanded (vista completa), compact (compressa) e minimal (essenziale).

    dynamicIsland: { context in
      DynamicIsland {
        DynamicIslandExpandedRegion(.leading) {
          VStack(alignment: .leading, spacing: 8) {
            HStack(spacing: 8) {
              ActivityIcon(activityIcon: mapJSIconToSFSymbol(context.attributes.activityIcon),
                          themeColor: .white,
                          size: 18)

              Text(context.attributes.activityName)
                .foregroundColor(.white)
                .font(.system(size: 16, weight: .semibold))
            }

            if !context.state.isRunning() {
              Text(context.state.getFormattedElapsedTime())
                .font(.system(size: 32, weight: .bold, design: .rounded))
                .foregroundColor(.white)
                .fontWeight(.medium)
                .monospacedDigit()
            } else {
              Text(timerInterval: context.state.startedAt...context.state.getFutureDate(),
                   pauseTime: nil,
                   countsDown: false,
                   showsHours: false)
                .font(.system(size: 32, weight: .bold, design: .rounded))
                .foregroundColor(.white)
                .fontWeight(.medium)
                .monospacedDigit()
            }
          }
          .padding(.leading, 8)
        }

        DynamicIslandExpandedRegion(.trailing) {
          VStack {
            Spacer()

            if context.state.isRunning() {
              Button(intent: PauseIntent()) {
                ZStack {
                  Circle()
                    .fill(Color(hex: "#007bff"))
                    .frame(width: 44, height: 44)
                  Image(systemName: "pause.fill")
                    .font(.system(size: 18, weight: .bold))
                    .foregroundColor(.white)
                }
              }
              .buttonStyle(PlainButtonStyle())
              .padding(.horizontal, 8)
            } else {
              HStack(spacing: 8) {
                Button(intent: CompleteIntent()) {
                  ZStack {
                    Circle()
                      .fill(Color(hex: "#28a745"))
                      .frame(width: 44, height: 44)
                    Image(systemName: "checkmark")
                      .font(.system(size: 16, weight: .bold))
                      .foregroundColor(.white)
                  }
                }
                .buttonStyle(PlainButtonStyle())

                Button(intent: ResumeIntent()) {
                  ZStack {
                    Circle()
                      .fill(Color(hex: "#007bff"))
                      .frame(width: 44, height: 44)
                    Image(systemName: "play.fill")
                      .font(.system(size: 18, weight: .bold))
                      .foregroundColor(.white)
                  }
                }
                .buttonStyle(PlainButtonStyle())
              }
            }
          }
          .frame(maxHeight: .infinity)
        }
      } compactLeading: {
        HStack(spacing: 4) {
          ActivityIcon(activityIcon: mapJSIconToSFSymbol(context.attributes.activityIcon),
                      themeColor: .white,
                      size: 16)

          Text(context.attributes.activityName)
            .foregroundColor(.white)
            .font(.system(size: 12))
            .lineLimit(1)
            .truncationMode(.tail)
        }
      } compactTrailing: {
        if !context.state.isRunning() {
          Text(context.state.getFormattedElapsedTime())
            .foregroundColor(.white)
            .monospacedDigit()
            .font(.system(size: 12, weight: .medium))
        } else {
          Text(timerInterval: context.state.startedAt...context.state.getFutureDate(),
               pauseTime: nil,
               countsDown: false,
               showsHours: false)
            .foregroundColor(.white)
            .monospacedDigit()
            .font(.system(size: 12, weight: .medium))
        }
      } minimal: {
        ActivityIcon(activityIcon: mapJSIconToSFSymbol(context.attributes.activityIcon),
                    themeColor: .white,
                    size: 12)
      }
    }
  • **Modalità expanded**: appare con una pressione prolungata ed è divisa in .leading e .trailing. Il lato leading impila l'icona (per esempio una figura che corre) e il nome ("Workout") con un grande timer, statico quando è in pausa (getFormattedElapsedTime) e in movimento quando è attivo (Text(timerInterval:)). Il lato trailing ha i pulsanti: un pulsante blu di pausa quando il timer è in funzione, oppure il segno di spunta verde (apri l'app) e il play blu (riprendi) quando è in pausa. Ho ritoccato font e padding per adattarli alle curve dell'Island.

  • **Modalità compact**: quando lo spazio si riduce, compactLeading mostra una piccola icona e il nome troncato, mentre compactTrailing mostra il timer (statico o in movimento). .lineLimit(1) tiene in ordine il nome, e un font da 12 punti garantisce la leggibilità.

  • **Modalità minimal**: strettissima, è solo un'icona da 12 punti, come un manubrio, per dire "il timer è ancora qui". Semplice ma efficace.

La cartella _shared: perché è così importante

Panoramica della cartella _sharedPanoramica della cartella _shared

La cartella _shared di expo-apple-targets è una directory di primo livello pensata per collegare il codice essenziale sia al target principale dell'app sia ai target secondari, come il widget della Live Activity.

Le estensioni, come i widget, girano in processi separati e richiedono che file specifici siano collegati al loro target oltre che a quello dell'app principale. La cartella _shared fa in modo che questi file vengano collegati automaticamente a entrambi, eliminando la configurazione manuale. Per il mio timer ci ho messo la struct LiveActivityAttributes, così l'app e il widget condividevano lo stesso state del timer (startedAt, pausedAt) senza problemi di sincronizzazione.

Aprire l'app dal widget della Live Activity

CompleteIntent permette agli utenti di toccare un pulsante con il segno di spunta sul widget della Live Activity per aprire l'app, segnalando che hanno finito con il timer. È un'interazione semplice ma fondamentale per chiudere un allenamento.

    import AppIntents
    import WidgetKit

    @available(iOS 16.2, *)
    struct CompleteIntent: AppIntent, LiveActivityIntent {
        static var title: LocalizedStringResource = "Complete Exercise"
        static var description: IntentDescription = "Opens the app to complete the exercise"
        static var openAppWhenRun: Bool = true

        init() {}
        func perform() async throws -> some IntentResult {
            NotificationCenter.default.post(name: Notification.Name("completeActivityFromWidget"), object: nil)

            return .result()
        }
    }

Quando l'utente tocca il segno di spunta verde, questo intent si attiva e pubblica una notifica completeActivityFromWidget. Il modulo nativo la intercetta, invia l'evento onWidgetCompleteActivity a JavaScript e iOS apre l'app, grazie a openAppWhenRun: true.

Gestire i tocchi dell'utente con gli intent

PauseIntent è uno degli intent che rendono interattivo il widget.

Intent della Live Activity sulla schermata di bloccoIntent della Live Activity sulla schermata di blocco

    import AppIntents
    import WidgetKit

    @available(iOS 16.2, *)
    struct PauseIntent: AppIntent, LiveActivityIntent {
      static var title: LocalizedStringResource = "Pause Timer"
      static var description: IntentDescription = "Pauses the current timer."

      init() {}

      func perform() async throws -> some IntentResult {
        NotificationCenter.default.post(name: Notification.Name("pauseTimerFromWidget"), object: nil)
        return .result()
      }
    }

Questo intent si attiva quando l'utente tocca il pulsante di pausa sul widget. È semplicissimo ma potente:

  • Pubblica una notifica (pauseTimerFromWidget) che il modulo nativo intercetta tramite setupNotificationObservers.

  • Il modulo poi esegue performPause, aggiornando lo state della Live Activity e avvisando JavaScript.

Il bello è il ciclo continuo che creano gli intent: l'utente tocca → l'intent si attiva → il modulo aggiorna → l'app resta sincronizzata. expo-apple-targets ha reso la configurazione degli intent un gioco da ragazzi grazie a un template, ma ho comunque dovuto fare debug di un caso in cui i tocchi non venivano registrati. Alla fine avevo scritto male il nome di una notifica. Un classico. La documentazione di Expo Modules mi ha aiutato a capire come gestire gli eventi generati da azioni native, ed è stato fondamentale per far funzionare tutto.

Eventi che parlano con JavaScript

Gli eventi della sezione seguente sono il modo in cui il modulo nativo tiene l'app React Native sincronizzata con lo state della Live Activity, usando il sistema di eventi di Expo.

onWidgetCompleteActivity

Questo evento si attiva quando l'utente tocca il segno di spunta per completare l'attività, ed è generato da CompleteIntent.

    @objc func completeIntentHandler(_ notification: Notification) {
        guard let currentId = self.currentActivityId, self.startedAt != nil else {
            return
        }

        let elapsed = self.calculateElapsedTime()

        sendEvent("onWidgetCompleteActivity", [
            "activityId": currentId,
            "elapsedTime": Int(elapsed)
        ])
    }

completeIntentHandler intercetta la notifica completeActivityFromWidget, calcola il tempo trascorso e invia a JavaScript l'evento onWidgetCompleteActivity con l'ID dell'attività e i secondi trascorsi. JavaScript può quindi aggiornare la UI dell'app o registrare il completamento dell'allenamento

onLiveActivityUpdate

Questo evento si attiva ogni volta che lo state del timer cambia (per esempio pausa o ripresa).

    private func sendTimerUpdateEvent() {
        guard let currentId = self.currentActivityId else { return }
        guard self.startedAt != nil else { return }

        let state = self.pausedAt == nil ? "active" : "paused"
        let elapsed = self.calculateElapsedTime()

        sendEvent("onLiveActivityUpdate", [
            "state": state,
            "elapsedTime": Int(elapsed),
            "activityId": currentId
        ])
    }

Chiamato dopo i cambi di state (come in performPause o performResume), invia l'evento onLiveActivityUpdate con lo state corrente ("active" o "paused"), il tempo trascorso e l'ID dell'attività. JavaScript lo ascolta per tenere la UI del timer nell'app sincronizzata con il widget.

Entrambi gli eventi creano un ciclo di feedback stretto tra il modulo nativo e JavaScript.

Perché tutto questo conta

Questa Live Activity non è solo un timer: è una funzione che fa sentire la mia app un vero cittadino nativo di iOS. Ecco perché è importante:

  • Coinvolgimento degli utenti: mostrare un timer sulla schermata di blocco o nella Dynamic Island tiene gli utenti collegati all'app senza interrompere il loro ritmo. È perfetto per gli allenamenti, dove ogni secondo conta.

  • Cura nativa: il design pulito del widget e i pulsanti interattivi fanno sembrare l'app di casa su iOS, non un ripiego multipiattaforma.

  • Prestazioni: l'approccio startedAt/pausedAt, basato su Text(timerInterval:), garantisce che il timer scorra fluido senza consumare la batteria né sbattere contro i limiti delle API.

expo-apple-targets e la Expo Modules API sono stati gli eroi silenziosi di questa storia, offrendo un framework solido per collegare JavaScript e Swift. L'attenzione della documentazione a definizioni di funzione pulite e alla gestione degli eventi ha mantenuto il mio codice ordinato e manutenibile.

Considerazioni finali

Questa Live Activity aggiunge all'app una sensazione fluida e nativa, mostrando aggiornamenti in tempo reale direttamente sulla schermata di blocco e nella Dynamic Island. Grazie a expo-apple-targets, alla Expo Modules API e agli spunti della community (sì, thread di Reddit compresi), realizzarla è stato piuttosto semplice. Le Live Activities sono un modo potente per rendere le app più connesse e dinamiche

Ecco il link GitHub al repo con il codice sorgente completo 👉🏻 https://github.com/tarikfp/expo-live-activity-timer