@getsetup/embed

中文文档
2.2.5发布于 2025/03/26UNLICENSEDTypeScriptCommonJS零依赖近 30 天下载 2569

这个软件包是供GetSetUp的合作伙伴在其构建过程中使用. 它将使用 Iframes 将 GetSetUp 嵌入内容注入伴侣的网站.

中文使用文档
文档目录9 节
  1. 安装
  2. 版本
  3. 快速启动示例
  4. 使用软件包
  5. 选项
  6. 页面布局
  7. 脚本
  8. 链接模板
  9. 清理

GSU 嵌入壳

这个软件包是供GetSetUp的合作伙伴在其构建过程中使用. 它将使用 Iframes 将 GetSetUp 嵌入内容注入伴侣的网站.

安装

npm i @getsetup/embed

版本

此软件包随后 铸造。 。 。 .

快速启动示例

import * as GSU from '@getsetup/embed'

// Read partner id from query string or hardode it
const searchParams = new URLSearchParams() // Please feel free to use framework specific equivalent functions here for e.g. React has useSearchParams().
const partnerId = searchParams.get('partner-id') || 'gsu-demo'

// This function is supplied by the hosting page.
// They should preform any checking and sanitation they wish to here.
const navigationCallBack = ({
  navigationAction,
  classId,
  classSlug,
}: {
  navigationAction: GSU.NavigationAction
  classId?: string
  classSlug?: string
}) => {
  const targetUrl = new URL(window.location.href)
  // The 'watch' navigation action is special because we need to pass the classId to the 'watch' page.
  if (navigationAction === 'watch' && classId) {
    targetUrl.pathname = `/hostSitePath/watch/${classSlug ?? ''}`
    targetUrl.searchParams.set('class-id', classId ?? '')
  } else if (navigationAction === 'discover') {
    targetUrl.pathname = '/hostSitePath/discover'
    targetUrl.searchParams.set('partner-id', partnerId)
    targetUrl.searchParams.delete('class-id')
  }
  window.location.assign(targetUrl)
}

// Token exchange is handled on a case-by-case basis. Pass this if it's not to be implemented.
const tokenRequestCallBack = () => {}

GSU.createIframe({
  targetElementId: '--ID-OF-THE-TARGET-ELEMENT--',
  targetPage: 'discover', // or 'watch'
  partnerId,
  navigationCallBack,
  tokenRequestCallBack,
})

使用软件包

软件包暴露了一个功能: GSU.createIframe(options)。此功能将在主机页面中创建一个iframe,并创建所需的事件听众 postMessage 与iframe通讯.

选项

这个 GSU.createIframe 函数将一个选项对象作为其单一参数。 该选项对象的TypeScript接口如下:

export type TargetPage = 'discover' | 'watch'
export type NavigationAction = 'discover' | 'watch' | 'login' | 'home' | 'help'

export enum IframeStatus {
  LOADING = 'LOADING',
  SUCCESS = 'SUCCESS',
  ERROR = 'ERROR',
}
export interface IframeStatusMessage {
  /** The current status of the iframe. */
  status: IframeStatus
  /** A text message to inform developers or monitoring. This should not be shown to users. */
  message: string
}

export interface CreateIframeOptions {
  /** The children of this target element will be replaced with the iframe embedded GetSetUp content. */
  targetElementId: string

  /** Which GetSetUp Page to display in the iframe. */
  targetPage: TargetPage // "discover" | "watch"

  /** The id of the class to play. Required if the `targetPage` is `watch`. */
  classId?: string

  /** The id of your organisation as issued to you by GetSetUp. */
  partnerId?: string

  /** A flag for disabling the chat tab on the `watch` page. */
  disableChat?: boolean

  /** A flag for disabling the help link on the `watch` page. */
  disableHelp?: boolean

  /**
   * You should provide this optional function if you want to change the URL of the hosting page when the iframe needs to navigate.
   *
   * This function is called when the iframe needs to navigate the top level URL.
   * E.G: to go from `hostsite.com/online-classes/catalogue` to `hostsite.com/online-classes/watch-video/98hsfnb498ywh4`
   * @param navigationAction The page to navigate to. If this is `login` the parent page should start a login flow and redirect the user to the current page once they are logged in.
   * @param classId If the page is the watch page, then classId must be passed back to the createIframe function on the new page.
   * @param classSlug If the page is the watch page, then the classSlug will be sent to this callback. The classSlug is only for SEO use on the parent page, it is not required to be passed back to the createIframe function.
   *
   * If this function is not provided then the iframe will perform navigations internally without informing the parent page.
   */
  navigationCallBack?: ({
    navigationAction,
    classId,
    classSlug,
  }: {
    navigationAction: NavigationAction
    classId?: string
    classSlug?: string
  }) => void

