시작하기

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

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-app-intents`
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/app-intents/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-app-intents` plugin in my project.

수동 설정을 하려면 패키지를 설치하고 native 프로젝트를 sync하세요:

npm install @capgo/capacitor-app-intents
npx cap sync

가져오기

import {
  CapgoAppIntents,
  drainPendingInvocations,
  useAppIntentsListener,
} from '@capgo/capacitor-app-intents';

호출 처리 (Cold start 안전)

WebView가 시작될 때 실행되는 Siri, Shortcuts, Spotlight 및 퀵 액션이 누락되지 않도록, 대기 중인 큐를 비우기 전에 리스너를 먼저 등록하세요.

const handleInvocation = async (invocation) => {
  console.log(invocation.name, invocation.params, invocation.source);
};

await useAppIntentsListener(handleInvocation);

useAppIntentsListener 연결합니다 appIntentInvoked 그런 다음 대기 중인 항목을 처리합니다. 다음을 호출할 수도 있습니다 getPendingInvocations() 및 removePendingInvocation() 명시적인 제어를 원한다면 수동으로 설정할 수도 있습니다.

Siri 구문 (codegen)

AppShortcut 문구와 SF Symbol 이름은 반드시 컴파일 타임 리터럴이어야 합니다. Swift에서 설정하세요. 앱 레포지토리에서 app-shortcuts.config.json 설정하여 iOS 타겟에 Swift 코드를 생성합니다: 앱 타겟:

node node_modules/@capgo/capacitor-app-intents/scripts/generate-app-shortcuts.mjs \
  --config app-shortcuts.config.json \
  --output ios/App/App/CapgoGeneratedAppShortcuts.swift

플러그인 SPM 패키지를 앱 타겟에 연결하여 CapgoDispatchAppIntent 해결됩니다. Capacitor 8에서는 SceneDelegate 퀵 액션과 이어지는 Spotlight 활동을 다음으로 전달하세요 CapgoAppIntentsLifecycle (플러그인 저장소 참고 docs/ios-scene-integration.md).

capacitor.config

plugins: {
  CapgoAppIntents: {
    appGroupId: 'group.your.app',
    spotlightDomainIdentifier: 'your.app.bundle',
  },
},

API 개요

`getPendingInvocations`

JavaScript가 준비되기 전에 대기열에 쌓인 호출을 반환합니다.

import { CapgoAppIntents } from '@capgo/capacitor-app-intents';

const result = await CapgoAppIntents.getPendingInvocations();
console.log(result);

`removePendingInvocation`

핸들러에서 처리를 완료한 후 대기 중인 호출 하나를 제거합니다.

import { CapgoAppIntents } from '@capgo/capacitor-app-intents';

await CapgoAppIntents.removePendingInvocation({ id: 'id-123' });

`setEntityCatalog`

지정된 타입 문자열에 대한 엔티티 카탈로그를 영구 저장합니다.

행마다 새로운 Swift 코드 없이 Siri 및 Shortcuts의 entity 파라미터를 구동합니다.

import { CapgoAppIntents } from '@capgo/capacitor-app-intents';

await CapgoAppIntents.setEntityCatalog({
  type: 'type',
  entries: [
    {
      id: 'id-123',
      title: 'Hello from Capacitor',
    },
  ],
});

`setHomeScreenShortcutItems`

홈 화면 퀵 액션(UIApplicationShortcutItems)을 교체합니다.

import { CapgoAppIntents } from '@capgo/capacitor-app-intents';

await CapgoAppIntents.setHomeScreenShortcutItems({
  items: [
    {
      type: 'type',
      title: 'Hello from Capacitor',
    },
  ],
});

`indexSpotlightEntities`

앱 도메인의 Spotlight 항목을 인덱싱합니다.

사용 기술 CSSearchableItem iOS 16 이상에서 지원됩니다. iOS 18 이상에서는 donate도 수행합니다. IndexedEntity 값을 통해 indexAppEntities 및 associateAppEntity.

import { CapgoAppIntents } from '@capgo/capacitor-app-intents';

await CapgoAppIntents.indexSpotlightEntities({
  entities: [
    {
      id: 'id-123',
      title: 'Hello from Capacitor',
      actionName: 'action',
    },
  ],
});

`removeSpotlightEntities`

Spotlight 항목을 ID로 삭제합니다.

import { CapgoAppIntents } from '@capgo/capacitor-app-intents';

