Getting Started

설치

Capgo의 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.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

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

iOS 설정

플러그인을 설치하고 동기화하는 것은 네이티브 라이브 액티비티 UI를 생성하지 않습니다. ActivityKit은 라이브 액티비티 구성이 등록된 위젯 확장 프로그램이 필요합니다. startActivity 표시할 수 없습니다.

필수 조건

• iOS 16.1 이상을 앱 대상과 위젯 확장 프로그램 대상 모두에 사용하세요. iOS 기기나 호환 가능한 시뮬레이터에서 테스트하세요. 동적 섬의 표시가 지원되는 기기 모델에서만 나타나며, 다른 기기는 잠금 화면 표시를 사용합니다.
• Apple의 4 KB 제한 이하의 조합된 정적 및 동적 ActivityKit 데이터를 유지하세요.
• iOS 16.1 or later for both the app target and Widget Extension target.

1. 위젯 확장 기능 만들기

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

bunx cap open ios

그 다음:

1. 선택 파일 > 새 목표 >.
2. 위젯 확장 기능 추가 위젯 확장 기능 활성화.
3. 라이브 활동 포함 __CAPGO_KEEP_0__.
4. Disable 설정 포함 의도 앱이도 구성 가능한 위젯이 필요할 때는 제외합니다.
5. 생성된 확장 프로그램이 메인 앱 대상에 포함되어 있어야 합니다.

위젯 확장 프로그램은 ActivityConfiguration 에서 등록해야 합니다. 그것은 모든 필요한 라이브 활동 표시를 제공해야합니다. WidgetBundleLock Screen

• Dynamic Island 확장
• Dynamic Island 축소
• Dynamic Island 최소
• 타겟만 추가하는 것은 충분하지 않습니다. 네이티브 앱 또는 플러그인은 ActivityKit의 request, update, update, end API를 호출해야합니다. 확장 프로그램은 SwiftUI __CAPGO_KEEP_0__를 포함해야합니다. 그것은 동일한 것을 디코딩하고 렌더링할 수 있어야합니다.

code ActivityAttributes Live Activity를 사용하는 앱의 상태를 사용하는 데 사용되는 콘텐츠를 포함하십시오. ActivityKit 모델을 공유하여 Widget Extension 및 메인 앱의 대상에 모두 포함하십시오. Xcode가 생성한 Live Activity 템플릿은 이 플러그인으로 전달된 JSON 레이아웃을 자동으로 렌더링하지 않으며, 확장도 호환 가능한 네이티브 레이아웃 렌더러가 필요합니다.

2. Live Activity 활성화

메인 앱 대상의 키를 추가하십시오. Info.plist:

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

프로젝트가 Info.plist생성하면 Live Activity를 지원하는 Boolean 값이 YES 메인 앱 대상의 사용자 지정 iOS 대상 속성

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

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

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/12345에 추가하여 메인 앱 타겟의 설정 > URL 타입 설정에서 스키마를 추가합니다.

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

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

• 푸시 알림 추가 푸시 알림 __CAPGO_KEEP_0__ 기능을 메인 앱에 제공합니다.
• __CAPGO_KEEP_0__을 통해 ActivityKit 푸시 토큰을 얻고 서버로 전송합니다.
• ActivityKit 알림을 APNs를 통해 푸시 타입으로 전송합니다. liveactivity __CAPGO_KEEP_0__
• 메인 앱에 __CAPGO_KEEP_1__ 추가할 때, 사용 사례가 빈번한 푸시 업데이트 요구를 가질 때만. NSSupportsLiveActivitiesFrequentUpdates ActivityKit 푸시 토큰은 표준 사용자 알림 장치 토큰과 별도로 관리됩니다. 푸시 알림 기능만 활성화하는 것은 충분하지 않습니다. 서버 주도 업데이트에는 네이티브 토큰 처리 및 APNs 백엔드가 필요합니다. Info.plist 네이티브 셋업 체크리스트

네이티브 셋업 체크리스트

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

__CAPGO_KEEP_5__이 __CAPGO_KEEP_6__에 등록되어 있는지 확인하세요. startActivity__CAPGO_KEEP_7__이 __CAPGO_KEEP_8__에 등록되어 있는지 확인하세요.

• NSSupportsLiveActivities __CAPGO_KEEP_0__이 iOS 앱 대상에서 활성화되어 있습니다.
• 위젯 확장기는 포함되어 있으며 ActivityConfiguration.
• 위젯 확장기와 ActivityKit 구현은 동일한 ActivityAttributes 타입입니다.
• 앱과 위젯 확장기 배포 대상은 iOS 16.1 이상입니다.
• iOS 설정에서 앱에 라이브 활동이 활성화되어 있습니다.
• 위젯 확장기에서 공유 이미지를 사용할 때 두 대상 모두에 App Group이 활성화되어 있습니다.
• __CAPGO_KEEP_0__ 또는 __CAPGO_KEEP_1__에 의해 사용되는 widgetUrl __CAPGO_KEEP_0__ 또는 __CAPGO_KEEP_1__이 등록되어 있습니다. tapUrl Import

__CAPGO_KEEP_0__을 가져오기 위해 ‘Import’ 섹션을 클릭합니다.

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

API 개요

areActivitiesSupported

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

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

__CAPGO_KEEP_0__

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_1__

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_4__

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_7__

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_10__

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

타이머 시퀀스를 일시 중단합니다.

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_2__

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

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

skipTimerStep

__CAPGO_KEEP_3__

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

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

previousTimerStep

__CAPGO_KEEP_4__

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

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

getTimerState

__CAPGO_KEEP_1__

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

__CAPGO_KEEP_3__

AreActivitiesSupportedResult

__CAPGO_KEEP_6__

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

StartActivityOptions

__CAPGO_KEEP_9__

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

__CAPGO_KEEP_0__

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

UpdateActivityOptions

__CAPGO_KEEP_3__

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

__CAPGO_KEEP_5__

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

__CAPGO_KEEP_7__

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.tsAPI의 업스트림 변경 시 다시 싱크를 실행하세요.

Getting Started에서 계속하기

업스트림에서 __CAPGO_KEEP_0__이 변경되면 다시 싱크를 실행하세요. Getting Started API을 위한 대시보드와 API 운영을 계획하고 연결하세요. Using @capgo/capacitor-live-activities Using @capgo/capacitor-live-activities를 위한 네이티브 기능 API Overview API Overview의 구현 세부 사항 Introduction Introduction의 구현 세부 사항 API Keys API Keys의 구현 세부 사항 Devices Devices의 구현 세부 사항