Panduan Memulai

Instal

Anda bisa menggunakan AI-Assisted Setup kami untuk menginstal plugin ini. Tambahkan skill Capgo ke tool AI Anda dengan command berikut:

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

Lalu gunakan prompt berikut:

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

Untuk setup manual, instal package dan sync project native:

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

Impor

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

Tangani invokasi (aman dari cold start)

Daftarkan listener sebelum mengosongkan antrean yang tertunda agar Siri, Shortcuts, Spotlight, dan quick actions yang berjalan saat WebView startup tidak hilang.

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

await useAppIntentsListener(handleInvocation);

useAppIntentsListener menghubungkan appIntentInvoked lalu mengosongkan item yang tertunda. Anda juga bisa memanggil getPendingInvocations() dan removePendingInvocation() secara manual jika Anda lebih suka kontrol eksplisit.

Frasa Siri (codegen)

AppShortcut frasa dan nama SF Symbol harus literal waktu kompilasi dalam Swift. Konfigurasikan app-shortcuts.config.json di repo aplikasi Anda dan generate Swift ke dalam iOS App target:

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

Hubungkan SPM package plugin ke target aplikasi agar CapgoDispatchAppIntent selesai. Pada Capacitor 8, teruskan quick action SceneDelegate dan aktivitas Spotlight yang berlanjut dengan CapgoAppIntentsLifecycle (lihat repo plugin docs/ios-scene-integration.md).

capacitor.config

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

Ringkasan API

getPendingInvocations

Mengembalikan pemanggilan yang diantrekan sebelum JavaScript siap.

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

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

removePendingInvocation

Hapus satu pemanggilan yang tertunda setelah handler memprosesnya.

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

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

setEntityCatalog

Simpan katalog entitas untuk string tipe tertentu.

Mengaktifkan parameter entitas Siri dan Shortcuts tanpa perlu menulis Swift baru di setiap baris.

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

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

setHomeScreenShortcutItems

Ganti quick actions Home Screen (UIApplicationShortcutItems).

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

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

indexSpotlightEntities

Buat indeks item Spotlight untuk domain aplikasi Anda.

Menggunakan CSSearchableItem pada iOS 16 ke atas. Pada iOS 18 ke atas juga melakukan donasi IndexedEntity nilai melalui indexAppEntities dan associateAppEntity.

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

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

removeSpotlightEntities

Hapus item Spotlight berdasarkan ID.

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

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

performAppleSchemaTemplate

Antrekan handler JavaScript untuk template skema Apple alpha.

Ini tidak memanggil API Mail privat atau skema sistem. Ini hanya memasukkan antrean pemanggilan (misalnya appleSchemaMailCreateDraft) agar aplikasi code Anda yang menanganinya.

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

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

Referensi Tipe

AppIntentInvocation

Invocation bergaya App Intent yang tertunda menunggu JavaScript.

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

Satu baris dalam katalog entity runtime yang digunakan oleh parameter Siri dan 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

Item quick action di Home Screen.

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

Entity yang dapat dicari di 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

Identifier template schema Apple versi Alpha yang disertakan oleh plugin.

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

Asal mula pemanggilan (invocation).

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

Sumber Kebenaran

Halaman ini dibuat dari plugin src/definitions.ts. Jalankan ulang sync saat API publik berubah di upstream.