await CapgoAppIntents.removeSpotlightEntities({ ids: ['ids'] });

`performAppleSchemaTemplate`

알파 Apple 스키마 템플릿용 JavaScript 핸들러를 큐에 추가합니다.

이는 비공개 Mail 또는 시스템 스키마 API를 호출하지 않습니다. 대신 호출을 대기열에 추가할 뿐입니다 (예: appleSchemaMailCreateDraft) 앱 code에서 처리할 수 있도록.

import { CapgoAppIntents } from '@capgo/capacitor-app-intents';

const result = await CapgoAppIntents.performAppleSchemaTemplate({
  template: 'mail_create_draft',
  params: {},
});
console.log(result);

타입 레퍼런스

`AppIntentInvocation`

JavaScript 호출을 기다리는 대기 중인 App Intent 스타일 호출입니다.

export interface AppIntentInvocation {
  /**
   * Stable id for this queued invocation.
   *
   * @since 0.1.0
   */
  id: string;

  /**
   * Handler name your JavaScript listens for.
   *
   * @since 0.1.0
   */
  name: string;

  /**
   * Parameters passed from Siri, Shortcuts, Spotlight, or quick actions.
   *
   * @since 0.1.0
   */
  params: Record<string, unknown>;

  /**
   * Origin of the invocation.
   *
   * @since 0.1.0
   */
  source: AppIntentInvocationSource;

  /**
   * Unix timestamp in milliseconds when the invocation was queued.
   *
   * @since 0.1.0
   */
  createdAt: number;
}

`EntityCatalogEntry`

Siri 및 Shortcuts 파라미터에서 사용하는 런타임 엔티티 카탈로그의 한 행입니다.

export interface EntityCatalogEntry {
  /**
   * Unique id within the catalog type.
   *
   * @since 0.1.0
   */
  id: string;

  /**
   * Primary label shown in Shortcuts and Siri.
   *
   * @since 0.1.0
   */
  title: string;

  /**
   * Optional subtitle.
   *
   * @since 0.1.0
   */
  subtitle?: string;

  /**
   * Optional extra metadata forwarded to JavaScript when the entity is chosen.
   *
   * @since 0.1.0
   */
  metadata?: Record<string, unknown>;
}

`HomeScreenShortcutItem`

홈 화면 퀵 액션 아이템입니다.

export interface HomeScreenShortcutItem {
  /**
   * Stable type string delivered to JavaScript.
   *
   * @since 0.1.0
   */
  type: string;

  /**
   * Visible title under the icon.
   *
   * @since 0.1.0
   */
  title: string;

  /**
   * Optional subtitle.
   *
   * @since 0.1.0
   */
  subtitle?: string;

  /**
   * Optional SF Symbol name.
   *
   * @since 0.1.0
   */
  iconName?: string;

  /**
   * Optional params merged into the invocation.
   *
   * @since 0.1.0
   */
  params?: Record<string, unknown>;
}

`SpotlightEntity`

Spotlight 검색 가능 엔티티입니다.

export interface SpotlightEntity {
  /**
   * Unique id within your app domain.
   *
   * @since 0.1.0
   */
  id: string;

  /**
   * Title shown in Spotlight.
   *
   * @since 0.1.0
   */
  title: string;

  /**
   * Optional description.
   *
   * @since 0.1.0
   */
  description?: string;

  /**
   * Optional keywords.
   *
   * @since 0.1.0
   */
  keywords?: string[];

  /**
   * Action name delivered when the result is opened.
   *
   * @since 0.1.0
   */
  actionName: string;

  /**
   * Optional params merged into the invocation.
   *
   * @since 0.1.0
   */
  params?: Record<string, unknown>;
}

`AppleSchemaTemplate`

플러그인에서 제공하는 알파 단계의 Apple schema template 식별자입니다.

export type AppleSchemaTemplate = 'mail_create_draft';

`AppIntentInvokedEvent`

export interface AppIntentInvokedEvent {
  /**
   * The invocation that was just queued or replayed to listeners.
   *
   * @since 0.1.0
   */
  invocation: AppIntentInvocation;
}

`AppIntentInvocationSource`

호출이 시작된 위치입니다.

export type AppIntentInvocationSource = 'app_intent' | 'spotlight' | 'quick_action' | 'apple_schema';

Source of Truth

이 페이지는 플러그인의 src/definitions.tsupstream에서 public API가 변경되면 sync를 다시 실행하세요.