快速入门 · Cloudflare Realtime docs

前提条件

要在您的应用程序中集成 RealtimeKit，您必须拥有 Cloudflare 账户 ↗。

按照创建 API 令牌指南，通过 Cloudflare 仪表板 ↗ 创建新令牌。
配置权限时，确保已选择 Realtime / Realtime Admin 权限。
根据您的用例需要，配置任何其他访问策略和限制。

可选： 或者，通过 API 以编程方式创建令牌。请确保您的访问策略包含 Realtime 权限。

安装

根据您要构建的平台选择框架。

请在您的项目仓库中安装以下依赖项：

npm i @cloudflare/realtimekit-react @cloudflare/realtimekit-react-ui

可选： 您也可以在我们的现成模板基础上进行构建：

git clone https://github.com/cloudflare/realtimekit-web-examples.git
cd realtimekit-web-examples/react-examples/examples/default-meeting-ui

请在您的项目仓库中安装以下依赖项：

npm i @cloudflare/realtimekit-web @cloudflare/realtimekit-ui

可选： 您也可以在我们的现成模板基础上进行构建：

git clone https://github.com/cloudflare/realtimekit-web-examples.git
cd realtimekit-web-examples/html-examples/examples/default-meeting-ui

请在您的项目仓库中安装以下依赖项：

npm i @cloudflare/realtimekit-angular @cloudflare/realtimekit-angular-ui

可选： 您也可以在我们的现成模板基础上进行构建：

git clone https://github.com/cloudflare/realtimekit-web-examples.git
cd realtimekit-web-examples/angular-examples/examples/default-meeting-ui

使用 Swift Package Manager 安装 RealtimeKit UI Kit：

在 Xcode 中，转到 File > Add Package Dependencies。
输入包 URL：https://github.com/dyte-in/RealtimeKitUI。
选择版本并将包添加到您的项目中。

将以下条目添加到 Info.plist 文件中。这将赋予您的应用程序访问摄像头和麦克风、访问照片以及安装所需字体和图标的权限。

<key>NSBluetoothPeripheralUsageDescription</key>
<string>Access Bluetooth to connect to headphones and audio devices during calls.</string>
<key>NSBluetoothAlwaysUsageDescription</key>
<string>Access Bluetooth to connect to headphones and audio devices during calls.</string>
<key>NSCameraUsageDescription</key>
<string>Access camera to enable video during meetings.</string>
<key>NSMicrophoneUsageDescription</key>
<string>Access microphone to enable audio during meetings.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Access photos to share images during meetings.</string>
<key>UIBackgroundModes</key>
<array>
  <string>audio</string>
  <string>voip</string>
  <string>fetch</string>
  <string>remote-notification</string>
</array>

UIBackgroundModes 键用于 iOS 应用程序的 Info.plist 文件中，以声明应用程序支持的后台执行模式。此键是一个字符串数组，指定了应用程序支持的后台任务类型。通过声明后台模式，应用程序可以在后台继续运行并执行特定任务，即使它不在前台也是如此。

通过将依赖项添加到您的 pubspec.yaml 文件中来安装 RealtimeKit UI Kit：

flutter pub add realtimekit_ui

然后将包导入到您的项目中：

import 'package:realtimekit_ui/realtimekit_ui.dart';

在 <project root>/android/app/build.gradle 处的 build.gradle 文件中设置 compileSdkVersion 36 和 minSdkVersion 24：

defaultConfig {
  ...
  compileSdkVersion 36
  minSdkVersion 24
  ...
}

将 Kotlin 版本更改为 1.9.0：

ext.kotlin_version = '1.9.0'

在您的 Podfile 中将平台设置为 iOS 13.0 或更高版本：

platform :ios, '13.0'

将以下条目添加到 Info.plist 文件中。这将赋予您的应用程序访问摄像头和麦克风、访问照片以及安装所需字体和图标的权限。

<key>NSBluetoothPeripheralUsageDescription</key>
<string>Access Bluetooth to connect to headphones and audio devices during calls.</string>
<key>NSBluetoothAlwaysUsageDescription</key>
<string>Access Bluetooth to connect to headphones and audio devices during calls.</string>
<key>NSCameraUsageDescription</key>
<string>Access camera to enable video during meetings.</string>
<key>NSMicrophoneUsageDescription</key>
<string>Access microphone to enable audio during meetings.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Access photos to share images during meetings.</string>
<key>UIBackgroundModes</key>
<array>
  <string>audio</string>
  <string>voip</string>
  <string>fetch</string>
  <string>remote-notification</string>
</array>

可选： 如果您允许用户在聊天中下载附件，请将以下权限添加到您的 Info.plist：

<key>LSSupportsOpeningDocumentsInPlace</key>
<true/>
<key>UIFileSharingEnabled</key>
<true/>

最低要求： React Native 0.84 或更高版本，React 19 或更高版本。

安装依赖项：

