# @freshworks/react-native-freshdesk-sdk 中文文档

规范地址：https://npmcn.com/package/%40freshworks/react-native-freshdesk-sdk/

版本：2\.1\.0
npm 元数据更新时间：2026-10-01T06:21:53.207Z
中文译文更新时间：2026-11-15T16:17:26.475Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40freshworks/react-native-freshdesk-sdk
原文对照：https://npmcn.com/package/%40freshworks/react-native-freshdesk-sdk/?lang=original
项目主页：https://github.com/freshworks/freshdesk_react_native_sdk_dev#readme
源码仓库：https://github.com/freshworks/freshdesk_react_native_sdk_dev

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：4.1 MB，124 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \*，react-native \>=0\.75\.0
- 首次发布：2026-07-03T18:25:54.077Z
- 最新版本发布：2026-10-01T06:21:52.996Z
- 近 30 天下载量：2385（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

Freshdesk Android和iOS SDKs的原生包装

## 安装

```sh
npm install @freshworks/react-native-freshdesk-sdk
```

也可以使用：`pnpm add @freshworks/react-native-freshdesk-sdk`、`yarn add @freshworks/react-native-freshdesk-sdk`、`bun add @freshworks/react-native-freshdesk-sdk`

## README

# Freshdesk 反应原生 SDK

"现代售票软件 你的销售和客户业务约定团队会喜欢。" 原生反应 本地新办公桌的包装 [iOS系统](https://github.com/freshworks-oss/freshdesk-ios-sdk) 财务报告和审定财务报表 [机器人](https://github.com/freshworks-oss/freshdesk-android-sdk) SDKs——客户支持,直播 聊天, 和知识库 为您的 React Industrial app .

## 特征

-   现场聊天和支持家庭
-   知识库/财务问题
-   打开特定主题
-   未读信件计数( 一发和实时)
-   用户和售票属性
-   JWT 用户认证
-   用户事件跟踪
-   内容配置/ 本地化
-   自定义链接处理
-   按下通知( 在主机应用程序中本地配置)

## 所需资源

-   **原生反应 QQ 0.75** (单位:千美元)`peerDependencies.react-native` 实值 `>=0.75.0`) (中文(简体) ). 打开 RN < 0.75, 继续使用 `~1.4.3` ——这是1.4.x已经实际坐过的地方.
-   **支持新架构 .** 模块是后相兼容的:一个涡轮模块 当启用了新架构时,则使用经典桥模。 没有 JavaScript API或代码需要修改,无论是哪种方式.
-   iOS 15.0+——作为销售商的本地SDK船 `FreshdeskSDK.xcframework` (无 Swift 软件包管理器 /) `use_frameworks!` 要求).
-   Android API 26+ (英语:`minSdkVersion 26`, (中文(简体) ), `compileSdkVersion 35`,Android Gradle插件 8.6+) 中,该插件可以使用
-   1.12+ (iOS) 可可胶囊

