Siri, Shortcuts, 위젯, 시스템 인텐트

Expo가 최근 출시한 expo-app-intents는 Apple의 App Intents를 framework를 JavaScript와 연결합니다: Siri 및 Shortcuts 구문, 런타임 엔티티 카탈로그, Apple Intelligence용 Apple 앱 스키마, Spotlight 인덱싱, 그리고 JavaScript가 시작되기 전에 도착하는 호출을 위한 네이티브 큐.

@capgo/capacitor-app-intents 는 Apple용 Capacitor 브리지입니다 App Intents를: Siri 및 Shortcuts 구문(컴파일 타임 codegen), 런타임 엔티티 카탈로그, Spotlight 인덱싱, 홈 화면 퀵 액션, 그리고 콜드 스타트를 위한 대기 호출 큐를 제공합니다. Widget Kit, Live Activities, Share Target, Intent Launcher는 여전히 인접한 영역을 커버합니다. 이 페이지에서는 이들이 어떻게 맞물리는지, Android와 혼용하지 않고 시스템 통합을 배포할 수 있도록 설명합니다. Intent Apple App Intents를 활용한 API.

한눈에 보기

시스템 영역	Capgo 플러그인을 설치하세요.	플러그인이 실제로 하는 일
홈 화면 위젯, 잠금 화면 Live Activities, Dynamic Island (SVG 또는 네이티브 위젯 code)	@capgo/capacitor-widget-kit	템플릿 액티비티 유지, 선언적 액션 실행, 위젯 또는 Live Activity 탭 로그 기록, App Groups를 통한 완전 네이티브 위젯 세션 동기화.
JSON 레이아웃 트리를 활용한 Live Activities	@capgo/capacitor-live-activities	Capacitor에서 ActivityKit 액티비티 시작, 업데이트, 종료; 타이머 시퀀스; App Group 내 이미지 공유.
다른 앱에서 공유 받기	@capgo/capacitor-share-target	shareReceived Android intent 또는 iOS Share Extension과 App Group을 통해 제목, 텍스트, 파일에 대한 이벤트를 받습니다.
Android 설정 또는 액티비티 열기; iOS 설정 URL 열기	@capgo/capacitor-intent-launcher	startActivityAsync, openIOSSettings, openApplication. 이는 하지 마세요 Apple App Intents입니다.
Siri 문구, Shortcuts, Spotlight, 빠른 동작, App Intent 대기열	@capgo/capacitor-app-intents	브릿지 디스패치, setEntityCatalog, indexSpotlightEntities, setHomeScreenShortcutItems, getPendingInvocations, useAppIntentsListener. iOS 16 이상.
온디바이스 LLM (지원되는 iPhone의 Apple Intelligence)	@capgo/capacitor-llm	채팅 및 모델 API. App Intent나 스키마 브릿지 불필요.

expo-app-intents와의 비교

기능 유사성을 평가할 때 이 표를 참고하세요. “partial”로 표시된 부분적(partial) 행은 기능의 일부만 겹친다는 의미입니다.

expo-app-intents 기능	Capgo 현재
음성 명령을 통한 Siri 및 단축어 앱의 커스텀 액션	지원 포함 @capgo/capacitor-app-intents. 구문은 컴파일 타임 리터럴로 생성된 Swift 내에 (AppShortcutsProvider) 존재하며, 런타임 JavaScript 문자열이 아닙니다.
JS 엔티티 카탈로그를 기반으로 하는 Shortcut 파라미터는 (AppEntity, EntityQuery)	지원 포함 @capgo/capacitor-app-intents 를 통해 setEntityCatalog() 및 네이티브 EntityQuery 연결합니다.
Apple 앱 스키마(예: Apple Intelligence를 위한 메일 초안 작성 인텐트)	부분 지원. App Intents를 통해 다음을 제공합니다. performAppleSchemaTemplate 하나의 JavaScript 큐만 사용 (네이티브 Mail API 없음). 앱 내에서 Compose UI 또는 딥 링크를 구현해야 합니다.
Spotlight 인덱싱 및 앱 내 검색 가능한 콘텐츠	지원 포함 @capgo/capacitor-app-intents 다음 방식을 통해 indexSpotlightEntities() (CSSearchableItem, 그리고 IndexedEntity iOS 18 이상에서 지원).
시스템 인텔리전스를 위해 화면 콘텐츠를 엔티티와 연결	부분 지원. 엔티티 카탈로그는 Shortcuts 파라미터의 기반이 되지만, 전체 화면 연결 API는 아직 노출되지 않았습니다.
JavaScript가 준비되기 전에 실행되는 액션을 위한 네이티브 큐	지원 를 통한 App Intents 지원 @capgo/capacitor-app-intents (getPendingInvocations, appIntentInvoked). Share Target 및 Widget Kit은 여전히 공유 및 템플릿 이벤트를 위해 자체 유지 모델을 사용합니다.
App Intents를 통한 대화형 Live Activity 또는 위젯 버튼	부분 지원. Widget Kit은 다음을 제공합니다: CapgoTemplateActionIntent 및 CompleteSetIntent 로 LiveActivityIntent 타입 정의: 템플릿 iOS 17+에서 hotspot 및 workout 액션을 지원합니다. 이 액션들은 네이티브 상태와 이벤트 로그를 업데이트하며, JavaScript에서 임의의 Siri 문구를 노출하지 않습니다.
앱 JavaScript에서 WidgetKit 및 ActivityKit을 호출	네. Widget Kit 및 Live Activities 플러그인(아래 참조).
Android Intent 액션(settings, VIEW, SEND 등)	지원 Intent Launcher 및 Share Target을 통해 실행하고 수신할 수 있습니다.