  /**
   * This function is called when the iframe needs a token.
   * This will happen on page load and when the current token expires.
   * This function is optionally async, it can either return the token, or a promise that will resolve to the token.
   * @returns Either a JWE compact token that contains user identification or a promise that will resolve to the token. If no token is available then this function can return `null | undefined` or an empty promise. */
  tokenRequestCallBack?: () => Promise<string | null | undefined | void> | string | null | undefined | void

  /**
   * This is called by the iframe loading script when the status of the iframe changes. It is used to inform the page the embeds the iframe whether the iframe loaded successfully or not.
   * @param iframeStatusMessage An `IframeStatusMessage` containing a `status` and a `message` field.
   */
  statusCallBack?: (iframeStatusMessage: IframeStatusMessage) => void

  /**
   * Optional - Used to construct links inside the iframe that point to the hosting site. Navigation is still accomplished via the `navigationCallBack`.
   * These links just allow bots to crawl the content for better SEO. Only Supported on premium plans.
   *
   */
  linkTemplates?: {
    /**
     * This template should be the URL you wish the browse pages to link to on your site. The tokens `{classSlug}` and `{sessionId}` are replaced with their values.
     * For example: `https://example.com/classes/{classSlug}/{sessionId}` could become `https://example.com/classes/cooking-with-rice/83bas8dfba`.
     */
    joinClass?: string
    /**
     * This template should be the URL of the learn page on your site.
     * For example: `https://example.com/online-classes/learn/`.
     */
    learnPage?: string
    /**
     * This template should be the URL of the fitness page on your site.
     * For example: `https://example.com/online-classes/fitness/`.
     */
    fitnessPage?: string
    /**
     * This template should be the URL of the fitness page on your site.
     * For example: `https://example.com/online-classes/discover/`.
     */
    discoverPage?: string
    /**
     * This template should be the URL of the fitness page on your site.
     * For example: `https://example.com/online-classes/watch/`.
     */
    watchPage?: string
    /**
     * This template should be the URL of the watch live class page on your site.
     * For example: `https://example.com/online-classes/watch/live`.
     */
    watchLivePage?: string
  }

  /**
   * Optional - Allows the caller to override urls that will be loaded in the iframe. Used for testing.
   */
  targetUrls?: {
    discover: string
    watch: string
  }

  /**
   * Optional - Allows the caller to override the loading timeout that displays an error message if the iframe doesn't load in time.
   * This value is in milliseconds.
   */
  loadingTimeoutInMs?: number

  /**
   * A set of options to allow the caller to control the theme rendered inside the iframe.
   * More options will be added to this over time.
   */
  themeOptions?: {
    /** This image will be displayed in the side bar of the `joinClass` page. */
    logoUrl?: string
  }

