시작하기

설치

AI-Assisted Setup으로 플러그인을 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

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

수동 설정을 선호한다면, 다음 명령어를 실행하여 플러그인을 설치하고 아래의 플랫폼별 지침을 따르세요:

1. 패키지 설치

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

2. 네이티브 프로젝트 동기화

   bunx cap sync

3. 벨소리 소스 선택 incoming-call 이벤트가 백엔드에서 오는지, Twilio나 Stream 같은 SDK에서 오는지, 아니면 FCM이나 PushKit 같은 네이티브 푸시 경로에서 오는지 정하세요.

빠른 시작

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

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

예시: endCall

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

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

예시: endAllCalls

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

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

자주 하는 실수

• 권한: 호출 checkPermissions() 그다음 requestPermissions() 필요할 때.
• 리스너: 화면이 언마운트될 때 핸들을 제거합니다.
• 신뢰할 수 있는 소스: 신뢰 src/definitions.ts GitHub 레포지토리에서.

통합 방식 및 구조

이 플러그인은 네이티브 수신 전화 화면 표시 기능만 담당합니다. 통신, 인증 및 실제 미디어 세션은 여전히 앱에서 직접 관리해야 합니다.

일반적인 프로덕션 패턴은 다음과 같습니다:

1. 백엔드 또는 호출 SDK에서 벨소리(ring) 이벤트를 발생시킵니다.
2. 앱에서 호출합니다 showIncomingCall().
3. 플러그인이 네이티브 수신 전화 UI를 표시합니다.
4. callAccepted 앱에 실제 룸 또는 VoIP 세션에 참여하도록 알립니다.
5. callDeclined, callEnded, 또는 callTimedOut 앱에 원격 상태를 정리하도록 알립니다.

최소한의 통합

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

중요 옵션

• callId: 나중에 재사용되는 안정적인 식별자 endCall()
• timeoutMs: 최선의 노력(best-effort) 기반 미응답 타임아웃
• extra: 리스너 페이로드에 그대로 반환되는 임의의 JSON
• android.channelId 및 android.channelName: Android 알림 채널 최적화
• android.showFullScreen: Android 전체 화면 수신 전화 액티비티 요청
• ios.handleType: 선택 generic, phoneNumber, 또는 emailAddress CallKit용

활성 통화 관리

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

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

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

이벤트 모델

• incomingCallDisplayed: 네이티브 UI가 성공적으로 표시됨
• callAccepted: 사용자가 네이티브 UI에서 수락함
• callDeclined: 참여 전 사용자가 거절함
• callEnded: 앱 또는 플랫폼이 추적 중인 통화를 종료함
• callTimedOut: 통화가 다음 시점까지 응답되지 않음 timeoutMs

각 이벤트에는 정규화된 call payload와 사용자의 원본 extra object가 포함됩니다.

플랫폼 참고 사항

• 앱 스위처 동작에 대한 iOS 가이드 CallKit을 PushKit 또는 APNs 흐름에 연결하기 전에 확인하세요.
• 앱 스위처 동작에 대한 Android 가이드 Android 14 이상에서 전체 화면 인텐트(full-screen intents)를 사용하기 전에 확인하세요.
• Web은 지원되지 않습니다.

시작하기 다음 단계

사용 중이라면 시작하기 대시보드 및 API 운영을 계획하려면, 이를 다음과 연결하세요 @capgo/capacitor-incoming-call-kit 사용하기 @capgo/capacitor-incoming-call-kit를 사용하여 네이티브 기능을 구현하려면, API 개요 구현 세부 사항은 API 개요에서 소개 구현 세부 사항은 소개에서 API 키 API Keys의 구현 세부 사항은, 기기 Devices의 구현 세부 사항은.