# @go1/go1-embedding-react-sdk 中文文档

规范地址：https://npmcn.com/package/%40go1/go1-embedding-react-sdk/

版本：0\.13\.1
npm 元数据更新时间：2026-06-25T13:29:14.050Z
中文译文更新时间：2026-11-16T17:31:23.010Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40go1/go1-embedding-react-sdk
原文对照：https://npmcn.com/package/%40go1/go1-embedding-react-sdk/?lang=original

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

- 包体积（解压后）：47 kB，12 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \>=16\.8
- 首次发布：2023-07-11T05:20:33.979Z
- 最新版本发布：2026-06-25T13:29:13.856Z
- 近 30 天下载量：59142（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：87（近 12 个月 9 个）

## 中文简介

一个将 Go1 内容嵌入您的网站的 React 库 .

## 安装

```sh
npm install @go1/go1-embedding-react-sdk
```

也可以使用：`pnpm add @go1/go1-embedding-react-sdk`、`yarn add @go1/go1-embedding-react-sdk`、`bun add @go1/go1-embedding-react-sdk`

## README

# Go1 嵌入反相 SDK

将 GO1 内容视图嵌入您网站的回放钩 。 包括您网站和 GO1 内容视图之间的双向消息 .

## 安装

```sh
npm install @go1/go1-embedding-react-sdk
```

## 使用量

从库中导入钩子并用于您的功能组件.

```tsx
import { useMemo, useCallback } from 'react';
import { ContentViewProps, useGo1ContentView } from '@go1/go1-embedding-react-sdk';

export function YourHostingComponent() {
  const onGo1MessageReceived = useCallback((message) => {
    console.log('Received postMessage from Go1');
    console.log(message);
  }, []);

  const options = useMemo<ContentViewProps>(() => {
    return {
      feature: 'ai-chat',
      portalURL: 'learning-incorporated-usa.mygo1.com',
      onGo1MessageReceived,
    };
  }, []);

  const { sendMessageToGo1, ContentView } = useGo1ContentView(options);

  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <ContentView />
    </div>
  );
}
```

# APIs 密码

### 类型

