Getting Started

설치

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-live-activities`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/live-activities/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

설치

플러그인을 설치하기 위해 AI-Assisted Setup을 사용할 수 있습니다. AI 도구에 Capgo 스킬을 추가하려면 다음 명령어를 사용하세요:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

그다음에 다음 프롬프트를 사용하세요:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-live-activities` plugin in my project.

만약 Manual Setup을 선호한다면, 플러그인을 설치하기 위해 다음 명령어를 실행하고 아래의 플랫폼별 지침을 따르세요:

bun add @capgo/capacitor-live-activities
bunx cap sync

iOS 설정

플러그인을 설치하고 동기화하는 것은 네이티브 Live Activity UI를 생성하지 않습니다. ActivityKit은 Live Activity 구성이 등록된 위젯 확장자가 있어야 Live Activity UI를 표시할 수 있습니다. startActivity Live Activity UI를 표시하기 위해서는 위젯 확장자가 필요합니다.

요구 사항

iOS 기기나 호환 가능한 시뮬레이터에서 테스트하세요. 동적 섬유는 지원되는 기기 모델에서만 나타나며, 다른 기기는 Lock Screen 표시를 사용합니다.
ActivityKit 데이터의 정적 및 동적 데이터를 Apple의 4 KB 제한 이하로 유지하세요.
1. 위젯 확장 생성

터미널 창

bunx cap open ios

그런 다음:

선택 파일 > 새 > 대상.
추가 위젯 확장.
활성화 실시간 활동 포함.
비활성화 구성 설정 의도 포함 앱이도 구성 가능한 위젯이 필요하다면 제외합니다.
생성된 확장을 메인 앱 대상에 포함하십시오.

Widget Extension은 다음을 포함해야 합니다. ActivityConfiguration 그리고 그것을 WidgetBundle에서 등록해야 합니다. 그것은 다음 Live Activity 표시를 제공해야 합니다:

Lock Screen
Dynamic Island 확장
Dynamic Island 축소
Dynamic Island 축소(leading 및 trailing)

Adding the target alone is not sufficient. The native app or plugin must call ActivityKit’s request, update, and end APIs. The extension must contain SwiftUI code that can decode and render the same ActivityAttributes 대상만 추가하는 것은 충분하지 않습니다. Native 앱 또는 플러그인은 ActivityKit의 request, update, end API를 호출해야 합니다. 확장에는 SwiftUI __CAPGO_KEEP_0__가 포함되어 있어 JSON 레이아웃을 디코딩하고 렌더링할 수 있어야 합니다. main 앱과 Widget Extension 대상 모두에 공유된 ActivityKit 모델을 포함해야 합니다. Xcode가 생성한 Live Activity 템플릿은 자동으로 이 플러그인에 전달된 JSON 레이아웃을 렌더링하지 않습니다. 확장도 호환 가능한 네이티브 레이아웃 렌더러가 필요합니다.

2. Live Activities 활성화

main 앱 대상의 Info.plist:

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

프로젝트가 자신의 Info.plist, 추가 실시간 활동 지원 Boolean 값이 YES 메인 앱 목표의 사용자 지정 iOS 목표 속성 대신에.

3. 공유 이미지를 위한 앱 그룹 구성

App Group은 saveImage, removeImage, listImages, 또는 cleanupImages을 사용할 때만 필요합니다. 플러그인은 메인 앱 번들 식별자에서 App Group 식별자를 추출합니다. 이 정확한 형식으로:

group.<MAIN_APP_BUNDLE_ID>.liveactivities

예를 들어, 번들 식별자 com.example.delivery must use:

group.com.example.delivery.liveactivities

Xcode에서, App Groups 메인 앱 대상과 위젯 확장 대상에 모두

능력을 추가하고, 동일한 식별자를 두 대상에 모두 활성화합니다.

라이브 활동 확장 프로그램은 네트워크에 접근할 수 없습니다. 메인 앱에서远程 이미지를 다운로드하고 공유 App Group에 저장한 후 라이브 활동에서 참조하세요. 번들 이미지는 위젯 확장 프로그램을 활성화하여 자산의 대상 소유권도 설정하세요.

4. 깊이 링크 구성 behavior.widgetUrl 사용할 때 tapUrl또는 타이머 시퀀스 myapp://order/12345Live 액티비티 시작하기 Info > URL 종류 설정.

5. 옵션: 서버 주도 업데이트 활성화

푸시 알림은 앱 내의 지역 업데이트에 필요하지 않습니다. 서버에서 Live 액티비티를 시작, 업데이트, 종료하려면:

Live 액티비티를 위한 푸시 알림 컨텍스트: Capgo 마케팅 웹사이트. 역할: 짧은 UI 레이블 또는 내비게이션 아이템. 메시지 키 `push_notifications` (푸시 알림).
메인 앱 대상에 푸시 알림 기능을 추가합니다.
ActivityKit 푸시 토큰을 획득하고 서버에 전송합니다. liveactivity ActivityKit 알림을 APNs를 통해 푸시 유형을 사용하여 전송합니다.
추가 NSSupportsLiveActivitiesFrequentUpdates 메인 앱에 추가 Info.plist 사용 사례가 빈번한 푸시 업데이트 요구 시에만 메인 앱에 추가

ActivityKit 푸시 토큰은 표준 사용자 알림 장치 토큰과 별도로 관리됩니다. 푸시 알림 기능만 활성화하는 것은 충분하지 않으며, 서버 주도 업데이트에는 네이티브 토큰 처리 및 APNs 백엔드가 필요합니다.

네이티브 설정 목록

호출하기 전에 startActivity, 다음을 확인하세요:

NSSupportsLiveActivities 활성화되어야 합니다.
위젯 확장기는 위젯 확장기가 등록하는 ActivityConfiguration.
네이티브 ActivityKit 구현과 위젯 확장기는 동일한 ActivityAttributes 타입을 사용합니다.
iOS 16.1 이상의 애플리케이션과 위젯 확장 배포 대상입니다.
iOS 설정에서 앱에 라이브 활동이 활성화되어 있습니다.
공유 이미지를 사용할 때는 두 대상 모두에 매칭되는 앱 그룹이 활성화되어 있습니다.
사용하는 모든 커스텀 URL 스키마 widgetUrl 또는 tapUrl Capacitor 라이브 업데이트의 대안을 비교하는 페이지에서 사용되는 HTML 텍스트 조각입니다. 역할: 장기 마케팅 또는 법률 문구. 페이지/영역: page alternatives.astro. Capgo 제품/브랜드 및 개발자 용어를 정확하게 유지합니다.

Appflow 비교/이동 마케팅 복사본에서 사용되는 HTML 텍스트 조각입니다. 역할: 장기 마케팅 또는 법률 문구. 페이지/영역: page ionic-appflow.astro. Capgo 제품/브랜드 및 개발자 용어를 정확하게 유지합니다.

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

API Overview

`areActivitiesSupported`

이 장치에서 Live 활동이 지원되는지 확인하세요. iOS 16.1 이상과 장치 지원이 필요합니다.

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { supported, reason } = await CapgoLiveActivities.areActivitiesSupported();
if (supported) {
  console.log('Live Activities are supported!');
} else {
  console.log('Not supported:', reason);
}

`startActivity`

지정된 레이아웃과 데이터와 함께 새로운 Live 활동을 시작합니다.

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { activityId } = await CapgoLiveActivities.startActivity({
  layout: {
    type: 'container',
    direction: 'horizontal',
    children: [
      { type: 'text', content: 'Order #{{orderNumber}}', fontSize: 16, fontWeight: 'bold' },
      { type: 'text', content: '{{status}}', fontSize: 14, color: '#666666' }
    ]
  },
  dynamicIslandLayout: {
    expanded: {
      leading: { type: 'image', source: 'sfSymbol', value: 'box.truck' },
      trailing: { type: 'text', content: '{{eta}}' },
      center: { type: 'text', content: '{{status}}' },
      bottom: { type: 'progress', value: 'progress' }
    },
    compactLeading: { type: 'image', source: 'sfSymbol', value: 'box.truck' },
    compactTrailing: { type: 'text', content: '{{eta}}' },
    minimal: { type: 'image', source: 'sfSymbol', value: 'box.truck' }
  },
  data: {
    orderNumber: '12345',
    status: 'On the way',
    eta: '10 min',
    progress: 0.6
  }
});
console.log('Started activity:', activityId);

`updateActivity`

기존 Live 활동을 새로운 데이터로 업데이트합니다.

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.updateActivity({
  activityId: 'abc123',
  data: {
    status: 'Arrived!',
    eta: 'Now',
    progress: 1.0
  },
  alertConfiguration: {
    title: 'Delivery Update',
    body: 'Your order has arrived!'
  }
});

`endActivity`

Live 활동을 종료합니다.

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.endActivity({
  activityId: 'abc123',
  data: { status: 'Delivered' },
  dismissalPolicy: 'after',
  dismissAfter: Date.now() + 3600000 // 1 hour from now
});

