Getting Started

1. 安装包

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

2. 同步本地项目

   bunx cap sync

3. 选择您的环源 决定是否来自您的后端、一个 SDK 如 Twilio 或 Stream，还是一个本地推送路径，如 FCM 或 PushKit。

如何集成

本插件仅负责本地 incoming-call 的呈现。您的应用仍然拥有传输、认证和实际媒体会话。

集成的常见生产模式是：

1. Your backend or calling SDK 发出一个环事件。
2. Your app calls showIncomingCall().
3. The plugin 展示原生 incoming-call 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：最佳努力未回答超时
• extra：监听器载荷中回显任意 JSON
• android.channelId 和 android.channelName：调节 Android 通知频道
• android.showFullScreen：请求 Android 全屏 incoming-call 活动
• 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 数据包和您的原始 extra 对象。

平台备注

• 阅读 iOS 指南 在将 CallKit 整合到 PushKit 或 APNs 流程之前，请阅读此文档。
• 阅读 Android 指南 在 Android 14 或更高版本上使用全屏意图之前，请阅读此文档。
• Web 不受支持。

继续从 Getting Started

如果您正在使用 Getting Started 来规划仪表板和 API 操作，请将其连接到 使用 @capgo/capacitor-incoming-call-kit 使用 @capgo/capacitor-incoming-call-kit 的原生能力 API 简介 使用 API 简介中的实现细节 介绍 使用介绍中的实现细节 API 密钥 使用 API 密钥中的实现细节 设备 使用设备中的实现细节