Widget Kit: 위젯, Live Activities, 템플릿 액션

@capgo/capacitor-widget-kit 다음과 가장 유사합니다: 시스템 표시 UI WebView 외부의 UI입니다. Capacitor에서 Lock Screen 및 Dynamic Island를 제어하고, SVG 템플릿이나 네이티브 Swift/Kotlin code로 Home Screen 위젯을 렌더링하며, 이후의 탭 이벤트를 처리할 수 있습니다.

템플릿 Live Activity를 시작하고 JavaScript로 액션 처리하기

앱 부팅 시 리스너를 등록한 다음, 앱이 다시 시작될 때 폴링하거나 호출해야 합니다. App 위젯 탭이 WebView 로딩 중에 실행될 수 있기 때문입니다:

import { App } from '@capacitor/app';
import { CapgoWidgetKit } from '@capgo/capacitor-widget-kit';

const ACTIVITY_ID = 'order-tracker';

async function drainTemplateEvents() {
  const { events } = await CapgoWidgetKit.listTemplateEvents({
    activityId: ACTIVITY_ID,
    unacknowledgedOnly: true,
  });

  for (const event of events) {
    if (event.actionId === 'mark-delivered') {
      // Update your app state from event.state or event.payload
    }
    await CapgoWidgetKit.acknowledgeTemplateEvents({
      eventIds: [event.eventId],
    });
  }
}

await CapgoWidgetKit.startTemplateActivity({
  activityId: ACTIVITY_ID,
  state: { status: 'On the way' },
  definition: {
    id: 'delivery-card',
    actions: [
      {
        id: 'mark-delivered',
        eventName: 'delivery.marked',
      },
    ],
    layouts: {
      lockScreen: {
        width: 200,
        height: 80,
        svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 80"><text x="8" y="40">{{state.status}}</text></svg>',
        hotspots: [
          {
            id: 'deliver',
            actionId: 'mark-delivered',
            x: 120,
            y: 20,
            width: 70,
            height: 40,
            label: 'Mark delivered',
          },
        ],
      },
    },
  },
});

App.addListener('resume', () => {
  void drainTemplateEvents();
});

void drainTemplateEvents();

iOS의 경우, 위젯 확장 프로그램의 대화형 컨트롤에서 번들된 CapgoTemplateActionIntent (LiveActivityIntent). 해당 경로는 저장된 템플릿 상태를 업데이트하며, JavaScript가 읽는 것과 동일한 이벤트 로그에 기록됩니다. 이는 하지 마세요 Shortcuts 앱에 사용자에게 보이는 단축어 문구를 추가하는 것과 같습니다.

자세한 내용은 Widget Kit 시작하기 App Group 설정 및 완전한 네이티브 위젯 세션을 위해.

Live Activities: Capacitor 기반 JSON 레이아웃

@capgo/capacitor-live-activities 에 집중합니다. ActivityKit 선언적 레이아웃 JSON(텍스트, 이미지, 타이머, 게이지, Dynamic Island 영역)을 사용합니다. App Intents나 Siri 단축어는 등록하지 않습니다.

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