`getAllActivities`

현재 활성화된 모든 라이브 활동을 가져옵니다.

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { activities } = await CapgoLiveActivities.getAllActivities();
activities.forEach(activity => {
  console.log(`Activity ${activity.activityId}: ${activity.state}`);
});

`saveImage`

라이브 활동에서 사용할 수 있는 이미지를 공유 앱 그룹 컨테이너에 저장합니다. 이미지들은 공유 컨테이너에 저장되어야만 위젯 확장에서 접근할 수 있습니다.

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { success, imageName } = await CapgoLiveActivities.saveImage({
  imageData: 'base64EncodedImageData...',
  name: 'product-image',
  compressionQuality: 0.8
});
// Use in layout with: { type: 'image', source: 'saved', value: imageName }

`removeImage`

공유 앱 그룹 컨테이너에서 저장된 이미지를 삭제합니다.

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { success } = await CapgoLiveActivities.removeImage({ name: 'product-image' });

`listImages`

공유 앱 그룹 컨테이너에 저장된 모든 이미지를 목록화합니다.

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { images } = await CapgoLiveActivities.listImages();
console.log('Saved images:', images);

`cleanupImages`

공유 컨테이너에서 저장된 모든 이미지를 삭제하세요.

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.cleanupImages();

`startTimerSequence`

운동/스포츠를 위한 타이머 시퀀스를 시작하세요. iOS에서: Live Activity 및 Dynamic Island에 표시 Android에서: 타이머와 함께 전면 알림으로 표시

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const { sequenceId } = await CapgoLiveActivities.startTimerSequence({
  title: 'HIIT Workout',
  steps: [
    { duration: 30, title: 'Jumping Jacks', subtitle: 'Warm up', color: '#FF6B00', icon: 'figure.jumprope' },
    { duration: 10, title: 'Rest', color: '#00C853', icon: 'pause.circle' },
    { duration: 45, title: 'Burpees', subtitle: 'High intensity', color: '#FF0000', icon: 'flame.fill' },
    { duration: 15, title: 'Rest', color: '#00C853', icon: 'pause.circle' },
    { duration: 45, title: 'Mountain Climbers', color: '#FF0000', icon: 'figure.run' },
    { duration: 15, title: 'Rest', color: '#00C853', icon: 'pause.circle' },
  ],
  loop: true,
  loopCount: 3,
  soundEnabled: true,
  vibrateEnabled: true,
  countdownBeeps: true,
  tapUrl: 'myapp://workout/hiit'
});

`pauseTimerSequence`

타이머 시퀀스를 일시 정지하세요.

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.pauseTimerSequence({ sequenceId: 'abc123' });

`resumeTimerSequence`

클립보드에 복사

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.resumeTimerSequence({ sequenceId: 'abc123' });

`stopTimerSequence`

시퀀스 타이머를 중단하고 취소하세요.

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.stopTimerSequence({ sequenceId: 'abc123' });

`skipTimerStep`

시퀀스에서 다음 단계로 건너 뛰세요.

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.skipTimerStep({ sequenceId: 'abc123' });

`previousTimerStep`

시퀀스에서 이전 단계로 돌아가세요.

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

await CapgoLiveActivities.previousTimerStep({ sequenceId: 'abc123' });

`getTimerState`

클립보드에 복사하세요

import { CapgoLiveActivities } from '@capgo/capacitor-live-activities';

const state = await CapgoLiveActivities.getTimerState({ sequenceId: 'abc123' });
console.log(`Step ${state.currentStepIndex + 1}/${state.totalSteps}: ${state.currentStep.title}`);
console.log(`Time remaining: ${state.remainingSeconds}s`);

타이머 시퀀스

`AreActivitiesSupportedResult`

활동이 지원되는지 확인하는 결과입니다.

export interface AreActivitiesSupportedResult {
  /** Whether Live Activities are supported on this device */
  supported: boolean;
  /** Reason if not supported */
  reason?: string;
}

`StartActivityOptions`

Live Activity를 시작하는 옵션입니다.

export interface StartActivityOptions {
  /** Main activity layout (lock screen widget) */
  layout: ActivityLayout;
  /** Dynamic Island layout configuration */
  dynamicIslandLayout: DynamicIslandLayout;
  /** Activity behavior settings */
  behavior?: LiveActivitiesBehavior;
  /** Dynamic data for the activity */
  data: Record<string, unknown>;
  /** Stale date timestamp (activity becomes stale after this) */
  staleDate?: number;
  /** Relevance score for activity ordering (0-100) */
  relevanceScore?: number;
}

