> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Aplicativo de exemplo: Live Activities

> Como o aplicativo de exemplo Clean Beans inicia, atualiza e encerra Live Activities do iOS a partir do backend, com o código do widget e as solicitações à API.

Esta página faz parte de [Aplicativo de exemplo: uma integração completa do OneSignal](https://documentation.onesignal.com/docs/pt-BR/example-full-integration-overview.md), que acompanha um aplicativo real do início ao fim. O aplicativo é o **Clean Beans**, uma escala de limpeza para casas compartilhadas, construído com Expo (React Native) e um backend Supabase.

Uma Live Activity é uma pequena visualização atualizada ao vivo na tela de bloqueio do iOS e na Dynamic Island. O Clean Beans usa duas: uma contagem regressiva até a janela de limpeza do usuário e um alerta quando uma sequência está prestes a terminar.

![Uma Live Activity de lembrete de limpeza na tela de bloqueio do iOS](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-LiveActivity-countdown.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=d3e51363076f6271d5f47cfec850e5e2)

O lembrete de limpeza em contagem regressiva na tela de bloqueio.

As Live Activities normalmente são iniciadas pelo aplicativo. O Clean Beans as inicia a partir do backend, porque elas precisam aparecer em um horário definido, com o aplicativo aberto ou não. O **push-to-start** do OneSignal torna isso possível.

## Configurar o aplicativo \\

Um aplicativo multiplataforma pode deixar o OneSignal gerenciar o ciclo de vida da Live Activity. Uma única chamada na inicialização é todo o JavaScript necessário.

```typescript app/_layout.tsx theme={null}
// Enable Live Activities with the default attributes type
OneSignal.LiveActivities.setupDefault({
  enablePushToStart: true,
  enablePushToUpdate: true,
});
```

O único código nativo que você escreve é o layout do widget, em SwiftUI. O Clean Beans adiciona a extensão do widget ao projeto iOS com um pequeno plugin de configuração do Expo, para que o projeto continue podendo ser gerado do zero a cada compilação.

```javascript plugins/withLiveActivityWidget.js theme={null}
const WIDGET_TARGET_NAME = "CleanBeansWidgetExtension";
const WIDGET_BUNDLE_ID_SUFFIX = ".CleanBeansWidgetExtension";
const DEPLOYMENT_TARGET = "16.2";
```

## Desenhar o widget \\

O widget usa o `DefaultLiveActivityAttributes` do OneSignal, que carrega dados livres. Um único widget atende as duas atividades lendo um valor `type` e escolhendo um layout.

```swift plugins/widget/CleanBeansWidgetLiveActivity.swift theme={null}
struct CleanBeansWidgetLiveActivity: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: DefaultLiveActivityAttributes.self) { context in
            // Dispatch based on activity type
            let activityType = context.attributes.data["type"]?.asString() ?? "streak-warning"

            if activityType == "cleaning-reminder" {
                CleaningReminderLockScreen(context: context)
            } else {
                StreakWarningLockScreen(context: context)
            }

        } dynamicIsland: { context in
            let activityType = context.attributes.data["type"]?.asString() ?? "streak-warning"

            if activityType == "cleaning-reminder" {
                return cleaningReminderDynamicIsland(context: context)
            } else {
                return streakWarningDynamicIsland(context: context)
            }
        }
    }
}
```

Cada layout lê seus valores dos dados que o backend enviou. Os `attributes` são fixados quando a atividade começa. O `state` pode mudar a cada atualização.

```swift plugins/widget/CleanBeansWidgetLiveActivity.swift theme={null}
let title = context.attributes.data["title"]?.asString() ?? "Streak Warning"
let message = context.state.data["message"]?.asDict()?["en"]?.asString()
    ?? "Your streak is at risk!"
let streakCount = context.state.data["streakCount"]?.asInt() ?? 0
let midnightTs = context.state.data["midnightTs"]?.asInt() ?? 0
let midnightDate = Date(timeIntervalSince1970: Double(midnightTs))
```

Uma contagem regressiva é desenhada com o estilo de timer do SwiftUI, que avança no dispositivo sem mais atualizações do servidor.

## Alerta de sequência: iniciar uma atividade a partir do backend \\

Às 19h no horário local, quem tem uma sequência e ainda não limpou nada no dia recebe uma contagem regressiva até a meia-noite. A função horária encontra essas pessoas usando a mesma correspondência de fuso horário dos lembretes push e depois inicia uma atividade para cada uma.

```typescript supabase/functions/streak-warning/index.ts theme={null}
const payload = {
  event: 'start',
  activity_id: activityId,
  include_aliases: {
    external_id: [user.id],
  },
  target_channel: 'push',
  event_attributes: {
    data: {
      title: 'Streak Warning',
    },
  },
  event_updates: {
    data: {
      message: {
        en: `Your ${user.streakCount}-day streak ends at midnight!`,
      },
      streakCount: user.streakCount,
      midnightTs: user.midnightTs,
      userName: user.name,
    },
  },
  name: 'Streak Warning',
  contents: {
    en: `Your ${user.streakCount}-day streak ends at midnight!`,
  },
  headings: {
    en: 'Streak at risk!',
  },
  priority: 10,
};

const res = await fetch(
  `https://api.onesignal.com/apps/${ONESIGNAL_APP_ID}/activities/activity/DefaultLiveActivityAttributes`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Key ${ONESIGNAL_REST_API_KEY}`,
    },
    body: JSON.stringify(payload),
  }
);
```

![Uma Live Activity de alerta de sequência em contagem regressiva até a meia-noite](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-LA-warning.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=586ca54b6a57f7d1647d5e9bb5aa874f)

O alerta de sequência em contagem regressiva até a meia-noite.

## Lembrete de limpeza: iniciar, atualizar, encerrar \\

O lembrete de limpeza passa por três fases. Cada uma é uma solicitação separada para a mesma atividade.

| Fase | Quando | Solicitação | O que o widget mostra |
| - | - | - | - |
| Contagem regressiva | Uma hora antes da janela | `start` | Um timer em contagem regressiva até o horário de início |
| Ativa | A janela abre | `update` | "It's your scheduled cleaning time, jump to it!" |
| Encerrada | A janela fecha | `end` | Dispensada após cinco segundos |

A função calcula em qual fase cada usuário deve estar.

```typescript supabase/functions/cleaning-activity/index.ts theme={null}
function getDesiredPhase(
  currentHour: number,
  window: CleaningWindow,
): 'countdown' | 'active' | null {
  const reminderHour = (window.start - 1 + 24) % 24;

  // Active: inside the cleaning window
  if (isHourInRange(currentHour, window.start, window.end)) return 'active';

  // Countdown: the single hour before the window starts
  if (currentHour === reminderHour) return 'countdown';

  return null;
}
```

Ela armazena a fase atual no perfil do usuário e só envia uma solicitação quando a fase desejada é diferente. Isso torna seguro executar o job horário repetidamente.

Atualizar e encerrar usam um endpoint diferente do de início. A atividade é indicada na URL, então essas solicitações não têm segmentação.

```typescript supabase/functions/cleaning-activity/index.ts theme={null}
async function updateCleaningActivity(activityId: string): Promise<boolean> {
  const payload = {
    event: 'update',
    event_updates: {
      data: {
        message: { en: "It's your scheduled cleaning time, jump to it!" },
        phase: 'active',
        targetTs: 0,
      },
    },
    name: 'Cleaning Active',
    contents: { en: "It's your scheduled cleaning time!" },
    priority: 10,
  };

  // ...
}