```typescript
export type OnGo1MessageReceived = (message: Go1Message) => void;

export type SendMessageToGo1 = (message: Go1Message) => void;

export type IframesMap = { [key: string]: HTMLIFrameElement };

export interface FeatureAttributeCommon {
  shouldSuppressPreview?: boolean;
  shouldSuppressOpeningPlayer?: boolean;
  shouldShowSelectWelcomeModal?: boolean;
  shouldSuppressBookmark?: boolean;
  shouldSuppressBookmarkAction?: boolean;
  shouldSuppressPlaylistAdministration?: boolean;
  shouldSuppressShareLink?: boolean;
  shouldSuppressLibrary?: boolean;
  shouldSuppressPlaylist?: boolean;
  shouldSuppressCopyRightFooter?: boolean;
  shouldSuppressPlay?: boolean;
  shouldSuppressExport?: boolean;
  shouldSuppressAIAgents?: boolean;
  shouldSuppressAIDiscoveryAgent?: boolean;
  shouldSuppressAIReportingAgent?: boolean;
  contentScope?: 'subscription' | 'library';
  shouldSuppressEndorsement?: boolean;
}


export type ThemeMode = 'light' | 'dark';

export interface ThemeModeInformation {
  mode: ThemeMode;
}

export interface ThemeInformation {
  /** Hex string, starting with a #. Example #0437F2 */
  accent: string;
  mode?: ThemeMode;
}

export type Go1MessageType =
  | 'preview_start_content'
  | 'preview_close'
  | 'preview_add_content_success'
  | 'preview_add_content_failure'
  | 'preview_remove_content_success'
  | 'preview_remove_content_failure'
  | 'parent_show_preview'
  | 'set_additional_embedding_data'
  | 'go1_app_initialised'
  | 'ott_required'
  | 'search_result_selected'
  | 'search_filter_toggle'
  | 'pass_ott'
  | 'logout',
  | 'sync_content'
  | 'inter_feature_navigation'
  | 'side_drawer_open'
  | 'side_drawer_close'
  | 'swap_out_open'
  | 'swap_out_close'
  | 'play_content'
  | 'library_content_added'
  | 'library_content_removed'
  | 'library_content_exported'
  | 'save_content';

export interface Go1Message {
  type: Go1MessageType;
  payload?: any;
}


export interface FeatureAttributeCommon {
  shouldSuppressPreview?: boolean;
  shouldSuppressOpeningPlayer?: boolean;
  shouldShowSelectWelcomeModal?: boolean;
  shouldSuppressBookmark?: boolean;
  shouldSuppressBookmarkAction?: boolean;
  shouldSuppressPlaylistAdministration?: boolean;
  shouldSuppressShareLink?: boolean;
  shouldSuppressLibrary?: boolean;
  shouldSuppressPlaylist?: boolean;
  shouldSuppressCopyRightFooter?: boolean;
  shouldSuppressPlay?: boolean;
  shouldSuppressExport?: boolean;
  shouldSuppressAIAgents?: boolean;
  shouldSuppressAIDiscoveryAgent?: boolean;
  shouldSuppressAIReportingAgent?: boolean;
  contentScope?: 'subscription' | 'library';
  shouldSuppressEndorsement?: boolean;
}

/**
 * @deprecated Use `feature: 'discovery-agent'` instead.
 * Used to configure the `ai-chat` feature.
 */
export interface FeatureAttributesAIChat extends FeatureAttributeCommon {
  intent?: 'skill_gap' | 'improve_skills' | 'next_role' | 'aspirations';
  message?: string; // The desired message to start the chat, which will be shown to the user
  existingSkills?: string[]; // max items 7, any more are discarded
  desiredSkills?: string[]; // max items 7, any more are discarded
  desiredRole?: string; // e.g. "Senior Account Manager"
  showFooter?: boolean // Whether to show/hide the footer, defaults to true
}

/**
 * Used to configure the `discovery-agent` feature
 */
export interface FeatureAttributesDiscoveryAgent extends FeatureAttributeCommon {
  message?: string; // The desired message to start the chat, which will be shown to the user
}

/**
 * Used to configure the `preview` feature
 */
export interface FeatureAttributesPreview extends FeatureAttributeCommon {
  id: number;
  startWith1Player?: boolean;
  showFooter?: boolean;
  contentRatingType?: 'no rating' | 'five star rating' | 'like rating';
}

/**
 * Used to configure the `wallet` feature
 */
export interface FeatureAttributesWallet extends FeatureAttributeCommon {
  walletMode: 'setup' | 'main';
  deepLink?: string;
  oneClickBuyUrl?: string;
}

export interface FeatureAttributesLibrary extends FeatureAttributeCommon, FeatureAttributesRetirement {
  libraryEmptyStateDescription?: string;
  shouldShowLibraryTabs?: boolean;
}

export interface FeatureAttributesRetirement extends FeatureAttributeCommon {
  shouldShowAlternativesSearchButton?: boolean;
  shouldShowNotificationEmailRegisterSwitch?: boolean;
}

export interface FeatureAttributesSearch extends FeatureAttributeCommon {
  searchTerm?: string;  // If the embedding search feature includes a search term, the app will initialize with the pre-filled search term.
}
export interface FeatureAttributesProspect {
  isProspectExperience?: boolean;
}

export interface FeatureAttributesGo1LearnSearch
  extends FeatureAttributeCommon,
    FeatureAttributesProspect {
  searchTerm?: string; // If the embedding search feature includes a search term, the app will initialize with the pre-filled search term.
  searchProvider?: string; // If the embedding search feature includes a search provider, the app will initialize with the pre-filled search provider.
}

export type FeatureAttributesRecommendations = Omit<FeatureAttributesGo1LearnSearch, 'searchProvider'> & {
  providers?: string[]; // If the embedding recommendations feature includes a search providers, the app will initialize with the pre-filled search provider
  skills?: string[]; // If the embedding recommendations feature includes a search skills, the app will initialize with the pre-filled search skills
  topics?: string[]; // If the embedding recommendations feature includes a search topics, the app will initialize with the pre-filled search topics
  sort?: string; // If the embedding recommendations feature includes a search sort, the app will initialize with the pre-filled search sort
}

export type FeatureAttributes =
  | FeatureAttributesAIChat
  | FeatureAttributesDiscoveryAgent
  | FeatureAttributesPreview
  | FeatureAttributesWallet
  | FeatureAttributesLibrary
  | FeatureAttributesSearch
  | FeatureAttributesRecommendations;

export interface AdditionalUserInfo {
  jobTitle: string;
}

export type FeatureType =
  /** @deprecated Use 'discovery-agent' instead. */
  | 'ai-chat'
  | 'discovery-agent'
  /** @deprecated Use 'admin-curation' instead. */
  | 'content-hub'
  | 'preview'
  | 'search'
  | 'admin-curation';

export interface InitOptions {
  /** Mandatory identifier for the embedded feature */
  feature: FeatureType;
  /** Optional element id to search for, and use as the parent for the Go1 content view (use either this or `iframeParentElement`, not both) */
  iframeParentId?: string;
  /** Optional element to use as the parent for the Go1 content view (use either this or `iframeParentId`, not both) */
  iframeParentElement?: HTMLElement;
  /** Optional parameters to configure the feature. See associated types for examples */
  featureAttributes?: FeatureAttributes;
  /** Optional Go1 portal URL, used for login purposes if no `oneTimeToken` is provided */
  portalURL?: string;
  /** Optional function that is invoked when the Go1 content view emits a message */
  onGo1MessageReceived?: OnGo1MessageReceived;
  /** Optional end user information that can enhance the context and provide a better experience. No PII is needed, please do not send any. */
  additionalUserInfo?: AdditionalUserInfo;
  /** Optional UI configuration */
  themeInformation?: ThemeInformation | ThemeModeInformation;
  /** Optional one time token that is used to pre-authorize the user without them needing to log in */
  oneTimeToken?: string;
  /** Optional OAuth token that is used to pre-authorize the user without them needing to log in */
  accessToken?: string;
  /** Optional Id that let us know which integration system users are coming from (will be required in the future)*/
  integrationSystemId?: string;
  /** Optional Id that let us know which integration system users are coming from, if using an intermediary system to embed */
  presentingIntegrationSystemId?: string;
   /** Optional flag to control JWT persistence in browser storage, if false, JWT will not be stored in localStorage, sessionStorage, or cookies */
  persistJWT?: boolean;
}
```

