打开方式与地址
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让宿主再发一次。消息只发往 manifesturl的 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 |
宿主 | 其他失败(含不认识的码) | 给用户提示 |
