OpenMax
免费试用

打开方式与地址

Workspace 外壳怎么打开你的应用、平台链接怎么对应到应用地址、入口地址上的显示参数、路由同步,以及应用请求打开会话(navigate)。

打开方式与地址

这页讲 Workspace 外壳怎么打开你的应用:平台链接和应用地址怎么对应、嵌入(iframe)需要你做什么、外壳会带哪些参数和消息,以及应用怎么把当前页同步给外壳、怎么请求打开一个会话。

地址规则与打开方式

  • 地址规则:
    • 官方 / 全局应用:/workspace/apps/{slug}(如 /workspace/apps/pages)。
    • 组织应用:/workspace/apps/custom/{id}。id 是首次发布时生成的 {slug}-{4 位随机字符}(slug 取 manifest 里的 slug;4 位为小写字母 + 数字,不含 0 / o / 1 / l / i),如 leantime-k7mp。全局唯一,首次发布后永不改变,只用于定位,不代表权限。
  • 怎么打开:外壳校验安装状态和入口 roles 后,直接打开 {url}{子路径}。open 含 embed 时放进页内 iframe,否则给「新标签打开」链接。外壳不签发 code、不传身份;应用内路由就是子路径。打开时地址上会带两个显示参数(见「入口地址上的参数」)。
  • 子路径怎么选:平台链接 /workspace/apps/…/{子路径} 先按「完全相同 → 落在某个可见入口之下的最长者(/ 兜住一切深链接)」选入口;都不中时回落到首个可见入口(优先 /)。这时打开的是回落入口本身,不把用户看不到的地址带给应用。
  • embed 打不开时:顶栏一直有「页面空白?」(等于新标签打开),10 秒未加载会提示改用新标签。

要支持 embed,你的应用需要

  • CSP:写 frame-ancestors 允许 Workspace,并去掉 X-Frame-Options: DENY。

    Workspace origin(frame-ancestors / issuer):https://openmax.com。

  • cookie:iframe 里你的 cookie 是第三方 cookie。登录流程 cookie 和会话 cookie 都要 Secure; HttpOnly; SameSite=None; Partitioned(顶层打开时可以用 Lax)。Safari 以及 iPhone / iPad 上的所有浏览器(WebKit)根本不存也不带这类 cookie,Partitioned 只有 Chromium 系认。所以嵌入时请改用登录「嵌入时登录」里的宿主代发授权码,不靠 cookie 登录,也不在 iframe 里跳转。

  • 会话不共享:带 Partitioned 的 cookie 按顶层站点分区。iframe 里建立的会话与新标签(顶层)里的会话互不共享,新标签首次打开会再走一次(无感的)授权,这是正常的。按登录「嵌入时登录」接入后,iframe 里的会话放在请求头里,同样与新标签互不共享。

  • iframe 属性:sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads"、referrerPolicy="no-referrer"、allow="clipboard-write"(应用拿不到 Referer,也不能导航顶层页)。新标签链接带 rel="noopener noreferrer"。

入口地址上的参数(只用于显示)

外壳每次把地址交出去(iframe src、顶栏 /「页面空白?」/ 10 秒提示 /「新标签打开」链接、应用目录卡片的新标签直链),都会在 query 上设置:

参数 取值 含义
theme light / dark Workspace 解析后的主题(「跟随系统」已按系统偏好解析)
openmax_lang en / zh 当前界面语言(认不出时为 en)
  • 只有这两个:外壳不带 code、token、org_id、member_id 或任何身份信息;平台链接上用户自己带的 query 也不透传。
  • 只用于显示,绝不能用于鉴权:任何人都能改地址栏,所以不能拿它们判断「是从 OpenMax 打开的」、选组织 / 租户、跳过登录或决定权限。身份只来自登录的授权结果。
  • 同名参数会被覆盖:url 里自带的 query 不会带进入口地址(只拼路径)。应用的路由 / 登录中间件要能容忍这两个未知参数(不要因此 400 或丢会话)。
  • iframe 里按这一次打开冻结:之后用户切主题 / 语言不改 src(不重载应用),改为 postMessage 发 {type:"openmax:theme", mode} / {type:"openmax:lang", lang}(每次 iframe load 也各发一次)。应用可向 window.parent 发 openmax:theme:request / openmax:lang:request 让宿主再发一次。消息只发往 manifest url 的 origin,所以 url 必须是你的最终 origin(不能再 30x 到别的域名)。新标签链接每次都带当前值。
  • 跳授权回来会丢:应用自己跳授权再回来时,这两个参数会丢。先把它们存进你的会话 / 本地存储,或回来后用上面的 request 消息再要一次。

协议由 @openmaxai/app-sdk 封装。这个包还没发布到 npm(实验性 0.0.0 版本),可以自己实现:两个 query 参数 + 四种主题 / 语言消息;路由同步另有一种(见「路由同步」),请求打开会话另有三种(见「应用请求打开会话」),嵌入登录另有三种(见登录「嵌入时登录」)。