`content-hub` 将会在未来的一次大释放中被移除 使用 `admin-curation` 为了新的融合。 现有 `content-hub` 请求是: 重定向服务器侧到 `admin-curation` 。在折旧窗口中.

`ai-chat` 将会在未来的一次大释放中被移除 使用 `discovery-agent` 为了新的融合.

## 函数 : `useGo1ContentView`

返回的反应钩

-   `sendMessageToGo1`: 允许您向 Go1 内容视图发送消息的函数
-   `ContentView`: 一个使 Go1 内容视图的反应组件

```typescript
function useGo1ContentView(options: InitOptions): {
  sendMessageToGo1: SendMessageToGo1;
  ContentView: () => React.JSX.Element;
};
```

### 使用量

```typescript
const onGo1MessageReceived = useCallback((message) => {
  console.log('Received postMessage from Go1');
  console.log(message);
}, []);

const options = useMemo<ContentViewProps>(() => {
  return {
    feature: 'ai-chat',
    portalURL: 'learning-incorporated-usa.mygo1.com',
    featureAttributes: {
      shouldSuppressShareLink: true,
    },
    persistJWT: false,
    onGo1MessageReceived,
    additionalUserInfo: {
      jobTitle: 'Sales development representative',
    },
    themeInformation: {
      accent: '#0437F2',
      mode: 'dark',
    },
    oneTimeToken: '907687a6e81a458190fe4c21f05ee689',
    integrationSystemId: 'int_nI7rPykBRm0C',
  };
}, []);

const { sendMessageToGo1, ContentView } = useGo1ContentView(options);

// now to render the <ContentView>
```