async function endCleaningActivity(activityId: string): Promise<boolean> {
  const payload = {
    event: 'end',
    event_updates: {
      data: {
        message: { en: 'Cleaning window ended' },
        phase: 'ended',
      },
    },
    name: 'Cleaning Ended',
    dismissal_date: Math.floor(Date.now() / 1000) + 5, // dismiss after 5s
    priority: 10,
  };

  // ...
}
```

> [!NOTE]
>
> Essas solicitações usam `priority: 10` porque cada uma é uma mudança de fase que deve aparecer imediatamente, e uma pessoa recebe no máximo algumas por dia. A prioridade `10` conta para o orçamento que a Apple permite a cada dispositivo para atualizações de Live Activity. Para qualquer coisa que seja atualizada com frequência, como um placar ou uma barra de progresso, comece com `5`.

> [!WARNING]
>
> Envie atualizações e encerramentos para `/apps/{app_id}/live_activities/{activity_id}/notifications`, e não para o endpoint de início. O Clean Beans enviava originalmente as três para o endpoint de início, e toda atualização e todo encerramento eram rejeitados com "Missing required parameter - event\_attributes".

> [!NOTE]
>
> Dê a cada atividade seu próprio `activity_id` e armazene-o quando a atividade começar. O OneSignal não aceita mais atualizações para um `activity_id` depois que a atividade termina, então um ID fixo por usuário pararia de funcionar após o primeiro dia.

> [card] [Configuração multiplataforma](https://documentation.onesignal.com/docs/pt-BR/cross-platform-live-activity-setup.md)
>
> `setupDefault` e a extensão do widget.

> [card] [Iniciar Live Activity](https://documentation.onesignal.com/reference/start-live-activity.md)
>
> A API de push-to-start.

> [card] [Atualizar Live Activity](https://documentation.onesignal.com/reference/update-live-activity-api.md)
>
> Solicitações de atualização e encerramento.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.