快速入门

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

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

然后使用以下 prompt：

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 事件是来自您的后端、SDK（例如 Twilio 或 Stream），还是来自 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 发送一个来电事件。
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: 尽力而为的未接听超时
• extra: 监听器 payload 中回显的任意 JSON
• android.channelId 以及 android.channelName: Android 通知渠道调优
• android.showFullScreen: 请求 Android 全屏来电 Activity
• 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 端。

从入门指南继续

如果你正在使用 快速入门 要规划 dashboard 和 API 操作，请将其连接到 使用 @capgo/capacitor-incoming-call-kit 用于“使用 @capgo/capacitor-incoming-call-kit”中的原生功能， API 概览 关于 API Overview 中的实现细节， 简介 关于 Introduction 中的实现细节， API 密钥 有关 API Keys 的实现细节，以及 设备 有关 Devices 的实现细节。