npm install @cloudflare/realtimekit-react-native @cloudflare/react-native-webrtc @cloudflare/realtimekit-react-native-ui @react-native-documents/picker react-native-file-viewer react-native-fs react-native-sound-player react-native-webview react-native-svg@^15.13.0 react-native-safe-area-context@^5.0.0

最低 Expo 版本： 56 或更高版本。

安装依赖项：

npx expo install @cloudflare/realtimekit-react-native-ui @cloudflare/realtimekit-react-native @cloudflare/react-native-webrtc @react-native-documents/picker react-native-file-viewer react-native-fs react-native-sound-player react-native-webview react-native-svg@^15.13.0 react-native-safe-area-context@^5.0.0

安装 Expo 配置插件：

npx expo install @expo/config-plugins

将插件添加到您的 app.json 中：

{
	"expo": {
		"plugins": [
			"@cloudflare/realtimekit-react-native",
			"@cloudflare/react-native-webrtc"
		]
	}
}

运行 prebuild 以设置原生模块：

npx expo prebuild

以下说明适用于 Release 构建。Debug 构建无需额外步骤即可工作。

编辑您的 android/gradle.properties 并添加以下行：

android.useFullClasspathForDexingTransform=true

在 strings.xml 文件中添加所需的 blob_provider_authority 字符串资源：

<resources>
  ...
  <string name="blob_provider_authority">YOUR_APP_RESOURCE_NAME</string>
  ...
</resources>

创建或追加到 android/app/proguard-rules.pro 文件中：

-keep class realtimekit.org.webrtc.** { *; }
-dontwarn org.chromium.build.BuildHooksAndroid

在您的 android/app/build.gradle 中，编辑 release 配置并添加以下行以导入 ProGuard 配置：

buildTypes {
  release {
    ...
    proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
  }
}

后台音频和视频 (Android)

SDK 包含一个 Android 前台服务，当应用程序移至后台时，该服务会保持音频和视频继续运行。当参与者加入会议时，该服务会自动启动，并在他们离开时停止。

默认情况下，该服务已启用并带有通用通知文本。若要自定义通知或禁用服务，请在调用 initMeeting 之前将 keepAliveService 传递给 useRealtimeKitClient hook：

const [meeting, initMeeting] = useRealtimeKitClient({
  keepAliveService: {
    enabled: true,                        // set to false to disable entirely
    title: "Team call",                   // notification title
    text: "Tap to return to your meeting", // notification body
  },
});

在 Android 13 及更高版本上，SDK 会自动请求 POST_NOTIFICATIONS 权限，以便通知显示在下拉通知栏中。无需额外设置。

最低支持的 iOS 版本：15.1。

打开您的 Podfile 并将平台设置为 iOS 15.1：

platform :ios, '15.1'

将以下权限条目添加到您的 Info.plist 文件中：

<key>NSCameraUsageDescription</key>
<string>Access camera to enable video during meetings.</string>
<key>NSMicrophoneUsageDescription</key>
<string>Access microphone to enable audio during meetings.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Access photos to share images during meetings.</string>
<key>UIViewControllerBasedStatusBarAppearance</key>
<false/>

屏幕共享 (iOS)

iOS 屏幕共享需要 Broadcast Upload Extension 和额外的原生设置。请参阅 Screen Share Setup (iOS) 指南以获取完整说明。

原生设置完成后，将 iOSScreenshareEnabled={true} 传递给 RtkMeeting，以在 UI 中启用屏幕共享按钮：

<RtkMeeting meeting={meeting} iOSScreenshareEnabled={true} />

创建 RealtimeKit 应用

您可以通过在 Cloudflare 仪表板 ↗ 中点击“Create App”来创建应用。

可选： 您还可以使用我们的 API 参考来创建应用：

curl --location 'https://api.cloudflare.com/client/v4/accounts/<account_id>/realtime/kit/apps' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <api_token>' \
--data '{"name": "My First Cloudflare RealtimeKit app"}'

注意： 我们建议为暂存和生产环境创建不同的应用。

创建会议

使用我们的 Meetings API 创建会议。我们将在后续步骤中使用响应中的 ID。

curl --location 'https://api.cloudflare.com/client/v4/accounts/<account_id>/realtime/kit/<app_id>/meetings' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <api_token>' \
--data '{"title": "My First Cloudflare RealtimeKit meeting"}'

添加参与者

创建预设

预设定义了用户应拥有的权限。在“概念”指南中了解更多信息。您可以使用 Presets API 或通过 RealtimeKit 仪表板 ↗ 创建新预设。

注意： 如果您在仪表板中创建了应用，请跳过此步骤 —— 默认预设已为您设置好了。

注意： 预设可以在多个会议中重复使用。定义一次角色（例如 admin 或 viewer），并将其应用于任意数量会议中的参与者。

添加参与者

使用上面创建的 Meeting ID 并从可用选项中选择 Preset Name，即可将参与者添加到会议中。

响应中包含一个 authToken，客户端 SDK 使用该令牌将此参与者添加到会议室。