地址组合示例

拼接规则:

  • url 去掉末尾斜杠后 + / + 子路径各段(空段忽略)。
  • 子路径为 / 时,得到 url 路径本身加一个 /。
  • 子路径的末尾斜杠不保留。
  • 子路径含 . / .. 段、反斜杠、控制字符、解码后的 ? / # 时不打开(外壳报不可用)。

下表的 … 是 ?theme=light&openmax_lang=zh:

manifest url 用户打开的平台链接 外壳实际打开
https://pm.example.com/ /workspace/apps/custom/leantime-k7mp https://pm.example.com/…
https://pm.example.com/ …/custom/leantime-k7mp/projects/12 https://pm.example.com/projects/12…
https://example.com/leantime(无末尾斜杠) …/custom/leantime-k7mp https://example.com/leantime/…
https://example.com/leantime/ …/custom/leantime-k7mp/dashboard/ https://example.com/leantime/dashboard…(末尾斜杠被去掉)
https://example.com/leantime/?tenant=a …/custom/leantime-k7mp https://example.com/leantime/…(tenant=a 不带)
  • 前缀部署(应用挂在反向代理的子路径下,如 /leantime):应用自己生成的链接、重定向、静态资源、cookie Path 都要带这个前缀(例如配置应用的外部 base URL)。否则外壳打开的页面能出来,但第一次跳转就会丢前缀。外壳只保证打开的地址落在 url 的路径之下。
  • 路由对末尾斜杠敏感的应用(/dashboard 与 /dashboard/ 不同):入口 path 写成不带末尾斜杠的形式,并让应用接受它。
  • redirect_uri 是单独的一项,不受上面拼接规则影响,也不必是入口。如 url = https://example.com/leantime/ 时可以写 https://example.com/leantime/auth/openmax/callback。它的主机必须与 url 相同;授权请求里带的值、token 请求里带的值、manifest 里的值三者逐字节一致(/callback 与 /callback/ 是两个地址)。主机的其他限制见应用类型与 manifest「校验规则」。

路由同步(可选,推荐嵌入应用接入)

现状:已上线。

解决什么:嵌入的应用跑在跨源 iframe 里,外壳读不到你在 iframe 里跳到了哪一页。不接时,用户在应用里点进某页后刷新浏览器,外壳按地址栏里那条(进入时的)平台链接重新打开,iframe 回到入口页;地址栏复制出去的也只是入口。接了以后,外壳地址跟着应用走:刷新停在原页,地址栏就是当前页的链接,复制给同事能打开同一页(对方按自己的角色重新选入口,看不到就回落并提示,不越权)。

怎么接:每次换页(含首屏)向父窗口发一条消息,只发给 Workspace origin https://openmax.com,不要用 "*":

parent.postMessage({ type: "openmax:location", path: location.pathname }, "https://openmax.com");

用 @openmaxai/app-sdk 时等价于 connectWorkspace({ workspaceOrigin }).reportRoute()(缺省取 location.pathname;没嵌入、与上次相同、路径不合法时不发)。SDK 还没发布到 npm,可以直接用上面这一行。

