Erste Schritte

Installation

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:

bunx 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-incoming-call-kit` plugin in my project.

Wenn du ein manuelles Setup bevorzugst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:

1. Paket installieren

   bun add @capgo/capacitor-incoming-call-kit

2. Native Projekte synchronisieren

   bunx cap sync

3. Wähle deine Klingelquelle Entscheide, ob das incoming-call Event von deinem Backend, einem SDK wie Twilio oder Stream oder einem nativen Push-Pfad wie FCM oder PushKit kommt.

Quickstart

import { IncomingCallKit } from '@capgo/capacitor-incoming-call-kit';

const result = await IncomingCallKit.showIncomingCall({
  callId: 'call-id-123',
  callerName: 'caller',
});
console.log(result);

Beispiel: endCall

import { IncomingCallKit } from '@capgo/capacitor-incoming-call-kit';

const result = await IncomingCallKit.endCall({ callId: 'call-id-123' });
console.log(result);

Beispiel: endAllCalls

import { IncomingCallKit } from '@capgo/capacitor-incoming-call-kit';

const result = await IncomingCallKit.endAllCalls();
console.log(result);

Häufige Stolperfallen

• Berechtigungen: aufrufen checkPermissions() dann requestPermissions() bei Bedarf.
• Listener: Handles beim Unmounten von Screens entfernen.
• Single Source of Truth: Vertrauen src/definitions.ts im GitHub Repo.

So funktioniert die Integration

Dieses Plugin ist nur für die native Anzeige eingehender Anrufe zuständig. Dein App verwaltet weiterhin den Transport, die Authentifizierung und die eigentliche Media-Session.

Das gängige Produktionsmuster ist:

1. Dein Backend oder der Aufruf von SDK sendet ein Ring-Event.
2. Deine App ruft showIncomingCall().
3. Das Plugin zeigt das native Incoming-Call-UI.
4. callAccepted weist deine App an, dem eigentlichen Raum oder der VoIP-Session beizutreten.
5. callDeclined, callEnded, oder callTimedOut weist deine App an, den Remote-State aufzuräumen.

Minimale Integration

import { IncomingCallKit } from '@capgo/capacitor-incoming-call-kit';

await IncomingCallKit.requestPermissions();
await IncomingCallKit.requestFullScreenIntentPermission();

await IncomingCallKit.addListener('callAccepted', async ({ call }) => {
  console.log('Accepted', call.callId, call.extra);
  // Start or join your real call session here.
});

await IncomingCallKit.addListener('callDeclined', ({ call }) => {
  console.log('Declined', call.callId);
  // Tell your backend or SDK that the user declined.
});

await IncomingCallKit.addListener('callTimedOut', ({ call }) => {
  console.log('Timed out', call.callId);
  // Clear ringing state in your backend or SDK.
});

await IncomingCallKit.showIncomingCall({
  callId: 'call-42',
  callerName: 'Ada Lovelace',
  handle: '+39 555 010 020',
  appName: 'Capgo Phone',
  hasVideo: true,
  timeoutMs: 45_000,
  extra: {
    roomId: 'room-42',
    callerUserId: 'user_ada',
  },
  android: {
    channelId: 'calls',
    channelName: 'Incoming Calls',
    showFullScreen: true,
  },
  ios: {
    handleType: 'phoneNumber',
  },
});

Wichtige Optionen

• callId: stable identifier reused later with endCall()
• timeoutMs: Best-Effort-Timeout für unbeantwortete Anrufe
• extra: Beliebiger JSON-Inhalt wird in Listener-Payloads zurückgegeben
• android.channelId und android.channelName: Optimierung der Android Notification Channels
• android.showFullScreen: fordert die Android Full-Screen Incoming-Call Activity an
• ios.handleType: Wähle generic, phoneNumber, oder emailAddress für CallKit

Verwaltung aktiver Anrufe

const { calls } = await IncomingCallKit.getActiveCalls();

await IncomingCallKit.endCall({
  callId: 'call-42',
  reason: 'remote-ended',
});

await IncomingCallKit.endAllCalls({
  reason: 'session-reset',
});

Event-Modell

• incomingCallDisplayed: Native UI wurde erfolgreich angezeigt
• callAccepted: Benutzer hat über die native UI zugestimmt
• callDeclined: Benutzer hat vor dem Beitritt abgelehnt
• callEnded: Deine App oder die Plattform hat den getrackten Call beendet
• callTimedOut: Der Call blieb unbeantwortet bis timeoutMs

Jedes Event enthält das normalisierte call Payload sowie dein ursprüngliches extra Objekt.

Plattform-Hinweise

• Lies die iOS-Guide bevor CallKit in einen PushKit- oder APNs-Flow eingebunden wird.
• Lies die Android-Guide bevor man auf Android 14 und neuer auf Full-Screen-Intents setzt.
• Web wird nicht unterstützt.

Weiter geht's nach Getting Started

Wenn du es nutzt Erste Schritte um Dashboard- und API-Operationen zu planen, verbinde es mit @capgo/capacitor-incoming-call-kit verwenden für die native Funktion bei der Nutzung von @capgo/capacitor-incoming-call-kit, API Übersicht für Details zur Implementierung im API Overview, Einführung für die Implementierungsdetails in der Einleitung, API Schlüssel für das Implementierungsdetail in API Keys und Geräte für das Implementierungsdetail in Devices.