Erste Schritte

Installieren

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge die Capgo Skills mit dem folgenden Befehl deinem KI-Tool hinzu:

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

Nutze dann diesen Prompt:

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

Für ein manuelles Setup installiere das Package und synchronisiere die nativen Projekte:

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

Importieren

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

Aufrufe verarbeiten (cold-start-sicher)

Registriere einen Listener, bevor du die Warteschlange leerst, damit Aufrufe von Siri, Shortcuts, Spotlight und Quick Actions während des WebView-Starts nicht verloren gehen.

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

await useAppIntentsListener(handleInvocation);

useAppIntentsListener hängt an appIntentInvoked and then drains pending items. You can also call getPendingInvocations() und removePendingInvocation() manuell, wenn du eine explizite Kontrolle bevorzugst.

Siri-Phrasen (Codegen)

AppShortcut Phrasen und SF Symbol-Namen müssen in Compile-Time-Literale Swift vorliegen. Konfiguriere app-shortcuts.config.json in deinem App-Repo und generiere Swift für dein iOS- App hinzu Target:

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

Verknüpfe das Plugin SPM-Package mit dem App-Target, damit CapgoDispatchAppIntent gelöst. Mit Capacitor 8 kannst du SceneDelegate Quick Actions und fortgesetzte Spotlight-Aktivitäten weiterleiten mit CapgoAppIntentsLifecycle (siehe Plugin-Repo docs/ios-scene-integration.md).

capacitor.config

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

API Übersicht

getPendingInvocations

Gibt Aufrufe zurück, die eingereiht wurden, bevor JavaScript bereit war.

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

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

removePendingInvocation

Entferne eine ausstehende Invocation, nachdem dein Handler sie verarbeitet hat.

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

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

setEntityCatalog

Speichert einen Entity-Katalog dauerhaft für einen bestimmten Typ-String.

Ermöglicht Siri- und Shortcuts-Entity-Parameter ohne neuen Swift-Code pro Zeile.

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

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

setHomeScreenShortcutItems

Ersetzt Home Screen Quick Actions (UIApplicationShortcutItems).

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

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

indexSpotlightEntities

Indiziert Spotlight-Items für deine App-Domain.

Verwendet CSSearchableItem unter iOS 16 und neuer. Ab iOS 18 und neuer werden zusätzlich gespendet IndexedEntity Werte über indexAppEntities und associateAppEntity.

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

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

removeSpotlightEntities

Spotlight-Elemente anhand der ID entfernen.

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

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

performAppleSchemaTemplate

Einen JavaScript-Handler für ein Alpha-Apple-Schema-Template in die Warteschlange stellen.

Dies ruft keine privaten Mail- oder System-Schema-APIs auf. Es stellt lediglich einen Aufruf in die Warteschlange (zum Beispiel appleSchemaMailCreateDraft) für deine App code, damit sie ihn verarbeitet.

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

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

Typreferenz

AppIntentInvocation

Ein ausstehender Aufruf im App-Intent-Stil, der auf JavaScript wartet.

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

Eine Zeile in einem Runtime-Entity-Katalog, den Siri- und Shortcuts-Parameter nutzen.

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

Quick-Action-Eintrag für den 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

In Spotlight durchsuchbare Entity.

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

Alpha-Apple-Schema-Template-Identifikatoren, die vom Plugin bereitgestellt werden.

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

Ursprung eines Aufrufs.

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

Source of Truth

Diese Seite wird aus dem Plugin generiert src/definitions.ts. Führe den Sync erneut aus, wenn sich das öffentliche API upstream ändert.