Per iniziare

Installazione

Puoi usare il nostro setup assistito dall'IA per installare il plugin. Aggiungi le skill Capgo al tuo strumento di IA usando il seguente comando:

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

Poi usa il seguente prompt:

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

Se preferisci la configurazione manuale, installa il plugin eseguendo questi comandi e segui le istruzioni specifiche per piattaforma qui sotto:

1. Installa il pacchetto

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

2. Sincronizza i progetti nativi

   bunx cap sync

3. Scegli la sorgente della chiamata Decidi se l'evento incoming-call provenga dal tuo backend, da un SDK come Twilio o Stream, o da un percorso push nativo come FCM o PushKit.

Avvio rapido

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

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

Esempio: endCall

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

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

Esempio: endAllCalls

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

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

Errori comuni

• Permessi: chiamata checkPermissions() poi requestPermissions() quando necessario.
• Listener: rimuovi gli handle quando gli schermi vengono smontati.
• Fonte di verità: fidati src/definitions.ts nel repo GitHub.

Come funziona l'integrazione

Questo plugin gestisce solo la visualizzazione nativa della chiamata in arrivo. La gestione del trasporto, dell'autenticazione e della sessione media rimane a carico della tua app.

Il pattern standard in produzione è:

1. Il tuo backend o il SDK di chiamata emette un evento di squillo.
2. La tua app chiama showIncomingCall().
3. Il plugin mostra l'interfaccia nativa della chiamata in arrivo.
4. callAccepted indica alla tua app di unirsi alla stanza o alla sessione VoIP effettiva.
5. callDeclined, callEnded, o callTimedOut indica alla tua app di ripulire lo stato remoto.

Integrazione minima

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',
  },
});

Opzioni importanti

• callId: identificatore stabile riutilizzato in seguito con endCall()
• timeoutMs: timeout best-effort per chiamate senza risposta
• extra: JSON arbitrario restituito nei payload del listener
• android.channelId e android.channelName: ottimizzazione dei canali di notifica Android
• android.showFullScreen: richiede l'activity Android full-screen per le chiamate in arrivo
• ios.handleType: scegli generic, phoneNumber, o emailAddress per CallKit

Gestione delle chiamate attive

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

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

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

Event model

• incomingCallDisplayedl'interfaccia nativa è stata mostrata correttamente
• callAccepted: l'utente ha accettato dall'interfaccia nativa
• callDeclined: l'utente ha rifiutato prima di unirsi
• callEnded: la tua app o la piattaforma ha terminato la chiamata tracciata
• callTimedOut: la chiamata è rimasta senza risposta fino a timeoutMs

Ogni evento contiene i dati normalizzati call payload normalizzato e il tuo extra object.

Note sulla piattaforma

• Leggi la Guida iOS prima di integrare CallKit in un flusso PushKit o APNs.
• Leggi la Guida Android prima di fare affidamento sui full-screen intents su Android 14 e versioni successive.
• Il Web non è supportato.

Continua da Getting Started

Se stai usando Per iniziare per pianificare le operazioni della dashboard e di API, collegalo a Utilizzo di @capgo/capacitor-incoming-call-kit per la funzionalità nativa in Using @capgo/capacitor-incoming-call-kit, Panoramica API per i dettagli di implementazione in Panoramica di API, Introduzione per i dettagli di implementazione in Introduzione, Chiavi API per i dettagli di implementazione in Chiavi API, e Dispositivi per i dettagli di implementazione in Dispositivi.