`StartActivityResult`

활동을 시작하는 결과입니다.

export interface StartActivityResult {
  /** Unique activity identifier */
  activityId: string;
}

`UpdateActivityOptions`

Live Activity를 업데이트하는 옵션입니다.

export interface UpdateActivityOptions {
  /** Activity ID to update */
  activityId: string;
  /** Updated data */
  data: Record<string, unknown>;
  /** Optional alert to show with update */
  alertConfiguration?: ActivityAlertConfiguration;
  /** Updated stale date */
  staleDate?: number;
  /** Updated relevance score */
  relevanceScore?: number;
}

`EndActivityOptions`

실시간 활동을 종료하는 옵션입니다.

export interface EndActivityOptions {
  /** Activity ID to end */
  activityId: string;
  /** Final data to display */
  data?: Record<string, unknown>;
  /** Dismissal policy */
  dismissalPolicy?: 'immediate' | 'default' | 'after';
  /** Dismiss after timestamp (when dismissalPolicy is 'after') */
  dismissAfter?: number;
}

`GetAllActivitiesResult`

모든 실시간 활동 결과입니다.

export interface GetAllActivitiesResult {
  /** List of activities */
  activities: ActivityInfo[];
}

`SaveImageOptions`

이미지를 저장하는 옵션입니다.

export interface SaveImageOptions {
  /** Base64 encoded image data */
  imageData: string;
  /** Name to save the image as */
  name: string;
  /** JPEG compression quality (0-1, default 0.8) */
  compressionQuality?: number;
}

`SaveImageResult`

이미지를 저장한 결과입니다.

export interface SaveImageResult {
  /** Whether the save was successful */
  success: boolean;
  /** Saved image name */
  imageName: string;
}

`RemoveImageOptions`

이미지 제거에 대한 옵션입니다.

export interface RemoveImageOptions {
  /** Name of the image to remove */
  name: string;
}

`RemoveImageResult`

이미지 제거의 결과입니다.

export interface RemoveImageResult {
  /** Whether the removal was successful */
  success: boolean;
}

`ListImagesResult`

이미지 목록의 결과입니다.

export interface ListImagesResult {
  /** List of saved image names */
  images: string[];
}

`TimerSequenceOptions`

타이머 시퀀스를 시작하는 옵션입니다.

export interface TimerSequenceOptions {
  /** Array of steps in the sequence */
  steps: TimerStep[];
  /** Overall title for the sequence (e.g., "HIIT Workout", "Tabata") */
  title?: string;
  /** Whether to loop the sequence when complete */
  loop?: boolean;
  /** Number of times to loop (if loop is true, 0 means infinite) */
  loopCount?: number;
  /** Play sound on step change (default: true) */
  soundEnabled?: boolean;
  /** Vibrate on step change (default: true) */
  vibrateEnabled?: boolean;
  /** Play countdown beeps in last 3 seconds (default: true) */
  countdownBeeps?: boolean;
  /** Deep link URL when tapping the notification/activity */
  tapUrl?: string;
  /** Keep screen on during timer (Android only, default: false) */
  keepScreenOn?: boolean;
}

실제 데이터의 원천

이 페이지는 플러그인의 src/definitions.ts Re-run the sync when the public API changes upstream.

Getting Started에서 계속

이 플러그인을 사용하여 Getting Started Getting Started를 사용하여 대시보드와 API를 계획하고 운영할 경우 Using @capgo/capacitor-live-activities Using @capgo/capacitor-live-activities API 개요 API 개요의 구현 세부 정보를 위해 소개 소개의 구현 세부 정보를 위해 API 키 API 키의 구현 세부 정보를 위해, 그리고 장치 장치의 구현 세부 정보를 위해

Getting Started

설치

iOS 설정

요구 사항

1. 위젯 확장 생성

2. Live Activities 활성화

3. 공유 이미지를 위한 앱 그룹 구성

5. 옵션: 서버 주도 업데이트 활성화

네이티브 설정 목록

Appflow 비교/이동 마케팅 복사본에서 사용되는 HTML 텍스트 조각입니다. 역할: 장기 마케팅 또는 법률 문구. 페이지/영역: page ionic-appflow.astro. Capgo 제품/브랜드 및 개발자 용어를 정확하게 유지합니다.

API Overview

areActivitiesSupported

startActivity

updateActivity

endActivity

getAllActivities

saveImage

removeImage

listImages

cleanupImages

startTimerSequence

pauseTimerSequence

resumeTimerSequence

stopTimerSequence

skipTimerStep

previousTimerStep

getTimerState