# Timer com Live Activity no Expo

By Tarik Pinarci (https://tarikpinarci.com). Published 2025-05-01. Canonical: https://tarikpinarci.com/pt/blog/expo-live-activity-timer

# Construindo um timer com Live Activity no Expo

As Live Activities no iOS mudam o jogo: elas permitem que os apps mostrem atualizações em tempo real direto na Tela Bloqueada ou na Dynamic Island. Naturalmente, comecei a imaginar como seria legal ter um timer de treino rodando ali, mantendo os usuários motivados sem nem precisar desbloquear o celular. Mas havia um porém: as Live Activities são construídas com as ferramentas nativas da Apple, como Swift e ActivityKit. Foi aí que descobri uma ferramenta chamada [expo-apple-targets](https://github.com/EvanBacon/expo-apple-targets), que me poupou de escrever módulos inteiros do zero e deixou o processo muito mais fácil do que eu esperava. Neste artigo, vou mostrar como construí uma Live Activity baseada em timer para iOS, os passos que segui e o que aprendi no caminho.

## Por que fiquei obcecado por Live Activities

As Live Activities não são só um truque legal: elas mudam o jogo no engajamento dos usuários. As [Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/live-activities) da Apple as descrevem como uma forma de entregar "informação atual, que se entende num relance" para tarefas sensíveis ao tempo. Imagine um app fitness mostrando o tempo da sua prancha no meio do treino, um app de delivery acompanhando o caminho da sua pizza ou um app de corrida atualizando a previsão de chegada do motorista, tudo direto na Tela Bloqueada ou, no iPhone 14 Pro e modelos posteriores, na Dynamic Island. É como dar aos usuários um passe VIP para as atualizações mais importantes do seu app sem que eles precisem desbloquear o celular.

Eu queria que os usuários vissem o timer do treino subindo durante uma série, mantendo o foco sem precisar abrir o app. É o tipo de acabamento que faz um app parecer profissional, e eu estava totalmente dentro. Mas não dá para fazer tudo isso sem mexer em nenhuma camada nativa, então eu sabia que ia mergulhar em Swift e brigar com o Xcode. Aí descobri o [expo-apple-targets](https://github.com/EvanBacon/expo-apple-targets), um pacote que faz a ponte entre o mundo JavaScript do Expo e os recursos nativos do iOS. Muito crédito ao [Evan Bacon](https://x.com/Baconbrix): essa ferramenta pegou uma tarefa assustadora e a transformou em um quebra-cabeça desafiador, mas possível.

## O panorama geral: Live Activities em um app Expo

As Live Activities são uma festa exclusiva do iOS. Elas funcionam com o ActivityKit, um framework baseado em Swift, o que significa que você vai escrever código nativo, querendo ou não. Para um app Expo, isso é como tentar convencer um peixe a subir em uma árvore: é possível, mas vai dar trabalho. O expo-apple-targets entra como um guia experiente, oferecendo uma estrutura para criar módulos nativos e widget extensions sem começar do zero. Ele é construído sobre o sistema de módulos do Expo ([Expo Modules API](https://docs.expo.dev/modules/module-api/)), que permite escrever código nativo em Swift e expô-lo ao JavaScript, deixando o processo todo bem menos parecido com um tratamento de canal.

## Configurando o projeto

Começar não foi exatamente um passeio no parque, mas o expo-apple-targets deixou tudo administrável. Assim dei a largada:

- **Instalando o expo-apple-targets**: um rápido npm install expo-apple-targets e eu já estava rodando. O README do pacote é uma mina de ouro: ele guia você para adicionar uma widget extension no Xcode e atualizar o app.json com o entitlement de Live Activity (com.apple.developer.activitykit).

- **Setup do módulo nativo**: usei o sistema de módulos do Expo para criar um módulo Swift que conversa com o ActivityKit. A [documentação do Expo Modules](https://docs.expo.dev/modules/module-api/) enfatiza definir assinaturas de funções e eventos claros, o que me ajudou a expor métodos como startActivity ao JavaScript sem suar a camisa.

- **Widget extension**: foi aqui que o SwiftUI entrou, permitindo desenhar o visual da Live Activity para a Tela Bloqueada e a Dynamic Island. O expo-apple-targets oferece um template de widget, mas precisei personalizá-lo para mostrar um timer correndo e botões interativos.

- **Intents**: eles permitem que os usuários toquem em botões no widget para pausar ou retomar o timer. O expo-apple-targets simplifica o setup dos intents, mas mesmo assim tive que depurar algumas falhas para fazer as notificações fluírem direito.

## Um timer atualizado a cada segundo?

![Um desenvolvedor empolgado implementa uma atualização de timer a cada segundo, levando a uma sobrecarga caótica do sistema enquanto o timer causa estragos. ([Gerado pelo gpt-4o](https://openai.com/index/hello-gpt-4o/))](https://cdn-images-1.medium.com/max/2048/1*Nq1a3rqsEIBCgTsAWdvgNQ.png)_Um desenvolvedor empolgado implementa uma atualização de timer a cada segundo, levando a uma sobrecarga caótica do sistema enquanto o timer causa estragos. ([Gerado pelo gpt-4o](https://openai.com/index/hello-gpt-4o/))_

Quando encarei o timer pela primeira vez, o meu cérebro disse: "_É só atualizar a Live Activity a cada segundo com a hora atual_." Parece simples, né? Errado. Encontrei uma [thread no Reddit](https://www.reddit.com/r/iOSProgramming/comments/18n12wh/how_does_this_app_achieve_to_update_its_live/?rdt=52173) em que devs discutiam a possibilidade de atualizar o timer da Live Activity. O veredito foi unânime: atualizar a cada segundo é um desastre. É como tentar mover uma nave espacial com uma roda de hamster: ela anda, mas vai queimar rápido. Atualizações constantes martelam a CPU e drenam a bateria, deixando o app lento.

Aquela thread do Reddit foi um alerta. Encontrei o Text(timerInterval:) do SwiftUI na [documentação do SwiftUI](<https://developer.apple.com/documentation/swiftui/text/init(timerinterval:pausetime:countsdown:showshours:)>) da Apple, e foi uma revelação. Essa view cuida das atualizações do timer de forma nativa, contando sem precisar atualizar a Live Activity inteira. É como terceirizar a parte chata para o iOS para você focar na parte divertida.

Então abandonei o plano de atualizar a cada segundo e fui com uma abordagem de startedAt/pausedAt. Veja por que ela vence:

- **Performance**: em vez de disparar atualizações a cada segundo, guardo o horário de início do timer (startedAt) e o horário da pausa (pausedAt, se estiver pausado). O widget usa Text(timerInterval:) para mostrar um timer ao vivo baseado em startedAt e, quando pausado, exibe um tempo estático usando pausedAt. Isso reduz as chamadas de API a quase zero.

- **Eficiência de bateria**: atualizações frequentes são um vampiro de bateria. Deixar o SwiftUI cuidar da contagem mantém o app leve e os celulares dos usuários felizes.

- **Conformidade com a API**: as APIs de Live Activity da Apple não foram feitas para spam em tempo real. O setup com startedAt/pausedAt se dá bem com o que o iOS espera, reduzindo a chance de rate limiting.

- **Simplicidade do código**: gerenciar dois timestamps é muito mais fácil do que fazer malabarismo com um fluxo de atualizações. Mantém o código limpo e o meu nível de estresse sob controle.

Essa abordagem foi como achar um atalho secreto em um videogame. O timer roda liso, fica bonito e não consome recursos à toa. A thread do Reddit ([aqui está ela de novo](https://www.reddit.com/r/iOSProgramming/comments/18n12wh/how_does_this_app_achieve_to_update_its_live/?rdt=52173)) merece uma medalha por me apontar a direção certa.

## O coração da Live Activity

Não vou te entediar com cada linha de código. Vamos focar nos trechos principais que fazem esse timer funcionar. Vou compartilhar o código-fonte completo no GitHub no fim do artigo.

### A struct LiveActivityAttributes

Essa struct é a espinha dorsal da Live Activity: ela define os dados e como eles evoluem.

```swift
    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
    }
```

Isso é como o DNA da Live Activity. A LiveActivityAttributes externa guarda as coisas estáticas, activityName (por exemplo, "Workout") e activityIcon (por exemplo, "RUNNING"), definidas quando a atividade começa. A ContentState interna é onde a ação acontece, acompanhando startedAt (quando o timer começou) e pausedAt (quando foi pausado, se foi). Os métodos auxiliares são os verdadeiros MVPs:

- getElapsedTimeInSeconds() calcula há quanto tempo o timer está rodando, parando em pausedAt se estiver pausado, ou usando a hora atual se estiver ativo. Isso mantém a lógica enxuta e reutilizável.

- isRunning() é uma verificação simples: se pausedAt é null, o timer está ativo. É uma forma limpa de evitar verificações de estado bagunçadas em outros lugares.

- getFormattedElapsedTime() transforma segundos em uma string bonita "MM:SS" ou "HH:MM:SS" para o widget. Adicionei suporte a horas depois de perceber que alguns usuários podem fazer treinos ultralongos, como maratonas.

- getFutureDate() define uma data daqui a um ano, que passo para o Text(timerInterval:) para deixar o timer rodar indefinidamente sem me preocupar com uma data de fim.

Adoro como essa struct mantém tudo organizado. É como uma mochila bem arrumada: tudo de que você precisa e nada de que não precisa. A conformidade com Codable e Hashable facilita serializar para as atualizações e usar no SwiftUI, o que salvou a minha vida na hora de sincronizar o estado entre o módulo e o widget.

### Iniciando a Live Activity

A função startActivity é onde a mágica começa, dando início a uma nova Live Activity.

```swift
    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 ""
    }
```

Essa função é a faísca que acende o fogo. Ela é exposta ao JavaScript pelo sistema de módulos do Expo, permitindo que o meu app React Native a chame com um nome e um ícone. Veja o que ela faz:

- Verifica se é iOS 16.2 ou posterior. As Live Activities não existem antes disso.

- Chama endAllActivities() para limpar qualquer atividade existente. O iOS permite várias Live Activities, mas eu queria uma por vez para evitar confusão.

- Define startedAt como a hora atual e limpa pausedAt, preparando o timer para rodar.

- Verifica se as Live Activities estão ativadas (os usuários podem desativá-las nos Ajustes, o que me deixou perdido no começo).

- Monta uma LiveActivityAttributes com o nome e o ícone informados, e uma ContentState com o horário de início.

- Solicita uma nova atividade via Activity.request, que me devolve um objeto Activity com um ID único.

- Guarda o ID, dispara um evento de atualização para o JavaScript e retorna o ID para que o app possa acompanhá-lo.

### Pausando o timer

A pausa do timer é tratada pela performPause, que atualiza o estado da Live Activity.

```swift
    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
    }
```

É aqui que a abordagem com startedAt/pausedAt brilha. Quando o usuário pausa o timer (pelo app ou pelo widget), essa função:

- Verifica se estamos no iOS 16.2 e se o timer ainda não está pausado (nada de pausar duas vezes).

- Pega o ID da atividade, usando currentActivityId como alternativa se nenhum for informado.

- Encontra a atividade usando findActivityById, que busca entre as atividades ativas.

- Define pausedAt como a hora atual, congelando o timer.

- Cria uma nova ContentState com o startedAt original e o novo pausedAt.

- Atualiza a atividade com activity.update, dizendo ao widget para mostrar o tempo pausado.

- Envia um evento para o JavaScript para manter a UI do app sincronizada.

A lógica aqui é toda sobre precisão: cada verificação (como pausedAt == nil) está ali para evitar casos extremos estranhos, como pausar uma atividade que não existe. Me apoiei na [documentação do Expo Modules](https://docs.expo.dev/modules/overview/) para o tratamento de eventos, usando sendEvent para enviar atualizações ao JavaScript. As primeiras versões dessa função não validavam o startedAt, o que gerou alguns timers bem esquisitos na tela. Lição aprendida: sempre proteja o seu estado.

## A view da Tela Bloqueada

A LockScreenLiveActivityView é o que os usuários veem quando o celular está bloqueado, e ela precisa ficar bonita.

![Live Activity na Tela Bloqueada](https://cdn-images-1.medium.com/max/2000/1*IZ1ZSG7_99jfTMBJosePGQ.png)_Live Activity na Tela Bloqueada_

```swift
    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)
            }
        }
    }
```

Esse é o coração visual da Live Activity, e é onde o SwiftUI realmente mostra o seu poder. A view é dividida em dois lados:

- **Lado esquerdo**: mostra o nome da atividade, o ícone e o timer. Se o timer está rodando, o Text(timerInterval:) faz o trabalho pesado, contando a partir de startedAt até daqui a um ano (graças ao getFutureDate). Se está pausado, exibe um tempo estático vindo do getFormattedElapsedTime. O modificador .monospacedDigit() mantém os números nítidos, e ajustei a fonte para ficar em negrito e legível.

- **Lado direito**: cuida dos botões. Quando está rodando, aparece um botão azul de pausa. Quando está pausado, você tem um check verde para abrir o app e um botão azul de play para retomar. Cada botão dispara um intent, que o módulo nativo captura e processa.

## Mergulhando na [Dynamic Island](https://developer.apple.com/design/human-interface-guidelines/live-activities#The-Dynamic-Island)

![View da Dynamic Island](https://cdn-images-1.medium.com/max/2000/1*iqy0d6FZe9UU0Tce7qCDug.png)_View da Dynamic Island_

Este trecho define como a Live Activity aparece nos três modos da Dynamic Island: expanded (visão completa), compact (espremida) e minimal (o mínimo possível).

```swift
    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)
      }
    }
```

- [\*\*Modo Expanded](https://developer.apple.com/design/human-interface-guidelines/live-activities#Expanded-presentation)\*\*: aparece com um toque longo e é dividido em .leading e .trailing. O lado leading empilha o ícone (por exemplo, uma figura correndo) e o nome ("Workout") com um timer grande, estático quando pausado (getFormattedElapsedTime) e correndo quando ativo (Text(timerInterval:)). O lado trailing tem os botões: um botão azul de pausa quando está rodando, ou um check verde (abrir o app) e um play azul (retomar) quando está pausado. Ajustei fontes e espaçamentos para caber nas curvas da Island.

- [\*\*Modo Compact](https://developer.apple.com/design/human-interface-guidelines/live-activities#Compact-presentation)\*\*: quando o espaço diminui, o compactLeading mostra um ícone pequeno e o nome truncado, enquanto o compactTrailing exibe o timer (estático ou correndo). O .lineLimit(1) mantém o nome arrumado, e uma fonte de 12 pontos garante a legibilidade.

- [\*\*Modo Minimal](https://developer.apple.com/design/human-interface-guidelines/live-activities#Minimal-presentation)\*\*: superapertado, é só um ícone de 12 pontos, como um haltere, para dizer "o timer ainda está aqui". Simples, mas eficaz.

## A pasta \_shared: por que ela é tão importante

![Visão geral da pasta _shared](https://cdn-images-1.medium.com/max/2000/1*OdZlqw2AXJeTakpTlghLDQ.png)_Visão geral da pasta \_shared_

A pasta \_shared no [expo-apple-targets](https://github.com/EvanBacon/expo-apple-targets?tab=readme-ov-file#_shared) é um diretório de nível superior feito para ligar código essencial tanto ao target principal do app quanto aos sub-targets, como o widget da Live Activity.

Extensions, como os widgets, rodam em processos separados e precisam que arquivos específicos estejam ligados ao seu target e também ao do app principal. A pasta \_shared garante que esses arquivos sejam ligados automaticamente aos dois, eliminando a configuração manual. Para o meu timer, coloquei a struct LiveActivityAttributes aqui, garantindo que o app e o widget compartilhassem o mesmo estado do timer (startedAt, pausedAt) sem problemas de sincronização.

## Abrindo o app a partir do widget da Live Activity

O CompleteIntent permite que os usuários toquem em um botão de check no widget da Live Activity para abrir o app, sinalizando que terminaram com o timer. É uma interação simples, mas crucial, para encerrar um treino.

```swift
    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 o usuário toca no check verde, esse intent dispara e publica uma notificação completeActivityFromWidget. O módulo nativo a captura, dispara o evento onWidgetCompleteActivity para o JavaScript, e o iOS abre o app graças ao [openAppWhenRun](https://developer.apple.com/documentation/appintents/openurlintent/openappwhenrun): true.

## Tratando os toques do usuário com intents

O PauseIntent é um dos intents que tornam o widget interativo.

![Intents da Live Activity na Tela Bloqueada](https://cdn-images-1.medium.com/max/2000/1*k2nzvHgwgqj6tFESIFcmbw.png)_Intents da Live Activity na Tela Bloqueada_

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

Esse intent é disparado quando o usuário toca no botão de pausa do widget. É simples demais, mas poderoso:

- Ele publica uma notificação (pauseTimerFromWidget) que o módulo nativo captura via setupNotificationObservers.

- O módulo então executa performPause, atualizando o estado da Live Activity e notificando o JavaScript.

A beleza aqui é como os intents criam um ciclo fluido: o usuário toca → o intent dispara → o módulo atualiza → o app continua sincronizado. O expo-apple-targets deixou o setup dos intents muito fácil ao oferecer um template, mas mesmo assim precisei depurar um caso em que os toques não eram registrados. No fim, eu tinha escrito errado o nome de uma notificação. Clássico. A [documentação do Expo Modules](https://docs.expo.dev/modules/overview/) me ajudou a entender como tratar eventos disparados por ações nativas, o que foi fundamental para isso funcionar.

## Eventos conversando com o JavaScript

![](https://cdn-images-1.medium.com/max/2000/1*F5GUBNYqWxbZbLU8-LZ0Ug.png)

Os eventos da seção a seguir são a forma como o módulo nativo mantém o app React Native sincronizado com o estado da Live Activity, usando o sistema de eventos do Expo.

### onWidgetCompleteActivity

Esse evento dispara quando o usuário toca no check para concluir a atividade, acionado pelo CompleteIntent.

```swift
    @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)
        ])
    }
```

O completeIntentHandler captura a notificação completeActivityFromWidget, calcula o tempo decorrido e envia o evento onWidgetCompleteActivity para o JavaScript com o ID da atividade e os segundos decorridos. O JavaScript pode então atualizar a UI do app ou registrar a conclusão do treino.

### onLiveActivityUpdate

Esse evento dispara sempre que o estado do timer muda (por exemplo, pausa ou retomada).

```swift
    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
        ])
    }
```

Chamado depois das mudanças de estado (como em performPause ou performResume), ele envia o evento onLiveActivityUpdate com o estado atual ("active" ou "paused"), o tempo decorrido e o ID da atividade. O JavaScript escuta esse evento para manter a UI do timer no app sincronizada com o widget.

Os dois eventos criam um ciclo de feedback bem fechado entre o módulo nativo e o JavaScript.

## Por que tudo isso importa

Essa Live Activity não é só um timer: é uma funcionalidade que faz o meu app parecer um cidadão nativo do iOS. Veja por que isso é importante:

- **Engajamento dos usuários**: mostrar um timer na Tela Bloqueada ou na Dynamic Island mantém os usuários conectados ao app sem quebrar o fluxo deles. É perfeito para treinos, em que cada segundo conta.

- **Acabamento nativo**: o design limpo do widget e os botões interativos fazem o app parecer que pertence ao iOS, e não algo multiplataforma feito às pressas.

- **Performance**: a abordagem com startedAt/pausedAt, movida pelo Text(timerInterval:), garante que o timer rode liso sem drenar a bateria nem esbarrar nos limites da API.

O expo-apple-targets e a [Expo Modules API](https://docs.expo.dev/modules/module-api/) foram os heróis anônimos aqui, oferecendo uma estrutura robusta para fazer a ponte entre JavaScript e Swift. A ênfase da documentação em definições de funções limpas e no tratamento de eventos manteve o meu código organizado e fácil de manter.

## Considerações finais

Essa Live Activity dá ao app uma sensação fluida e nativa, mostrando atualizações em tempo real direto na Tela Bloqueada e na Dynamic Island. Graças ao expo-apple-targets, à Expo Modules API e às dicas da comunidade (sim, threads do Reddit incluídas), dar vida a ela foi bem tranquilo. As Live Activities são uma forma poderosa de deixar os apps mais conectados e dinâmicos.

Aqui está o link do GitHub com o repositório completo 👉🏻 [https://github.com/tarikfp/expo-live-activity-timer](https://github.com/tarikfp/expo-live-activity-timer)