const { supported } = await CapgoLiveActivities.areActivitiesSupported();
if (!supported) {
  return;
}

const { activityId } = await CapgoLiveActivities.startActivity({
  layout: {
    type: 'container',
    direction: 'vertical',
    children: [
      { type: 'text', content: 'Order {{orderId}}', fontWeight: 'bold' },
      { type: 'text', content: '{{status}}' },
    ],
  },
  data: { orderId: '42', status: 'Preparing' },
});

await CapgoLiveActivities.updateActivity({
  activityId,
  data: { orderId: '42', status: 'Out for delivery' },
});

선택 Live Activities 레이아웃 DSL과 이미지 헬퍼가 필요할 때 선택하세요. 위젯 키트 홈 화면 위젯, SVG 프레임 또는 템플릿 이벤트 로그와 LiveActivityIntent 버튼이 필요할 때

Share Target: 수신 공유 (Shortcuts 송신 제외)

@capgo/capacitor-share-target 다른 앱이 콘텐츠를 앱으로 보내도록 합니다. iOS에서는 App Group에 쓰는 Share Extension을 추가합니다. 메인 앱 플러그인이 해당 페이로드를 읽고 비운 뒤 다음을 emit합니다: shareReceived.

iOS에서는 콜드 스타트를 처리합니다. 네이티브 플러그인이 호출하는 대상: notifyListeners(..., retainUntilConsumed: true) 따라서 첫 번째 JavaScript 리스너가 여전히 이벤트를 수신합니다.

import { CapacitorShareTarget } from '@capgo/capacitor-share-target';

await CapacitorShareTarget.addListener('shareReceived', (event) => {
  const firstText = event.texts[0] ?? '';
  const firstFile = event.files[0];
  console.log(event.title, firstText, firstFile?.uri);
});

이는 Android의 SEND intent 필터를 보완합니다. 또한 하지 마세요 앱에서 공유 단축어나 Siri 액션을 게시할 수 있습니다.

Intent Launcher: Android intents, iOS Settings (App Intents 제외)

이 이름은 Apple의 기능과 혼동하기 쉽습니다. App Intents를. @capgo/capacitor-intent-launcher 실행할 때만 Android activity(포함 ActivityAction.CREATE_SHORTCUT 레거시 런처 단축어용) 및 열기 iOS 설정 URL scheme.

import { IntentLauncher, ActivityAction, IOSSettings } from '@capgo/capacitor-intent-launcher';

await IntentLauncher.startActivityAsync({
  action: ActivityAction.WIFI_SETTINGS,
});

await IntentLauncher.openIOSSettings({ option: IOSSettings.App });

Siri, 단축어 앱 및 AppIntent 유형에는 다음을 사용하세요. @capgo/capacitor-app-intents. Intent Launcher는 Android activity와 iOS Settings URL만 실행합니다.

추천 조합

목표	시작하기
SVG 및 탭 로깅을 활용한 잠금 화면과 Dynamic Island	위젯 키트
Rich layout JSON 및 타이머 시퀀스	Live Activities
사용자가 링크 또는 파일을 앱으로 공유할 때	공유 대상
WiFi 또는 앱 설정으로 딥링크 연결	인텐트 런처
엔티티 파라미터와 함께 JS 핸들러를 실행하는 Siri 구문	App Intents를 (구문을 위한 codegen, setEntityCatalog, useAppIntentsListener)

남은 미비점 (계획용)

영역	상태
Widget Kit 커스텀 AppShortcut 템플릿 이벤트 로그와 연결된 문구	Widget Kit 번들링 LiveActivityIntent 헬퍼 기능만 제공하며, 임의의 Siri 문구는 App Intents 코드 생성 단계에서 처리해야 합니다.
Share Target API 폴링	오늘 발생한 이벤트만 표시; 다음을 사용하세요 addListener('shareReceived') 부팅 초기 단계에서.
Apple Mail 네이티브 스키마 인텐트	서드파티 앱에서는 사용할 수 없습니다. 대신 App Intents가 JS 핸들러를 큐에 추가합니다.
Android App Intents 기능 지원	App Intents는 iOS 16 이상에서만 지원됩니다. Android에서는 명확한 에러가 반환됩니다.

계속하기

• App Intents 개요
• Widget Kit 개요
• Live Activities 개요
• Share Target 개요
• Intent Launcher 개요