@corto-ai/整合信使

@corto-ai/integrations-messenger 为主机应用程序和嵌入式集成之间的通信提供消息服务.

此软件包目前处于早期开发阶段并正在被发布到npm,以支持内部/dev工作流程.

预定用途

这个软件包的用意是为团队在CORTO平台上添加应用程序(例如基于iframe的集成).

状态

• 早期发展
• API 在 dev 发布之间可能更改
• 文件将逐步扩充

安装

npm install @corto-ai/integrations-messenger

能力

• 握手身份( I) - 每一个窗口(主机或集成)都有独特的注册 id. Nested 窗口自动与他们的家长握手,这样在任何动作发出前双方都知道他们和谁说话.
• 原始消息检查 - 一旦握手完成,特定来源的信息只有在来自在握手期间观察到的源头时才会被接受,防止来自出乎意料的源头的信息.
• 请求/答复行动 -- 为以下动作打入的助手,每个助手都有: send{{Action}} (呼叫方)和 handle{{Action}} (执行方)一收到匹配的响应就解决的对子.
• 流程/pubsub通知 - 基于频道的通知动作,可以反复发送或处理,有助于随着时间的推移推动多个更新,而不是单一的请求/答复.
• 跨嵌入式框架自动转发 - 如果一个窗口没有为动作注册的处理器,则消息会自动向上/向下传输到iframe树上,所以多层次的嵌入不需要每个关卡来执行每个动作.
• 可选调试日志 - 通过 withLogging: true 改为 init 在整合时记录握手和向控制台传递活动.

使用量

初始化

每个使用此软件包的窗口 -- -- 主机和嵌入式集成都一样 -- -- 必须调用 init 第一条:

import messenger from '@corto-ai/integrations-messenger';

await messenger.init({ id: 'my-integration-app' });

• id 需要并且必须是窗口调用的唯一 init。 。 。 .
• parentRef 是可选的,默认为 window.parent。只有在页面没有与其直接父端通信的情况下,才会覆盖它.
• withLogging 可选,并允许控制台日志用于调试握手/留言流.
• 如果窗口被嵌入( 它) parentRef 没有 window 本身, init 还踢出与父母的握手. init 一旦设置完成,就解决;与父手握手会同步完成.

在 Iframe 中嵌入集成物的主机应用程序也必须调用 registerChild 并提到iframe的 contentWindow 和同样的 id 儿童传给 init数字 :

messenger.registerChild(iframe.contentWindow, 'my-integration-app');

registerChild 听听那个孩子的握手声 一旦完成就决定了 在Iframe自己之前叫它吧 init 呼叫运行,否则握手可能会被错过.

行动

messenger.actions 所有支持的实体/流动的行动都影响到:

全体 matter, (中文(简体) ), contact,以及 settings 动作接受可选 newTab 显示主机的旗帜应在新标签中打开目标,以及 matter 动作还接受可选 matterId 超越上面所说的.

对于每项行动 send... 函数用于嵌入式集成调用,请主机应用程序执行一些动作或返回一些数据。 匹配 handle... 函数意在由主机应用程序执行:它注册一个接收请求的回调,并返回要发送的回调.

// in the host application
await messenger.init({ id: 'host' });

messenger.registerChild(iframe.contentWindow, 'child');

messenger.actions.matter.handleOpenChatSession(async ({ matterId, sessionId }) => {
  try {
    await someService.openSession(matterId, sessionId);
    return { success: true };
  } catch (err) {
    return { success: false, error: err.message };
  }
});

// in the embedded integration
await messenger.init({ id: 'child' });

const response = await messenger.actions.matter.sendOpenChatSession({
  matterId: '123',
  sessionId: 'abc'
});

if (response.success) {
  // happy path
} else {
  // sad path
}

流动( pubsub)

pubsub 通知与其他行动不同:而不是一次以单一答复解决, sendNotificationRequest 财务报告和审定财务报表 handleNotificationRequest 能够多次为同一人发回电 channel,两个都用 remove() 函数以停止监听.

// listen for notifications on a channel
const handle = messenger.actions.pubsub.sendNotificationRequest({ channel: 'documents' }, (notification) => {
  console.log('received', notification.data);
});

// later, stop listening
handle.remove();

const statusHandle = messenger.actions.pubsub.sendStatusRequest(({ status }) => {
  console.log(status);
});

statusHandle.remove();

模块通信

如上文所述 window.sendOpenModal 命令允许集成触发模式上覆并显示其应用程序中的自定义模式。 值得一提的是,这一新模式 无法与父应用程序联系相反,Modals应与其兄弟之间的融合(即打开模式的融合)通过 广播频道API。这样,他们就可以通知兄弟们可能需要的用户互动,包括关闭模式.

转发

为了支持多层次的iframe筑巢,包内固有的有一个"前向"的机械师:对于任何动作,如果在给定的窗口中没有定义处理器,则消息会继续上下到iframe树上取. 这是默认启用的, 不需要选入 .

在孩子应用程序中添加处理器可以阴影同一动作在父应用程序中的处理,因为只有在处理器没有定义时才会转发. 如果你不确定你是否应该为某个动作执行一个处理器,不要——让它转发给主机.

演示仓库

我们已经建立了一个 演示仓库 作为如何使用此软件包的例子.

发展

这个库由CORTO维护,并作为常规软件包发布工作流程的一部分发布.

详情请访问 https://www.docorto.ai 互联网档案馆的存檔,存档日期2011-12-02。 。 。 .

许可证

许可证细节将记录在这一软件包向稳定释放方向移动时.