> 从1.4.x升级? 见 [`MIGRATION.md`](https://npmcn.com/package/%40freshworks/react-native-freshdesk-sdk/MIGRATION.md) iOS Podfile / (英语) Gemfile变化是主要步骤.

> 少数方法(`resetUser`, (中文(简体) ), `enableDebugLogs`, (中文(简体) ), `getUnreadCount`行为 android vs iOS上略有不同 因为两个本地的SDK没有 暴露同样的能力——见 [`PLATFORM_DIFFERENCES.md`](https://npmcn.com/package/%40freshworks/react-native-freshdesk-sdk/PLATFORM_DIFFERENCES.md) 在依靠他们准确的运行时间行为之前.

## 安装

```bash
npm install @freshworks/react-native-freshdesk-sdk
# or
yarn add @freshworks/react-native-freshdesk-sdk
```

库会使用自動連接- React Introduct 0.60+不需要手动连接.

### iOS系统

设置您的部署目标 `Podfile` 并安装吊舱——无 `use_frameworks!` 需要(作为X框架销售商的自来自来自来自来自来自来自来自来自来自来自去自来自来自去自去自去自去自去自去自去自去自去自去自去自去自去自去自去自去自去自去自去自去自去自去自去自去自去自去自去自去自去自去自去自去自去自去自去自去自去自去自去自去自自去自自自去自自自去自自去自自去自自自去自自自去自自自自自自去自自去自自自自自去自出自自出自自出自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自自 cockspec 构建为静态框架 :

```ruby
platform :ios, '15.0'
```

```bash
cd ios && pod install
```

保留 `use_frameworks!` 璶 _其他项目_ 依赖性需要它 - 偏好 `:linkage => :static`从1.4.x升级? 1.4.x Podfile / Gemfile 需要文件 首先删除的 SPM 线条——参见 [`MIGRATION.md`](https://npmcn.com/package/%40freshworks/react-native-freshdesk-sdk/MIGRATION.md)。 。 。 .

完整指南(部署目标指针,将框架嵌入您的应用程序捆绑、推) 装有货包的船只——见 `docs/integration/installation.md` (即说. `node_modules/@freshworks/react-native-freshdesk-sdk/docs/integration/installation.md` 一次 ),或浏览而不安装在 [unpkg.com/browse/@freshworks/resact-native-freshdesk-sdk/docs/整合/安装.md](https://unpkg.com/browse/@freshworks/react-native-freshdesk-sdk/docs/integration/installation.md)。 。 。 .

### 机器人

保证 `mavenCentral()` 在你的仓库里 `minSdkVersion` 为 26+。 本地依赖性 (单位:千美元)`com.freshworks.sdk:freshdesk`自动列入.

```groovy
allprojects {
  repositories {
    google()
    mavenCentral()
  }
}
```

## 文档

你从Freshdesk入口处得到你的证书: **管理设置 — 移动聊天 SDK — 您的 SDK** (单位:千美元)`token`, (中文(简体) ), `host`, (中文(简体) ), `sdkId`) (中文(简体) ). 对于 JWT 强制SDK , 您还需要一个用户 `jwt`。 。 。 .

### 初始化

在您的应用生命周期中尽早初始化一次 。 所有其他方法都要求 初始化为先.

**要求 :** `token`, (中文(简体) ), `host`,以及 `sdkId` 从Freshdesk门户. **可选 :** `locale`, (中文(简体) ), `jwt` (仅限JWT强制部件), `debugMode` (Android) (英语). 推动通知设置(Firebase, APN、传送门按键) **没有** 初始化的一部分——SDK用于应用中的支持 ; 当您需要托盘通知时, 单独配置按键.

包装套装 `hostPlatform` 改为 `reactnative` sDK 遥测头的内部 (单位:千美元)`x-fd-mobile-sdk`; 应用程序不通过或配置此选项.

```typescript
import FreshdeskSDK from '@freshworks/react-native-freshdesk-sdk';

await FreshdeskSDK.initialize({
  token: 'your-account-token',
  host: 'your-host.freshdesk.com',
  sdkId: 'your-sdk-id',
  locale: 'en',        // optional, default 'en' (applied at init only)
  jwt: 'your-jwt',     // required only for JWT-enforced SDKs
  debugMode: false,    // optional, Android only
});
```

> 推进通知是可选的 。 推,SDK也必须被初始化 **本土** 在应用 启动,因为设备标志在JS层运行前到达. 见 [推动通知](https://npmcn.com/package/%40freshworks/react-native-freshdesk-sdk/#readme-push-notifications). 应用中支持工程不推接线.

### 启动支助经验

```typescript
// Support home
await FreshdeskSDK.openSupport();

// Knowledge base / FAQ
await FreshdeskSDK.openKnowledgeBase();

// A specific topic (topicId is optional)
await FreshdeskSDK.openTopic({ topicName: 'Orders', topicId: '12345' });

// Dismiss any open Freshdesk view
await FreshdeskSDK.dismiss();
```

### 未读数

```typescript
// One-shot value
const count = await FreshdeskSDK.getUnreadCount();

// Real-time updates
const sub = FreshdeskSDK.addUnreadCountListener((event) => {
  console.log('Unread count:', event.count);
});

// Clean up when done
sub?.remove();
```

### 用户和售票属性

对于非JWT强制SDK,在初始化后设置用户属性. (财产必须是: 在链接部件的联系人/勾选字段下列出白名单 。)

```typescript
await FreshdeskSDK.setUserProperties({
  name: 'Jane Doe',
  email: 'jane@example.com',
  phone: '+1234567890',
});

await FreshdeskSDK.setTicketProperties({
  subject: 'Product Enquiry',
  priority: 3,
});

// Read current user
const user = await FreshdeskSDK.getUser();
```

关于JWT强制自毁K,用户特性通过JWT有效载荷更新——见下文.

### JWT 认证

Freshdesk使用JSON Web Tokens只允许认证的用户开始对话.

1.  通过 `jwt` 期间 `initialize()` (JWT-强制SDKs的强制性规定).
2.  查看用户状态变化 .
3.  更新/更新代号为 `authenticateAndUpdate`。 。 。 .

```typescript
const sub = FreshdeskSDK.addUserStateListener((event) => {
  // States: 'authenticated', 'authExpired', 'notAuthenticated',
  //         'identifierUpdated', 'jwtNotPresent', 'undefined'
  console.log('User state:', event.state);
});

// Refresh or update the user with a new JWT (also updates user/ticket properties from payload)
await FreshdeskSDK.authenticateAndUpdate('new-jwt-token');
```

### 重置用户

调用登录( 或在切换账户前) 来清除用户的会话和数据 .

```typescript
const result = await FreshdeskSDK.resetUser();
// { success: boolean; message?: string; error?: string }
```

### 跟踪用户事件

跟踪事件,以用作互动环境、触发消息或分割.

```typescript
await FreshdeskSDK.trackEvent('add_to_cart', { productId: '12345', quantity: 2 });
```

### 内容配置/ 本地化

覆盖静态部件文本(标题、占位符、票单、隐私政策、响应时间) \[原件:英 您省略的任何字段都会保留部件默认; 通过 `{}` 重置为默认值。 变化仍在继续 立即生效.

```typescript
await FreshdeskSDK.setContentConfiguration({
  headers: {
    chat: 'Talk to our team',
    faq: 'Help Centre',
    ticketForm: { title: 'Raise a ticket', submitBtnTitle: 'Submit' },
  },
  placeholders: {
    replyField: 'Type your reply...',
    searchField: 'Search articles...',
  },
  privacyPolicySetting: {
    privacyPolicyMessage: 'We respect your privacy',
    privacyPolicyLinkText: 'Privacy Policy',
    privacyPolicyLink: 'https://example.com/privacy',
  },
});
```

### 自定义链接处理器

控制SDK内部所压的链接(如深链接).

```typescript
import { Linking } from 'react-native';

const sub = FreshdeskSDK.setLinkHandler((event) => {
  if (event.url.startsWith('myapp://')) {
    // handle deep link
    return;
  }
  Linking.openURL(event.url);
});

sub?.remove();
```

### 事件和清理

```typescript
import FreshdeskSDK, { FreshdeskEvents } from '@freshworks/react-native-freshdesk-sdk';

FreshdeskSDK.addUnreadCountListener(/* ... */);
FreshdeskSDK.addUserStateListener(/* ... */);
FreshdeskSDK.addUserCreatedListener(/* ... */); // iOS only

// Remove every listener (e.g. on unmount)
FreshdeskSDK.removeAllListeners();

// Event name constants
FreshdeskEvents.UNREAD_COUNT_CHANGED; // 'unreadCountChanged'
FreshdeskEvents.USER_STATE_CHANGED;   // 'userStateChanged'
FreshdeskEvents.USER_CREATED;         // 'userCreated'
FreshdeskEvents.ON_LINK_PRESSED;      // 'onLinkPressed'
```

### 推动通知

推车搞定了 **本土** ——没有JavaScript push API. 主机应用程序必须初始化 SDK 在启动时以本地方式转发设备令牌/ 发送信件 :

-   **iOS系统** ——APNs `.p8` 认证密钥, 推动通知+背景模式能力, 以及本地 输入 `AppDelegate`。 。 。 .
-   **机器人** - 消防队(`google-services.json`), Google 服务插件, 以及本地输入 `MainApplication.onCreate()` 加一个 `FirebaseMessagingService`。 。 。 .

SDK源寄存器中的样本应用是参考线条(Freshworks GitHub access) 要求: [样本( a)](https://github.com/freshworks/freshdesk_react_native_sdk_dev/tree/main/sample_app)) (中文(简体) ). 带包裹的全程飞船——见 `docs/integration/installation.md#push-notifications`,或 浏览到 [unpkg.com/browse/@freshworks/resact-native-freshdesk-sdk/docs/整合/安装.md](https://unpkg.com/browse/@freshworks/react-native-freshdesk-sdk/docs/integration/installation.md#push-notifications)。 。 。 .

### SDK 资讯

```typescript
const version = await FreshdeskSDK.getSDKVersion();
```

### 诊断

校验或调试您的整合 :

```typescript
await FreshdeskSDK.enableDebugLogs(true);
const report = await FreshdeskSDK.runDiagnostics();
console.log(report.prettyPrinted);
```

在iOS上,它运行着本土结构化诊断(FreshdeskSDK 1.3+). 在Android的包装上 在本地诊断对土地进行平等使用之前进行回返综合检查 `debugMode: true` 财务报告和审定财务报表 显示更深的信号.

## AI 整合工具箱

Npm 包装一个 **AI 整合工具箱** 教授编码代理(Cursor, Claude, 副驾驶, Codex, Kiro) 如何将 SDK 集成并调试到您的 React Introduct app中.

安装后 :

```bash
cp -R node_modules/@freshworks/react-native-freshdesk-sdk/ai-integration-kit/. /path/to/your-app/
```

然后问你的AI工具:"使用新鲜的桌面-反应-内在-整合技能并连接新鲜的桌面 支持。"

警棍技能(用于SDK维护者): `ai-integration-kit/ai/skills/freshdesk-react-native-integration/SKILL.md`。 。 。 . 再生成工具副本 `npm run sync:ai-kit`。 。 。 .

全套工具绘图和使用指导船舶使用该包——见 `ai-integration-kit/README.md` (即说. `node_modules/@freshworks/react-native-freshdesk-sdk/ai-integration-kit/README.md` ),或浏览而不安装 [unpkg.com/browse/@refreshworks/resact-native-refreshdesk-sdk/ai-Institution-kit/README.md 互联网档案馆的存檔,存档日期2013-12-22](https://unpkg.com/browse/@freshworks/react-native-freshdesk-sdk/ai-integration-kit/README.md)。 。 。 .

## 处理错误

所有的方法都回报承诺。 常见错误代码 :

| 代码 | 含义 |
| --- | --- |
| `FRESHDESK_INVALID_CONFIG` | 失踪 `token` 编号 : `host` 编号 : `sdkId` |
| `FRESHDESK_NOT_INITIALIZED` | 之前使用过一种方法 `initialize()` |
| `FRESHDESK_INIT_ERROR` | 初始化失败( 证书/ 网络) |
| `FRESHDESK_NO_ACTIVITY` 编号 : `FRESHDESK_NO_VIEW_CONTROLLER` | 应用没有前置 |
| `FRESHDESK_AUTH_ERROR` | JWT 认证失败 |

## 完整文档

这些导航船,包裹在 `docs/integration/` (即说. `node_modules/@freshworks/react-native-freshdesk-sdk/docs/integration/` (已安装). 你们可以 也可以不安装即通过unpkg浏览:

-   [安装](https://unpkg.com/browse/@freshworks/react-native-freshdesk-sdk/docs/integration/installation.md)
-   [初始化](https://unpkg.com/browse/@freshworks/react-native-freshdesk-sdk/docs/integration/initialization.md)
-   [API 参考](https://unpkg.com/browse/@freshworks/react-native-freshdesk-sdk/docs/integration/api_reference.md)
-   [解决问题](https://unpkg.com/browse/@freshworks/react-native-freshdesk-sdk/docs/integration/troubleshooting.md)

## 许可证

麻省理工学院

## 支助

-   电子邮件 : [支持@ refreshdesk.com](mailto:support@freshdesk.com)
-   [支助门户](https://support.freshdesk.com/)
-   [报告问题](https://github.com/freshworks/freshdesk_react_native_sdk_dev/issues) (需要 Freshworks GitHub 访问; 使用上方的支持门户)

## 常见问题

### @freshworks/react-native-freshdesk-sdk 是什么？

Freshdesk Android和iOS SDKs的原生包装

### 如何安装 @freshworks/react-native-freshdesk-sdk？

在项目目录运行 npm install @freshworks/react-native-freshdesk-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\*）、react-native（\>=0\.75\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @freshworks/react-native-freshdesk-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @freshworks/react-native-freshdesk-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @freshworks/react-native-freshdesk-sdk 可以商用吗？

@freshworks/react-native-freshdesk-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @freshworks/react-native-freshdesk-sdk 的下载量有多少？

根据 npm 官方下载统计，@freshworks/react-native-freshdesk-sdk 在 2026/10/16 – 2026/11/14 这 30 天内被下载 2,385 次，日均约 80 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @freshworks/react-native-freshdesk-sdk 还在维护吗？

最新版本 2\.1\.0 发布于 2026/10/01（1 个月前）；至今共发布 13 个版本，其中过去 12 个月发布了 13 个；首次发布于 2026/07/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。