项 规则
path 你的文档当前的 location.pathname,含你自己的部署前缀(manifest url 是 https://example.com/leantime/ 时发 /leantime/projects/12),前缀由外壳剥掉;你不需要知道自己的平台链接长什么样
格式 以单个 / 开头(//、/\、带协议的一律不收),≤ 2048 字符,不含 ?、#、反斜杠、控制字符、编码过的 / \ .(%2F %5C %2E),没有 . / .. 段
能还原 必须落在 manifest url 的路径之下,且按「地址组合示例」的规则拼回去就是这一页(末尾斜杠不计);空段(/a//b)这类拼不回去的不收
可见 必须落在当前用户可见的入口之下(按「地址规则与打开方式」选入口时不回落);落不进去的不收——写进地址反而制造一个「打开就回落」的链接
只同步路径 query 与 hash 不同步:外壳打开地址时本来就不透传 query,刷新只能还原到路径这一级。用 ?id= 区分详情页的应用,刷新会回到列表页;要恢复到详情,把 id 放进路径(/items/42)
来源 外壳只认来自你这个 iframe(event.source)、且 event.origin 等于 manifest url 的 origin 的消息——所以 url 必须是你的最终 origin
  • 不满足任一条,外壳静默忽略,地址停在上一次接受的那页,不回错误消息。外壳也不回 ack。
  • 外壳只用 history.replaceState 改自己的地址:不导航、不重载你的 iframe、不新增历史条目。你的 pushState 本身已在浏览器的会话历史里;用户按后退时你的路由回退,再发一次当前页(下面配方里的「每次换页都发」自然覆盖),外壳地址随之退回。
  • 外壳不会反过来驱动你导航:刷新 / 分享时外壳照「地址规则与打开方式」直接打开 {url}{子路径},你的应用要能直接从深层页面启动(深链路由、服务端渲染的页面本来就可以)。
  • 顶栏入口下拉:地址已跟到 /reports/42 时再选「Reports」,外壳会重新打开入口页(iframe 重载);你上报自己正停在某个入口页时,再选该入口不重载。
  • 外壳拒收了你最近一次上报(不可见入口之外的页、登录回调页、形状不合法等)时,按「位置未知」处理:再选当前入口会重新打开入口页。
  • 同一帧里连发多条,外壳只处理最后一条;同值不重写。

不要上报这些页面:OAuth 回调(redirect_uri)、登录中转、一次性确认页、提交成功页这类刷新后不能重放的路由。刷新会不带 query 地重放回调,应用报错。外壳拿不到你的 redirect_uri,替你拦不住,只能你自己排除。唯一的例外:写回后的平台链接里含 /auth/callback(原样或解码后,如 /auth/callback、/reports/auth/callback)的上报会被外壳忽略——那会被 Workspace 当成它自己的登录回调页、停止续期。不要依赖这一条,回调页仍要自己排除。

框架配方(都用 location.pathname,所以路由的 basename / base / basePath 自然带上):

// 公共部分
const workspace = connectWorkspace({ workspaceOrigin: WORKSPACE_ORIGIN });
const skip = (p) => p.startsWith("/auth/");   // 回调、登录中转等一次性路由

// React Router
const { pathname } = useLocation();
useEffect(() => { if (!skip(pathname)) workspace.reportRoute(); }, [pathname]);

// Vue Router
router.afterEach((to) => { if (!skip(to.path)) workspace.reportRoute(); });

// Next.js(App Router,client component)
const pathname = usePathname();
useEffect(() => { if (!skip(pathname)) workspace.reportRoute(); }, [pathname]);

// 服务端渲染的页面(每页一个文档):页面加载时发一次
if (!skip(location.pathname)) workspace.reportRoute();

不接会怎样:行为不变(刷新回到当前入口页)。外壳没有不靠应用的兜底:跨源 iframe 的地址受同源策略保护,SPA 内跳转父页面看不到任何事件。不想接又想刷新不丢页,只能应用自己在 sessionStorage 记当前页、启动时恢复——这属于应用自身实现,平台不承诺。

应用请求打开会话(navigate)

现状:即将上线。

嵌入的应用可以请宿主打开一个会话:和某个成员的私聊,或某个已有会话。比如在任务详情里放一个「找负责人聊」按钮。

请求:应用向父窗口发 openmax:navigate:request,只发给 Workspace origin:

// 打开和某个成员的私聊
parent.postMessage({
  type: "openmax:navigate:request",
  requestId: "req_01",
  target: { kind: "dm", memberId: "MEMBER_ID" }
}, "https://openmax.com");

// 打开某个会话
parent.postMessage({
  type: "openmax:navigate:request",
  requestId: "req_02",
  target: { kind: "conversation", conversationId: "CONVERSATION_ID" }
}, "https://openmax.com");

回复:宿主回 openmax:navigate:accepted 或 openmax:navigate:error。accepted 只表示宿主收到了请求,不保证会话一定打开了。

window.addEventListener("message", (event) => {
  if (event.source !== window.parent || event.origin !== "https://openmax.com") return;
  const { type } = event.data || {};
  if (type === "openmax:navigate:accepted") { /* 宿主收到了请求;不代表会话一定已打开 */ }
  if (type === "openmax:navigate:error") { /* 请求出错,按下面的错误码表处理 */ }
});
项 规则
target {kind: "dm", memberId} 或 {kind: "conversation", conversationId},二选一
id 格式 requestId、memberId、conversationId 都只能是 1~64 位 [A-Za-z0-9_-]
调用时机 必须在用户点击里调(由用户操作触发),不能在页面加载或定时器里自动发
限流 每个 iframe 60 秒最多 10 次;被拒的请求不计入;和授权请求(登录「嵌入时登录」)分开计
上下文 目前只打开会话,不能附带上下文
  • @openmaxai/app-sdk 里的写法是 openChat({ memberId })。这个包还没发布到 npm,请照上面的消息格式自己发 postMessage。
  • 上面代码里的 https://openmax.com 是 Workspace 的 origin。

错误码:openmax:navigate:error 带一个错误码;rate_limited 时可能还带 retryAfter(单位秒)。不认识的码按 failed 处理。

错误码 谁判的 含义 应用怎么做
invalid_request 宿主 请求格式不对(target 不是两种之一,或 id 格式不对) 修代码(开发期错误)
unsupported_target 宿主 宿主不支持这个 target 回落到应用自己的做法(比如提示用户去 OpenMax 里找这个会话),不重试
activation_required 宿主 不是由用户点击触发的 改成在点击处理里发;不要自动重试
rate_limited 宿主 太频繁(见上表「限流」);可能带 retryAfter 提示稍后再试;有 retryAfter 时不早于它再发
failed 宿主 其他失败(含不认识的码) 给用户提示