## 函数 : `sendMessageToGo1`

向 Go1 内容视图发送消息 。 当一个事件在您的网站上开始时, 控制用户体验有用, Go1 内容视图需要意识到它( 并可能执行其他动作 - 这是 `feature` 依赖。)

其使用的例子如下:.

```typescript
function sendMessageToGo1(message: Go1Message): void;
```

### 使用量

```typescript
const message = {
  type: 'logout',
  payload: {},
};
sendMessageToGo1(message);
```

## 函数 : `onGo1MessageReceived`

对Go1内容视图中发生的事件做出回应. 用于控制 Go1 内容视图中的事件开始时的用户体验, 您的网站需要意识到它 .

### 使用量

```typescript
const onGo1MessageReceived = (message) => {
  switch (message.type) {
    case 'enrolment_created': {
      const { userId, courseId } = message.payload;
      // perform appropriate actions for when a new enrolment is created
      break;
    }
    case 'category_favourite_added': {
      const { userId, category } = message.payload;
      // perform appropriate actions for when a new category is favourited
      break;
    }
    default:
      break;
  }
};
```

### Go1 信件示例有效载荷

已添加到库中

```typescript
{
  "type": "library_content_added",
  "payload": {
    "id": "3510462",
    "action_type": "admin-add",
    "timestamp": "2026-06-16T02:13:45.123Z",
    "type": "lo",
    "lo_type": "course"
  }
}
```

已从图书馆删除项目

```typescript
{
  "type": "library_content_removed",
  "payload": {
    "id": "3510462",
    "action_type": "admin-remove",
    "timestamp": "2026-06-16T02:13:45.123Z",
    "type": "lo",
    "lo_type": "course"
  }
}
```

选中的库项目已经通过Message 导出

```typescript
{
  "type": "library_content_exported",
  "payload": {
    "items": [
      { "id": "3510462", "type": "lo" },
      { "id": "3510463", "type": "lo" }
    ]
  }
}
```

项目书签动作是由学习者请求的,同时 `shouldSuppressBookmarkAction` 已启用

```typescript
{
  "type": "save_content",
  "payload": {
    "id": "3510462",
    "action_type": "learner-save",
    "timestamp": "2026-06-16T02:13:45.123Z",
    "type": "lo",
    "lo_type": "course"
  }
}
```

项目书签动作已被管理员请求, 而 `shouldSuppressBookmarkAction` 已启用

```typescript
{
  "type": "save_content",
  "payload": {
    "id": "3510462",
    "action_type": "admin-save",
    "timestamp": "2026-06-16T02:13:45.123Z",
    "type": "lo",
    "lo_type": "course"
  }
}
```

## 支助

[https://www.go1.com/developers (英语)](https://www.go1.com/developers)

## 常见问题

### @go1/go1-embedding-react-sdk 是什么？

一个将 Go1 内容嵌入您的网站的 React 库 \.

### 如何安装 @go1/go1-embedding-react-sdk？

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

### @go1/go1-embedding-react-sdk 支持 TypeScript 吗？

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

### @go1/go1-embedding-react-sdk 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @go1/go1-embedding-react-sdk 可以商用吗？

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

### @go1/go1-embedding-react-sdk 的下载量有多少？

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

### @go1/go1-embedding-react-sdk 还在维护吗？

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