curl --location 'https://api.cloudflare.com/client/v4/accounts/<account_id>/realtime/kit/<app_id>/meetings/<meeting_id>/participants' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <api_token>' \
--data '{
  "name": "Mary Sue",
  "preset_name": "<preset_name>",
  "custom_participant_id": "<uuid_of_the_user_in_your_system>"
}'

在 API 参考中了解有关添加参与者的更多信息。

前端集成

您现在可以将 RealtimeKit Client SDK 添加到您的应用程序中。

在您的 React 应用程序中，添加以下代码：

import { useEffect } from "react";
import {
	useRealtimeKitClient,
	useRealtimeKitMeeting,
	RealtimeKitProvider,
} from "@cloudflare/realtimekit-react";
import { RtkMeeting } from "@cloudflare/realtimekit-react-ui";

export default function App() {
  const [meeting, initMeeting] = useRealtimeKitClient();

  useEffect(() => {
    initMeeting({ authToken: '<auth-token>' });
  }, []);

  return (
    <RealtimeKitProvider value={meeting}>
      <MyMeetingUI />
    </RealtimeKitProvider>
  );
}

export default function MyMeetingUI() {
  const { meeting } = useRealtimeKitMeeting();
  return (
    <RtkMeeting mode="fill" meeting={meeting} showSetupScreen={true} />
  );
}

将 <auth-token> 替换为从上一步获取的 authToken。

运行应用程序并导航到会议页面，以查看运行中的 RealtimeKit Client SDK。

npm run dev

可选： 如果您使用的是我们现成的模板，请运行以下命令来启动应用程序：

npm i -g vite && npm run dev

在浏览器中打开应用。要加入会议，请将您的 auth token 附加到预览 URL：

http://localhost:5173?authToken=<auth_token>

在您的 HTML 应用程序中，添加以下代码：

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Default Meeting UI | RealtimeKit</title>

    <!-- 导入助手以加载 UI Kit 组件 -->
    <script type="module">
      import { defineCustomElements } from 'https://cdn.jsdelivr.net/npm/@cloudflare/realtimekit-ui@latest/loader/index.es2017.js';
      defineCustomElements();
    </script>

    <!-- 通过 CDN 导入 RealtimeKit Core -->
    <script src="https://cdn.jsdelivr.net/npm/@cloudflare/realtimekit@latest/dist/browser.js"></script>

  </head>
  <body>
    <rtk-meeting id="my-meeting" show-setup-screen="true" />

    <script>
      const searchParams = new URL(window.location.href).searchParams;

      const authToken = searchParams.get('authToken');

      if (!authToken) {
        alert(
          "An authToken wasn't passed, please pass an authToken in the URL query to join a meeting."
        );
      }

      // 初始化会议
      RealtimeKitClient.init({
        authToken,
      }).then((meeting) => {
        document.getElementById('my-meeting').meeting = meeting;
      });
    </script>

  </body>
</html>

将 <auth-token> 替换为从上一步获取的 authToken。

运行应用程序并导航到会议页面，以查看运行中的 RealtimeKit Client SDK。

npm run dev

可选： 如果您使用的是我们现成的模板，请运行以下命令来启动应用程序：

npm i -g vite && npm run dev

在浏览器中打开应用。要加入会议，请将您的 auth token 附加到预览 URL 中：

http://localhost:5173?authToken=<auth_token>

将 RTKComponentsModule 加载到您的应用模块中。这通常是 app.module.ts 文件。这使您可以在组件 HTML 文件中使用 UI 组件。

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { RTKComponentsModule } from '@cloudflare/realtimekit-angular';
import { AppComponent } from './app.component';

@NgModule({
declarations: [AppComponent],
imports: [BrowserModule, RTKComponentsModule],
providers: [],
bootstrap: [AppComponent],
})
export class AppModule {};

可选： 如果您使用的是 TypeScript，请在 tsconfig.json 中将 allowSyntheticDefaultImports 设置为 true。

{
	"compilerOptions": {
		"allowSyntheticDefaultImports": true
	}
}

将 RtkMeeting 组件加载到您的模板文件 (component.html) 中。

<rtk-meeting #myid></rtk-meeting>

初始化会议

class AppComponent {
title = 'MyProject';
@ViewChild('myid') meetingComponent: RtkMeeting;
rtkMeeting: RealtimeKitClient;

async ngAfterViewInit() {
	const meeting = await RealtimeKitClient.init({
	authToken: '<auth-token>',
	});
	meeting.join();
	this.rtkMeeting = meeting;
	if (this.meetingComponent) this.meetingComponent.meeting = meeting;
}
}

将 <auth-token> 替换为从上一步获取的 authToken。

运行应用程序并导航到会议页面，以查看运行中的 RealtimeKit Client SDK。

npm run dev

可选： 如果您使用的是我们现成的模板，请运行以下命令来启动应用程序：

npm i -g vite && npm run dev

在浏览器中打开应用。要加入会议，请将您的 auth token 附加到预览 URL 中：

http://localhost:5173?authToken=<auth_token>