시작하기

이 플러그인의 설치 단계와 전체 마크다운 가이드를 포함한 설정 프롬프트를 복사하세요.

        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.

설치

Capgo의 AI 보조 설치를 사용하여 플러그인을 설치할 수 있습니다. AI 도구에 Capgo 기능을 추가하려면 다음 명령어를 사용하세요:

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

페이지/영역: Capgo 마케팅 웹사이트. 역할: UI 레이블. 표시되는 곳: page agents/[slug].astro. 메시지 키 `agents_page_copy_label` (Agents Page Copy Label).

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

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

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

iOS 설정

설치 및 동기화는 Live 활동 UI를 생성하지 않습니다. ActivityKit은 Live 활동 구성이 등록된 위젯 확장 프로그램이 필요합니다. startActivity Live 활동을 표시할 수 있습니다.

요구 사항

iOS 16.1 이상을 앱 대상과 위젯 확장 프로그램 대상 모두에 사용하세요.
iOS 기기 또는 호환 시뮬레이터에서 테스트하세요. 동적 섬유는 지원되는 기기 모델에서만 나타납니다. 다른 기기는 잠금 화면 표시를 사용합니다.
Apple의 4 KB 제한 이하로 유지하세요.

native iOS 프로젝트를 열어주세요.

bunx cap open ios

그런 다음:

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

위젯 확장은 반드시 ActivityConfiguration 그것을 등록하세요. WidgetBundleLive 활동의 모든 필수 표현을 제공해야 합니다.

스크린 잠금
확장된 Dynamic Island
축소된 Dynamic Island
축소된 Dynamic Island

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를 호출해야 합니다. 확장에는 JSON 레이아웃을 디코딩하고 렌더링할 수 있는 SwiftUI __CAPGO_KEEP_0__가 포함되어야 합니다. main 앱과 Widget Extension 대상 모두에 공유된 ActivityKit 모델을 포함해야 합니다. Xcode가 생성한 Live Activity 템플릿은 자동으로 이 플러그인에 전달된 JSON 레이아웃을 렌더링하지 않으며 확장도 호환 가능한 네이티브 레이아웃 렌더러가 필요합니다.

2. Live 활동 활성화

main 앱 대상의 키를 추가하세요. Info.plist:

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

만들어진 프로젝트가 Info.plist, 라이브 활동을 지원합니다. 라이브 활동을 지원하는 YES 의

속성을

3. 공유 이미지를 위한 앱 그룹을 구성합니다. saveImage, removeImage, listImages, or cleanupImages앱 그룹은

group.<MAIN_APP_BUNDLE_ID>.liveactivities

을 사용할 때만 필요합니다. 플러그인은 앱 그룹 식별자를 다음 형식으로 메인 앱 번들 식별자에서 추출합니다: com.example.delivery 사용해야 합니다:

group.com.example.delivery.liveactivities

Xcode에서 다음을 추가하세요: 애플리케이션 그룹 라이브 활동 확장자는 네트워크에 접근할 수 없습니다. 메인 앱에서远程 이미지를 다운로드하고 공유 App Group에 저장한 후 라이브 활동에서 참조하세요. 배포된 이미지는 Widget Extension을 활성화하여 자산의 대상 멤버십도 활성화하세요.

4. 디ープ 링크 구성

사용할 때 또는 타이머 시퀀스

를 사용할 때, 메인 앱 대상의 behavior.widgetUrl 속성에서 스키마를 추가하세요. tapUrl애플리케이션의 메인 앱에서 매칭 URL 스키마 또는 Universal Link를 등록하세요. 커스텀 스키마와 같은 myapp://order/12345라이브 액티비티를 사용하기 위한 첫 단계는 앱의 메인 타겟 아래에 스키마를 추가하는 것입니다. Info > URL 종류 설정.

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

서버에서 Live 활동을 시작, 업데이트, 또는 종료하려면 푸시 알림이 필요하지 않습니다.

Live Activities 활동킷 푸시 토큰을 얻어 서버에 전송하세요. 활동킷 알림을 APNs를 통해 푸시 타입을 사용하여 전송하세요.
추가
푸시 알림 liveactivity 푸시 타입.
Add NSSupportsLiveActivitiesFrequentUpdates 메인 앱으로 Info.plist 사용 사례가 빈번한 푸시 업데이트 요구를 만족할 때만

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

네이티브 설정 목록

호출하기 전에 startActivity확인하세요:

NSSupportsLiveActivities 메인 앱 대상에서
Widget 확장기는 ActivityConfiguration.
네이티브 ActivityKit implementation과 Widget Extension은 동일한 ActivityAttributes type.
Widget 확장기는
iOS 설정에서 앱에 대해 Live Activities가 활성화되어 있습니다.
모든 대상에서 공유 이미지를 사용할 때 App Group이 일치하는 상태로 활성화되어 있습니다.
또는 widgetUrl or tapUrl __CAPGO_KEEP_0__ Overview

Import

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

API 개요

`areActivitiesSupported`

__CAPGO_KEEP_0__ Overview

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`

새로운 데이터로 기존 Live Activity를 업데이트합니다.

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 Activity를 종료합니다.

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`

현재 활성화된 모든 Live Activity를 가져옵니다.

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`

Activities가 지원되는지 확인하는 결과입니다.

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`

Live Activity를 종료하는 옵션입니다.

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`

모든 Live Activity 결과입니다.

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

Getting Started에서 계속

이 플러그인을 사용하는 경우 시작하기 계획 대시보드 및 API 운영을 위해 @capgo/capacitor-실시간 활동 Using @capgo/capacitor-live-activities Using @API/__CAPGO_KEEP_1__-live-activities 플러그인을 사용하는 경우 Capgo API 개요에 대한 구현 세부 정보를 참조하십시오. 소개 Capgo __CAPGO_KEEP_0__ 키에 대한 구현 세부 정보를 참조하십시오. API 키 for API 구현 세부 사항에 대한 Devices Capgo __CAPGO_KEEP_0__

시작하기

설치

iOS 설정

요구 사항

1. 위젯 확장 프로그램 만들기

2. Live 활동 활성화

속성을

사용할 때 또는 타이머 시퀀스

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

네이티브 설정 목록

Import

API 개요

areActivitiesSupported

startActivity

updateActivity

endActivity

getAllActivities

saveImage

removeImage

listImages

cleanupImages

startTimerSequence

pauseTimerSequence

resumeTimerSequence

stopTimerSequence

skipTimerStep

previousTimerStep

getTimerState