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 函数第二次.