  /** Information used to report analytics back to your organisation. */
  analyticsInfo?: {
    /** The domain of the site that is hosting the embed. */
    domain?: string
    /** A stable id for the device the user is using to access the parent page. */
    deviceId?: string
  }
}
  • targetElementId 主机页面上元素的ID. iframe将在该元素内被创建.

  • targetPage (REQUIRED):GetSetUp页面在iframe内部渲染. 一个 "discover" 或者说 "watch"。 。 。 .

  • classId (如果 targetPage 实值 watch:一个会被传递到联想类页面的字符串,以便它知道要播放什么视频.

  • partnerId 你的组织的ID字符串 是GetSetUp给你的 GetSetUp 用来调整内容与你的组织.

  • deviceId (选择): 这是用于分析的可选代号 将报告给你的组织.

  • disableChat (选择): 这是一个可选的旗子, 它将禁用聊天标签 watch 页 次.

  • disableHelp (选择): 这是一个可选的旗子, 它将禁用在 watch 页 次.

  • navigationCallBack (如果 targetPage 实值 discover | watch:这用于在主机站点的页面之间导航,从类列表到嵌入类视频的页面. 它被传递 navigationAction (单位:千美元)"discover" | "watch" | "login" | "home" | "help"如果 navigationAction="watch" 也可以通过 classId 财务报告和审定财务报表 classSlug 的类别。 托管地应酌情处理这些导航请求.

  • tokenRequestCallBack (选择): 此回调用于从主机页面获得一个符号. 此令牌用于聊天授权, 因此如果您已禁用聊天, 此回调是可选的, 否则需要此回调 。 这种回调在 Iframe 加载或当前符号过期时被调用. 回调必须返回用GetSetUp给你的公钥加密的加密的JWT(JWE). 或作为承诺中的一串 如果代号是Aync的话 如果无法找到任何令牌(例如用户没有登录到您的网站),您可以返回 null, (中文(简体) ), undefined,无void或承诺解决其中任何一种。 有关建造代币的详情如下: 脚本 节.

  • statusCallBack (选择): 这种回调在 Iframe 装入、 已装入或出错时被调用 。 传递到此函数的对象有: status (单位:千美元) message。这两个字段都是为了让开发者了解iframe正在做什么,不应向用户显示.

  • linkTemplates.joinClass (OPTIONAL):将用来构建从嵌入式浏览页面(learn, ifition)到嵌入相接类页面的页面的链接的URL模板. 这是提供给高级合伙人的可选便利 它不会影响仍然由 navigationCallBack相反,它提供了一个连接点,可以让bots爬来帮助SEO。 见 链接模板部分 更多信息. linkTemplates 是允许今后扩大这一概念的目标.

  • linkTemplates.learnPage (OPTIONAL):用于构建从一个嵌入式浏览页(例如健身)到学习页的链接的URL模板. 这是提供给高级合伙人的可选便利 它不会影响仍然由 navigationCallBack相反,它提供了一个连接点,可以让bots爬来帮助SEO。 见 链接模板部分 更多信息.

  • linkTemplates.fitnessPage (OPTIONAL):用于从一个嵌入式浏览页面(例如学习)到健身页面构建链接的URL模板. 这是提供给高级合伙人的可选便利 它不会影响仍然由 navigationCallBack相反,它提供了一个连接点,可以让bots爬来帮助SEO。 见 链接模板部分 更多信息.

  • linkTemplates.discoverPage (OPTIONAL):用于从一个嵌入式浏览页(ex. discovery)到SEO友好的url页面构建链接的URL模板. 这是提供给高级合伙人的可选便利 它不会影响仍然由 navigationCallBack相反,它提供了一个连接点,可以让bots爬来帮助SEO。 见 链接模板部分 更多信息.

  • linkTemplates.watchPage (OPTIONAL):用于构建从一个嵌入式监视页面到嵌入了监视类页面的链接的URL模板. 这是提供给高级合伙人的可选便利 它不会影响仍然由 navigationCallBack相反,它提供了一个连接点,可以让bots爬来帮助SEO。 见 链接模板部分 更多信息.

  • linkTemplates.watchLivePage (OPTIONAL):用于从一个嵌入式表活类页面到嵌入表活类页面的页面构建链接的URL模板. 这是提供给高级合伙人的可选便利 它不会影响仍然由 navigationCallBack相反,它提供了一个连接点,可以让bots爬来帮助SEO。 见 链接模板部分 更多信息.

  • targetUrls (OPTIONAL):允许调用者覆盖被嵌入的页面的urls. 用于测试,生产中不应要求这样做。 是该表单的对象 :

{
  learn: string
  fitness: string
  lobby: string
}
  • loadingTimeoutInMs (optional):允许呼叫者超越加载超时. 在此超时后, iframe 加载被标记为失败, 脚本向用户显示错误消息 。 如果在本地运行或在测试环境中运行,这会导致问题,因此呼叫者可以使用这个选项来设置一个需要的更长时间的超时. 建议您在生产时不要使用此选项.
  • themeOptions (optional):一组选项,允许呼叫者控制在iframe内所渲染出的主题. 随着时间的推移,将增加更多的选项.
  • analyticsInfo 用来向组织报告分析的信息.

导航动作

这个 navigationCallBack 已经通过 a navigationAction 参数是下列字符串之一:

  • "learn": 这表示用户想要浏览您嵌入 GetSetUp 的页面 学习 页 次 例如,用户点击了后面的按钮 加入类 页 次.
  • "fitness": 这表示用户想要浏览您嵌入 GetSetUp 的页面 适应性 页 次 例如,用户点击了后面的按钮 加入类 页 次.
  • "joinClass": 这表示用户想要浏览您嵌入 GetSetUp 的页面 加入类 页 次 当用户点击列表上的类时会发生这种情况 学习 或者说 适应性 页面,或者如果用户点击该页上的探索面板中推荐的类 加入类 页 次 在这种情况下 navigationCallBack 还将通过 sessionId 您必须返回创建Iframe函数,以确保为用户装入类,以及 classSlug 您可以在页面上构建一个漂亮的 URL 加入类。 。 。 .
  • "login":这表示用户想要使用嵌入式聊天体验于 加入类 而母页尚未提供可使用的符号 。 您应该引导用户浏览您的登录体验, 并且一旦认证后, 引导用户访问当前访问的页面 .
  • "home":这表示用户想浏览母站点的主页. 您应该酌情导航用户.
  • "help":这表明用户需要帮助. 这由母站点酌情处理. 您应该将用户导航到您的帮助页面, 或者在 iframe 上显示一个对话框, 或者对帮助请求的任何其他回应 , 对您的网站来说是有意义的 .
  • "discover": 这表示用户想要浏览您嵌入 GetSetUp 的页面 发现 页 次 例如,用户点击了后面的按钮 看着 页 次.
  • "watch": 这表示用户想要浏览您嵌入 GetSetUp 的页面 看着 页 次 当用户点击列表上的类时会发生这种情况 发现 页面,或者如果用户单击该页上的探索面板中的推荐类 看着 页 次 在这种情况下 navigationCallBack 还将通过 classId 您必须返回创建Iframe函数,以确保为用户装入类,以及 classSlug 您可以在页面上构建一个漂亮的 URL 看着。 。 。 .

页面布局

Iframe 创建时附有以下样式:

border: 'none';
width: 100%;
height: 100%;

浏览页面

浏览页面(目前是学习、健身和发现)的设计要占用尽可能多的横向空间。 浏览页面没有固定的宽度 。 您可以使用嵌入浏览页面的页面的横向布局来做任何你想做的. 浏览器iframe的高度由GetSetUp iframe脚本所控制. iframe会发送一个后Message事件,包码会听从,然后包码会设定iframe的高度,以匹配里面内容的teh高. 因此浏览页面的iframe高度可以任意高. 你不应该指望任何固定的高度 iframe.

观察页面

监视页的iframe旨在占据它给定的横向和纵向空间。 您应当设定包含iframe(由 targetElementId) (中文(简体) ).

例如,如果您想要 JUN Class iframe 占据整个浏览器窗口,您应该使用 :

overflow: hidden;
width: 100%;
height: 100vh;

或者,如果您想要将组合类框架装入一个较小的空间,以便允许页面上的其他内容,您可以使用以下样式来绘制包含的元素:

overflow: hidden;
width: 100%;
height: calc(100vh - 300px);

这将允许150px高元素在页面上下方的空间.

Watch iframes应该支持包含元素上的大部分宽度/高值,但我们不推荐小于(600px,300px)或(300px,600px)的值.

脚本

给 tokenRequestCallBack() 函数必须是 JSON 网络加密(JWE) 符号。 GetSetUp 将为您提供一个公用密钥, 作为 JSON 网络密钥( JWK) , 您将用来加密该令牌 .

符号应使用下列设置加密:

  • 备选案文 : RSA-OAEP-256
  • 环境 : A256GCM

该标志的有效载荷必须包含:

  • 子:指使对象. 这应该是一个稳定的用户代号,如果在分析报告中被送回来,你就能理解.
  • 是:指使的发行人。 这一定是 embeddingOrgId 这是GetSetUp发给你的.
  • (原始内容存档于2017-10-10). Aud: the suiters for the sord. 这一定是弦 getsetup。 。 。 .
  • exp: 此令牌不再有效的时间戳 。 这是一个JSON数字值,代表从1970-01-01T00:00Z UTC起的秒数. 见 在 RFC7519 中执行 编辑 同一 RFC 格式的数值

托肯刷新

GetSetUp 聊天体验将使用符号过期时间(exp),以确定何时检查出一个新的符号. 聊天体验将使用 tokenRequestCallBack 30秒后 信物就过期了 如果聊天体验收到一个无效的符号,它将继续使用它现有的有效符号直到过期.

聊天体验将一个地平板放在一个符号可以有效的最小时间长度上. 如果信使有效时间不到一分,聊天体验会视信使有效时间为一分. 这样做是为了防止DOSing GetSetup的配置错误,或通过 tokenRequestCallBack,带有立即到期的符号的母页.

当令牌过期时,用户将会从聊天体验中被登录出,并且需要点击一个按钮来再次启动登录流. 聊天体验不会在收到无效的会令后自动重试以获得有效的会令牌.

使用 jose npm 软件包数字 :

const publicKey = {
  /* JWK given to you by GetSetUp. */
}

const token = new jose.EncryptJWT({})
  .setProtectedHeader({ alg: 'RSA-OAEP-256', enc: 'A256GCM' })
  .setIssuer('my-awesome-company') // Your embeddingOrgId
  .setAudience('getsetup')
  .setSubject('ssd8y34bn87sfgh') // The userId
  .setExpirationTime('10m') // Expire 10 minutes from now.
  .encrypt(publicKey)

linkTemplates 是允许今后扩大这一概念的一个目标,但只有 joinClass, (中文(简体) ), learnPage, (中文(简体) ), fitnessPage, (中文(简体) ), discoverPage 财务报告和审定财务报表 watchPage 链接模板目前得到支持.

链接模板是传递到 GSU.createIframe 函数为字符串。 如果字符串中存在, 符号 {classSlug} 财务报告和审定财务报表 {classId} 被他们的价值观所取代.

这一方案旨在让溢价伙伴能够控制其网站上的链接。 页面之间的导航由 NavigationActions 传到 导航 回电。链接模板允许溢价合伙人控制嵌入式学习和健身页面显示的链接格式.

例如,设想网站实例.com被嵌入了GetSetUp的页面. 例.com使用基于路径的url格式,并主机为 GetSetUp 健身页面 example.com/classes/fitness. example.com 主机连接类页面 example.com/watch 与类弹道和类代号相通,例如. example.com/watch/cooking-with-rice/wdf80h32b。为了在他们的网站上实现可爬行的链接,example.com 应该通过一个链接 https://example.com/watch/{classSlug}/{classId}。 。 。 .

如果实例.com使用查询字符串在嵌入式页面之间进行路由,那么他们的URL可能看起来是这样: example.com/watch?class-id=wdf80h32b 在这种情况下,他们 linkTemplate 应: example.com/watch?class-id={classId}。 。 。 .

请注意:

  • Link 模板上没有预先设置的清醒度检查,它是100%由集成伙伴控制.
  • 如果您在不同页面上需要不同的 URL, 那么您可以提供不同的 linkTemplate这些页面上的s.
  • 只有象征 {classSlug} 财务报告和审定财务报表 {classId} 支持在 linkTemplates. 其他一切将保持不变.

清理

这个 GSU.createIframe 函数返回 a GSU.IframeInstance 具有下列接口的对象:

export interface IframeInstance {
  cleanUp: () => void
}

在此对象上的清除功能将取消飞行计时器中的任何一项,并删除GetSetUp内容与这个软件包之间通信所需的事件倾听器. 你应该保留一个参考 GSU.IframeInstance 对象,并在调用 GSU.createIframe 函数第二次.

版本与发布记录

@getsetup/embed 共发布 37 个版本,首次发布于 2023/06/23;过去 12 个月发布了 0 个版本。

版本发布日期距今
2.2.5latest2025/03/261.6 年前
2.2.32025/01/151.8 年前
2.2.22024/10/012 年前
2.2.02024/06/252 年前
2.1.02024/04/042 年前
2.1.0-v2.1.0-alpha-10-2024-04-03T024730.203Z-1677039beta2024/04/032 年前

关于 @getsetup/embed 的常见问题

@getsetup/embed 是什么?

这个软件包是供GetSetUp的合作伙伴在其构建过程中使用. 它将使用 Iframes 将 GetSetUp 嵌入内容注入伴侣的网站.

如何安装 @getsetup/embed?

在项目目录运行 npm install @getsetup/embed,或使用 pnpm add / yarn add / bun add。

@getsetup/embed 支持 TypeScript 吗?

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

@getsetup/embed 支持 ESM 还是 CommonJS?

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

@getsetup/embed 可以商用吗?

@getsetup/embed 使用 UNLICENSED 许可。作者声明为 UNLICENSED,即不授予公开使用许可(与公共领域的 Unlicense 不同)。使用前需获得作者授权。以上为概括,不构成法律意见,请以许可原文为准。

@getsetup/embed 的下载量有多少?

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

@getsetup/embed 还在维护吗?

最新版本 2.2.5 发布于 2025/03/26(1.6 年前);至今共发布 37 个版本,其中过去 12 个月发布了 0 个;首次发布于 2023/06/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。