SaveImageResult

설치

        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

다음 명령어를 사용하세요:

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 16.1 이상의 앱 대상과 위젯 확장 대상 모두를 사용해야 합니다.
iOS 기기나 호환되는 시뮬레이터에서 테스트하세요. 동적 섬유만 지원되는 기기 모델에서만 동적 섬유가 나타나고, 다른 기기는 Lock Screen 표시를 사용합니다.
ActivityKit 데이터의 정적 및 동적 데이터를 합친 크기가 Apple의 4 KB 제한을 넘지 않도록 하세요.

네이티브 iOS 프로젝트를 열어주세요:

bunx cap open ios

그런 다음:

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

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

Lock Screen
Dynamic Island expanded
Dynamic Island compact leading and trailing
Dynamic Island minimal

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

2. Live Activities 활성화

main 앱 타겟의 Info.plist:

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

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

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

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

group.<MAIN_APP_BUNDLE_ID>.liveactivities

예를 들어, 번들 식별자 com.example.delivery 해야 합니다:

group.com.example.delivery.liveactivities

Xcode에서, 메인 앱 대상과 위젯 확장 대상에 모두 App Groups 능력을 추가하고, 메인 앱과 위젯 확장 대상에 동일한 식별자를 활성화합니다.

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

4. 깊이 링크 구성

사용할 때 behavior.widgetUrl 또는 타이머 시퀀스 tapUrl, 메인 앱에서 일치하는 URL 스키마 또는 Universal Link를 등록하세요. 커스텀 스키마인 myapp://order/12345Live 액티비티를 시작하기 위해, 앱의 메인 타겟 아래에 scheme을 추가하세요. Info > URL 종류 설정.

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

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

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

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

네이티브 설정 체크리스트

호출하기 전에 startActivity활성화 여부를 확인하세요.

NSSupportsLiveActivities 메인 앱 대상에 활성화되어야 합니다.
위젯 확장은 ActivityConfiguration.
위젯 확장은 ActivityAttributes ActivityKit 네이티브 구현과 위젯 확장은 동일한
iOS 16.1 이상 또는 그 이상의 애플리케이션과 위젯 확장 배포 대상입니다.
iOS 설정에서 앱에 라이브 활동이 활성화되어 있습니다.
공유 이미지를 사용할 때는 iOS 16.1 이상 또는 그 이상의 애플리케이션과 위젯 확장 배포 대상에서 일치하는 앱 그룹이 활성화되어 있습니다.
사용하는 모든 커스텀 URL 스키마 widgetUrl 또는 tapUrl Capacitor 라이브 업데이트 대안

등록되어 있습니다.

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`

현재 활성화된 모든 Live 활동을 가져오십시오.

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

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

`saveImage`

Live 활동에서 사용할 수 있는 이미지를 공유 앱 그룹 컨테이너에 저장하십시오. 이미지는 위젯 확장에서 접근할 수 있도록 공유 컨테이너에 저장해야 합니다.

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`

실시간 활동 시작에 대한 옵션입니다.

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`

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

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