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 구성이 등록된 위젯 확장자가 있어야만 startActivity 아무것도 표시할 수 있습니다.

요구 사항

iOS 16.1 이상을 앱 대상과 위젯 확장 대상 모두에 사용하세요.
iOS 기기나 호환되는 시뮬레이터에서 테스트하세요. 동적 섬유원은 지원되는 기기 모델에서만 나타나며, 다른 기기는 Lock Screen 표시를 사용합니다.
Apple의 4 KB 제한 이하의 ActivityKit 데이터를 동적 및 정적으로 combination하세요.

native iOS 프로젝트 열기:

bunx cap open ios

그 다음:

선택 파일 > 새 목표 >.
위젯 확장션 추가 Add a.
이용 실시간 활동 포함.
비활성화 구성 intent 포함 앱이도 구성 가능한 위젯이 필요할 경우 제외합니다.
생성된 확장 프로그램이 메인 앱 대상에 포함되어야 합니다.

위젯 확장 프로그램은 ActivityConfiguration 에 등록해야합니다. WidgetBundle실시간 활동 표시를 제공해야합니다.

스크린 잠금
확장된 동적 섬
축소된 동적 섬(앞/뒤)
DINAMIK 섬유로 최소한의

타겟을 추가하는 것만으로는 충분하지 않습니다. Native 앱 또는 플러그인은 ActivityKit의 request, update, 및 end API를 호출해야 합니다. 확장 프로그램은 SwiftUI code를 포함해야 하며 JSON 레이아웃을 디코딩하고 렌더링할 수 있어야 합니다. ActivityAttributes 그것들에 의해 사용되는 콘텐츠 상태도 포함해야 합니다. main 앱과 Widget Extension 타겟 모두에 공유된 ActivityKit 모델을 포함해야 합니다. Xcode가 생성한 Live Activity 템플릿은 자동으로 이 플러그인에 전달된 JSON 레이아웃을 렌더링하지 않습니다. 확장 프로그램도 호환되는 네이티브 레이아웃 렌더러가 필요합니다.

2. Live 활동 활성화

main 앱 타겟의 Info.plist:

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

프로젝트가 Info.plist생성하면 추가 Live 활동 지원 YES Boolean 값으로 'true'로 설정해야 합니다.

3. 앱 그룹을 공유 이미지를 위한 설정

앱 그룹은 saveImage, removeImage, listImages, 또는 cleanupImages를 사용할 때만 필요합니다.

group.<MAIN_APP_BUNDLE_ID>.liveactivities

클립보드 복사 com.example.delivery 예를 들어, 번들 식별자가

group.com.example.delivery.liveactivities

클립보드 복사 Xcode에서 메인 앱 타겟과 위젯 확장 타겟에 모두 앱 그룹

네트워크 접근이 불가능한 Live Activity 확장에서 원격 이미지를 다운로드할 수 없습니다. 메인 앱에서 원격 이미지를 다운로드하고 공유 App Group에 저장한 후 Live Activity에서 참조하세요. 배포된 이미지는 Widget Extension을 활성화하여 asset의 대상 구성원에 추가하세요.

4. 링크 설정

사용할 때 behavior.widgetUrl 또는 타이머 시퀀스 tapUrl등록된 URL 스키마 또는 Universal Link를 메인 앱에서 등록하세요. 커스텀 스키마인 경우 myapp://order/12345메인 앱 대상의 정보 > URL 유형 설정에서 스키마를 추가하세요.

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

푸시 알림은 앱에서 시작, 업데이트 또는 종료하는 Live Activity를 위해 필요하지 않습니다. 서버에서 Live Activity를 시작, 업데이트 또는 종료하려면:

__CAPGO_KEEP_0__ capability을 Push Notifications 기본 앱 대상에 기능을 추가하세요.
ActivityKit 푸시 토큰을 얻고 서버로 전송하세요.
APNs을 사용하여 ActivityKit 알림을 전송하세요. liveactivity push type.
__CAPGO_KEEP_0__을 기본 앱에 추가하세요. NSSupportsLiveActivitiesFrequentUpdates 기본 앱에 __CAPGO_KEEP_0__을 추가하세요. 사용 사례가 빈번한 푸시 업데이트 요구 시에만. Info.plist ActivityKit 푸시 토큰은 표준 사용자 알림 장치 토큰과 별도로 관리됩니다. Push Notifications 기능만 활성화하는 것은 충분하지 않습니다. 서버 주도 업데이트에는 네이티브 토큰 처리 및 APNs 백엔드가 필요합니다.

네이티브 셋업 체크리스트

네이티브 셋업 체크리스트 섹션 제목입니다.

애플리케이션을 호출하기 전에 확인하세요: startActivity이용할 수 있도록 설정되어야 합니다.

NSSupportsLiveActivities Widget Extension이 내장되어 Widget Extension이
를 등록합니다. ActivityConfiguration.
Widget Extension과 native ActivityKit 구현은 동일한 ActivityAttributes 타입을 사용합니다.
앱과 Widget Extension 배포 대상이 iOS 16.1 이상일 때
iOS 설정에서 앱에 Live Activities가 활성화되어야 합니다.
공유 이미지를 사용할 때는 두 대상 모두에 App Group이 활성화되어야 합니다.
또는 widgetUrl 에 사용하는 사용자 정의 URL 스키마가 등록되어야 합니다. tapUrl __CAPGO_KEEP_0__

Import

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

API 개요

`areActivitiesSupported`

iOS 16.1 이상 및 장치 지원이 필요한 이 기기의 Live Activities 지원 여부를 확인합니다.

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 Activity를 시작합니다.

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`

__CAPGO_KEEP_0__를 업데이트합니다.

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`

__CAPGO_KEEP_0__를 종료합니다.

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`

__CAPGO_KEEP_0__를 모두 가져옵니다.

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

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

`saveImage`

__CAPGO_KEEP_0__를 공유 App 그룹 컨테이너에 저장합니다.

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`

__CAPGO_KEEP_0__을 공유 컨테이너에서 삭제합니다.

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에서: 라이브 활동 및 다이나믹 아일랜드에 표시 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`

__CAPGO_KEEP_0__

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

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

`resumeTimerSequence`

__CAPGO_KEEP_0__

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

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

`stopTimerSequence`

__CAPGO_KEEP_4__

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

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

`skipTimerStep`

__CAPGO_KEEP_6__

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`

실시간 활동을 시작하는 옵션

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`

실시간 활동을 업데이트하는 옵션입니다.

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`

getAllActivities의 결과입니다.

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

`SaveImageOptions`

__CAPGO_KEEP_2__

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`

__CAPGO_KEEP_4__

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

`RemoveImageOptions`

__CAPGO_KEEP_6__

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

`RemoveImageResult`

__CAPGO_KEEP_8__

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공개 API이 업스트림에서 변경될 때 다시 싱크를 실행하세요.

Getting Started에서 계속 진행하세요.

__CAPGO_KEEP_0__을 사용 중이라면 Getting Started API 대시보드와 API 연산을 계획하는 데 사용하는 경우 API을 capgo/capacitor-live-activities를 사용하여 capgo/capacitor-live-activities를 사용하는 데 native 기능을 사용하는 경우 @capgo/capacitor-live-activities API 개요 API 개요에서 구현 세부 정보 소개 소개에서 구현 세부 정보 API 키 API 키에서 구현 세부 정보 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__

Getting Started

설치

iOS 설정

요구 사항

1. 위젯 확장션 만들기

2. Live 활동 활성화

3. 앱 그룹을 공유 이미지를 위한 설정

4. 링크 설정

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

네이티브 셋업 체크리스트 섹션 제목입니다.

Import

API 개요

areActivitiesSupported

startActivity

updateActivity

endActivity

getAllActivities

saveImage

removeImage

listImages

cleanupImages

startTimerSequence

pauseTimerSequence

resumeTimerSequence

stopTimerSequence

skipTimerStep

previousTimerStep

getTimerState