> ## 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.

# 예제 앱: Live Activities

> 예제 앱 Clean Beans가 백엔드에서 iOS Live Activities를 시작, 업데이트, 종료하는 방법을 위젯 코드 및 API 요청과 함께 소개합니다.

이 페이지는 실제 앱 하나를 처음부터 끝까지 따라가는 [예제 앱: OneSignal 전체 통합](https://documentation.onesignal.com/docs/ko/example-full-integration-overview.md)의 일부입니다. 앱은 공유 주택을 위한 청소 당번표 앱인 **Clean Beans**이며, Expo(React Native)와 Supabase 백엔드로 만들어졌습니다.

Live Activity는 iOS 잠금 화면과 Dynamic Island에 표시되는, 실시간으로 업데이트되는 작은 화면입니다. Clean Beans는 두 가지를 사용합니다. 사용자의 청소 시간대까지의 카운트다운과, 연속 기록이 끊기기 직전의 경고입니다.

![iOS 잠금 화면의 청소 알림 Live Activity](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-LiveActivity-countdown.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=d3e51363076f6271d5f47cfec850e5e2)

잠금 화면에서 카운트다운하는 청소 알림.

Live Activities는 보통 앱이 시작합니다. Clean Beans는 앱이 열려 있든 아니든 정해진 시간에 나타나야 하므로 백엔드에서 시작합니다. OneSignal의 **push-to-start**가 이를 가능하게 합니다.

## 앱 설정하기 \\

크로스 플랫폼 앱은 Live Activity의 수명 주기 관리를 OneSignal에 맡길 수 있습니다. 시작 시 호출 한 번이면 필요한 JavaScript는 끝입니다.

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

직접 작성하는 네이티브 코드는 SwiftUI로 만드는 위젯 레이아웃뿐입니다. Clean Beans는 작은 Expo config 플러그인으로 위젯 확장을 iOS 프로젝트에 추가하므로, 빌드할 때마다 프로젝트를 처음부터 생성할 수 있습니다.

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

## 위젯 그리기 \\

위젯은 자유 형식 데이터를 담는 OneSignal의 `DefaultLiveActivityAttributes`를 사용합니다. 위젯 하나가 `type` 값을 읽어 레이아웃을 선택하는 방식으로 두 활동을 모두 처리합니다.

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

각 레이아웃은 백엔드가 보낸 데이터에서 값을 읽습니다. `attributes`는 활동이 시작될 때 고정됩니다. `state`는 업데이트마다 바뀔 수 있습니다.

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

카운트다운은 SwiftUI의 타이머 스타일로 그려지며, 서버의 추가 업데이트 없이 기기에서 시간이 흘러갑니다.

## 연속 기록 경고: 백엔드에서 활동 시작하기 \\

현지 시간 오후 7시에, 연속 기록이 있으면서 오늘 아직 청소하지 않은 사람은 자정까지의 카운트다운을 받습니다. 매시간 실행되는 함수가 푸시 알림과 같은 시간대 일치 방식으로 대상자를 찾은 다음 각자에게 활동을 시작합니다.

```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),
  }
);
```

![자정까지 카운트다운하는 연속 기록 경고 Live Activity](https://mintcdn.com/onesignal/XdN288-p34EfpfHk/images/tutorials/cleanbeans-LA-warning.png?fit=max\&auto=format\&n=XdN288-p34EfpfHk\&q=85\&s=586ca54b6a57f7d1647d5e9bb5aa874f)

자정까지 카운트다운하는 연속 기록 경고.

## 청소 알림: 시작, 업데이트, 종료 \\

청소 알림은 세 단계를 거칩니다. 각 단계는 같은 활동에 대한 별도의 요청입니다.

| 단계 | 시점 | 요청 | 위젯에 표시되는 내용 |
| - | - | - | - |
| 카운트다운 | 시간대 1시간 전 | `start` | 시작 시간까지 카운트다운하는 타이머 |
| 활성 | 시간대 시작 | `update` | "It's your scheduled cleaning time, jump to it!" |
| 종료 | 시간대 종료 | `end` | 5초 후 사라짐 |

함수는 각 사용자가 어느 단계에 있어야 하는지 계산합니다.

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

현재 단계를 사용자 프로필에 저장하고, 원하는 단계가 다를 때만 요청을 보냅니다. 덕분에 매시간 작업을 반복 실행해도 안전합니다.

업데이트와 종료는 시작과 다른 엔드포인트를 사용합니다. 활동은 URL에 지정되므로 이 요청에는 타겟팅이 없습니다.

```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]
>
> 이 요청들은 각각 즉시 표시되어야 하는 단계 변화이고 한 사람이 하루에 많아야 몇 번 받으므로 `priority: 10`을 사용합니다. 우선순위 `10`은 Apple이 기기마다 Live Activity 업데이트에 허용하는 예산에서 차감됩니다. 점수나 진행률 표시줄처럼 자주 업데이트되는 경우에는 `5`로 시작하세요.

> [!WARNING]
>
> 업데이트와 종료는 시작 엔드포인트가 아니라 `/apps/{app_id}/live_activities/{activity_id}/notifications`로 보내세요. Clean Beans는 처음에 세 가지 요청을 모두 시작 엔드포인트로 보냈고, 모든 업데이트와 종료가 "Missing required parameter - event\_attributes"로 거부되었습니다.

> [!NOTE]
>
> 활동마다 고유한 `activity_id`를 부여하고 활동이 시작될 때 저장하세요. OneSignal은 활동이 종료된 `activity_id`에 대한 추가 업데이트를 받지 않으므로, 사용자마다 고정된 ID를 쓰면 첫날 이후에는 동작하지 않습니다.

> [card] [크로스 플랫폼 설정](https://documentation.onesignal.com/docs/ko/cross-platform-live-activity-setup.md)
>
> `setupDefault`와 위젯 확장.

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

> [card] [Live Activity 업데이트](https://documentation.onesignal.com/reference/update-live-activity-api.md)
>
> 업데이트 및 종료 요청.


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