连接ifi - 代理网络

这个模块为所有网络客户端,包括桌面集成平台,electronjs,和香草浏览器提供了Connefi代理的基本执行. 它会与任何 Connectifi 互通服务 端点并暴露一个被瞄准的FDC3 api. 默认情况下,代理将生成UX用于标准界面函数,如取色和意向解析等. 也可以是无头跑.

装入

在您的应用程序中安装模块 :

npm i @connectifi/agent-web

包含在您的捆绑中

import {createAgent} from '@connectifi/agent-web';

要绕过捆绑,您也可以从 unpkg.com 中加载代理并直接用作脚本模块 :

<script type="module" >
  import { createAgent } from "https://unpkg.com/@connectifi/agent-web/";

  createAgent(
        `https://[ME].connectifi.app`,
        `$[appName]@$[directoryName]`,
      )
      .then((fdc3) => {
          // do fdc3 things...
      });
</script>

使用量

该模块暴露出一个单一功能: 创建代理 返回一个以标准解决的承诺 FDC3 2.0 API (英语) (Desktop Agent)在成功连接到指定的接口服务后. 该函数需要3个参数:

• 间歇 - Connectifi服务的 URL 该应用程序的目标
• 应用 - FDC3应用软件 必须 格式为 应用程序Name@目录Name (见下文安全模式)
• 配置 - 代理的可选配置,包括下列道具:
  • 日志 - 用于记录代理输出的回调功能
  • 无头 - 无头模式运行代理的布尔旗(它只会连接并曝光FDC3 API)
  • 道具 - 为代理人配置UI的属性集合
    • 图标Src - 覆盖标志图像

说明: 如果您需要 FDC3 1.2 界面, 您可以使用 1.3.2版本 本单元.

简单创建示例

    const fdc3Session = await createAgent('https://platform.connectifi.app, 'myApp@myDirectory');

    //then use the standard FDC3 api
    const listener = await fdc3Session.addContextListener('fdc3.instrument', handleContext);

使用日志的示例

const logThat = (...params: any) => {
  console.log('logThat', ...params);
  const paramString = [...params].reduce((acc, p) => {
    acc += ` ${typeof p === 'object' ? JSON.stringify(p) : p}`;
    return acc;
  });
  const newLog = `${new Date().toISOString()} - ${paramString}`;
  setLogs((prevLogs) => [...prevLogs, newLog]);
};

const fdc3Session = await createAgent(
  'https://platform.connectictifi.app',
  'myApp@myDirectory',
  {logger: logThat}
);

//then use the standard FDC3 api...

设置自定义标志的示例

const fdc3Session = await createAgent(
  'https://platform.connectifi.app',
  'myApp@myDirectory',
  {
    props: {
      logoSrc: 'https://mylogo.png',
    },
  }
);

//then use the standard FDC3 api...

注释 : 如果设置自定义标识,如果该标识是:

• 超过 HTTPS
• 平方圆
• png 格式
• 透明背景的白色/ 灯光

与现有的FDC3模式相结合

通过FDC3 API的范围界定,Connectifi代理提供了典型的FDC3功能的超集. 支持桌面容器使用的FDC3全球模式也很简单.

创建 fdc3 全球对象

const fdc3Global = async () => {
  //create the agent and assign to the window
  window.fdc3 = await createAgent(
    'https://platform.connectifi.app',
    'myApp@myDirectory'
  );

  //fire the fdc3Ready event
  document.dispatchEvent(new CustomEvent('fdc3Ready', {}));
};

装入预装

使用上述代码,在任何以Electronjs为主的项目中将全球宣言作为预装脚本进行包装就简单了.

与 fdc3 全球实例连接

设置时 bridgeGlobal 配置旗为真,代理将与其环境中全球公布的FDC3对象相接. 沟通行为将:

• 如果一个连接系统/用户频道被加入或离开,桥将加入或离开同一id的全球系统/用户频道(如果存在的话)
• 如果通过当前连接的信道收到上下文, 桥将执行 fdc3.broadcast 在同样背景下的全球化问题
• 若为 raiseIntent 或者说 raiseIntentForContext 在Connefi范围内,代理也会从FDC3全球环境中获得相关的意向,并在解析器中显示为"本地"意向.

注释 : 这个特征是一个在进行中的工作,行为的细微变化将继续与支持在不同FDC3环境中的桥梁相伴而来.

自定义代理

Connectifi代理可以使用传入构造器的配置对象完全定制. 这个 代理图形 接口 :

export interface AgentConfig {
  props?: FabProps;
  headless?: boolean;
  logLevel?: LogLevel;
  bridgeGlobal?: boolean;
  logger?: (...params: any) => void;

  onFDC3Ready?: (fdc3: DesktopAgent) => void;
  onSessionStarted?: (directory: DirectoryProps, username?: string) => void;
  onSessionError?: (errorMessage: string) => void;
  onSessionAuthRequired?: (directory: DirectoryProps) => void;
  onSignedIn?: (username: string) => void;
  onSignedOut?: () => void;
  onChannelJoined?: (channelId: string) => void;
  onChannelLeft?: () => void;
  onConnected?: (initialConnect: boolean) => void;
  onDisconnected?: (nextConnect?: number) => void;
  onWorkingChanged?: (workInProgress: boolean) => void;
  handleIntentResolution?: (
    message: IntentResolutionMessage,
    callback: ResolveCallback,
    closeCallback: CloseCallback,
  ) => void;
  handleOpen?: (message: ConnectifiOpenMessage) => void;
}

• 道具
  • 这些是配置代理提供的默认 " FAB " UX 的 UI 特性( 参见 UI 推进 (见下文)
• 无头
  • 如果设置为 真实 - 代理商不会提供默认UI.
• 日志级别
  • 记录可以设置为“ 调试 ” 、“ info” 或“ silent”
• 全球桥梁
  • 实验特性: 如果设置为 真实 - 代理将附加在 window.fdc3 对象上(例如如果运行在桌面容器中), 并加入到其中, 以便意图解析和播放上下文 .
• 日志
  • 指定用于输出日志语句的自定义函数.

UI 推进

logoSrc?: string;
position?: ValidPositions;
loginStyle?: LoginStyles;

• 标志Src - 为 FAB 中显示的标志定义自定义位置
• 位置 - 'tl', 'ml', 'bl', 'r', 'm', 或 'br' 。 将 FAB 定位在屏幕的上、下、中、右/左/中.

UI 回调

  logger?: (...params: any) => void;
    
  onFDC3Ready?: (fdc3: DesktopAgent) => void;
  onSessionStarted?: (directory: DirectoryProps, username?: string) => void;
  onSessionError?: (errorMessage: string) => void;
  onSessionAuthRequired?: (directory: DirectoryProps) => void;
  onSignedIn?: (username: string) => void;
  onSignedOut?: () => void;
  onChannelJoined?: (channelId: string) => void;
  onChannelLeft?: () => void;
  onConnected?: (initialConnect: boolean) => void;
  onDisconnected?: (nextConnect?: number) => void;
  onWorkingChanged?: (workInProgress: boolean) => void;
  handleIntentResolution?: (
    message: IntentResolutionMessage,
    callback: ResolveCallback,
    closeCallback: CloseCallback,
  ) => void;
  handleOpen?: (message: ConnectifiOpenMessage) => void;

手提式自动解析

当一个模棱两可的意向结果列表被推向了应用程序,供终端用户解决时,就叫作这个. 调用后将获得IntentSecretMessage的数据结构,同时提供调用后调用(ResolveCallback),当一个用户在应用程序上选择了解决用意的调用.

export interface IntentResolutionMessage {
  resolutionType: ResolutionType;
  context: Context;
  data: AppIntentResult | AppIntentResult[];
  bridgeData?: AppIntent | AppIntent[];
}

意图解析信息具有以下属性:

• 分辨率Type - " intent-resolver " 或 " context-resolver " 取决于分辨率是否来自 意图 或者说 提高关联性 电话.
• 上下文 - FDC3 与意图相关的上下文对象
• 数据 - 单一结果(`intent-resolver'类型)或结果清单(`context-resolver')。 见 应用程序结果 见下文.
• bridgeData - 一个可选结果集,来自已桥接的 fdc3 全球背景( Desktop Agent) 如果 全球桥梁 属性设定为真实。 见 应用程序结果 见下文.

应用程序结果

export interface AppIntentResult {
  intent: IntentMetadata;
  apps: Array<ConnectifiAppMetadata>;
}

export interface ConnectifiAppMetadata extends AppMetadata {
  type: IntentResultType;
  id: string;
  url: string;
  instanceTitle: string;
  intents: Array<ConnectifiAppIntent>;
  proximity: number;
  useragent: string;
  browser?: string;
  device?: string;
  os?: string;
  lastUpdate: number;
}

AppIntentResult将标准FDC3 IntentMetadata类型与ConnectifiAppMetadata类型组合起来. (即意图与应用结果相匹配). 这个 连接ifiAppMetadata 数据 type 是标准 FDC3 AppMetadata 类型的扩展,它提供了一些额外的属性,用于帮助用户在应用程序间分解. 例如:

• 相近 - 从0开始 - 从启动解析器的应用程序中显示相对设备和应用相近的编号. 例如,如果目标应用在同一个设备上,并且运行在与发起者相同的应用程序(如Chrome)中,相近为0. 评分的用意是帮助对列表进行排序,顺序是最接近用户当前工作的后方的应用程序.
• 浏览器 - 应用程序运行中的浏览器类型指标
• 设备 - 应用程序运行的设备指示器
• os - 应用程序运行的OS 指示器
• 用户代理 - 应用程序的原始用户代理字符串

频道

加入频道时调用 。 争论是 编号 已连接.

频道左侧

离开时调用 CurrentChannel 执行 。 即用户离开当前频道但不加入另一个频道.

打开

后调用 fdc3. 打开 或者一个意图解决。 在此情况下,服务会向客户端发送信息,请求其启动特定应用. 消息格式如下:

export interface ConnectifiOpenMessage {
  name?: string;
  url?: string;
  pendingId: string;
}

何处 名称 是目录中应用程序的名称, url 密码 是启动的url(用于网络应用程序),以及 待决文件 是非ce,可以让新推出的应用程序检索任何预期意图/文本数据。 注:名称和url是可选的,取决于所推出的应用程序的类型.

一个典型的手柄 Open 看起来像这样:

const handleOpen = (message : ConnectifiOpenMessage ) => {
     if (data.url && data.pendingId) {
        window.open(data.url, data.pendingId as string);
      }
}

此处注意使用 待决文件 作为 名称 用于新窗口 - 这是 Agent 拾取的会话 - 它会自动使用窗口的名称来获取新应用程序的待处理状态 。 其他模式可以并且将会被用于非浏览器客户端. 另请注意,对于大多数浏览器 窗口。打开 电话必须足够接近最终用户点击工作。 因此,如果你正在构建没有机会让终端用户在应用程序启动前点击某个东西的工作流程 - 您需要在浏览器的流程中构建一些机制(向用户介绍链接等) .

工作报告草稿 已更改

代理开始或停止"工作"或"忙"时打电话. 布尔参数是当前状态.

签名

在用户成功签入目录后调用. 将传递用户名/ 标识符作为参数 .

已签名

用户签名后呼叫.

已连接

当套接字连接建立时调用 .

已断开

当套接字连接被丢弃时调用 。 将会通过自动重联时间(以毫秒计)作为参数.

会议开始

当连接ifi代理已建立与服务和目录的会话时调用 .

会议

当连接ifi代理无法为服务和目录建立会话时调用 。 错误消息会显示是哪个 。 这是一个致命的错误.

会议授权

当用户无法连接到目录时调用, 因为无法认证 。 传出目录名称作为参数.

错误

当用户无法连接到目录时调用, 因为无法认证 。 传出目录名称作为参数.

处理连接状态

Connectifi被设计为在包括移动设备在内的任何地方运行,其中连接中断是常见的. 该代理公司为缓解潜在的连接问题提供了一些工具.

自动重接

如果连接被丢弃,代理将自动管理重联. 在默认的 UI 中, Toast 也会向终端用户建议连接状态和任何再连接尝试.

连接出错

使用FDC3 2.0,所有FDC3 API都是Async. 与 Connectifi 连接, 任何 API 呼叫, 以类型错误拒绝连接 ConnectionError.NoConnectionAvailable。这个错误可以处理并用来触发对用户的通知、记录和/或关键事件的排队.

在Connect / 在断线回调中

以上概述的这些回调可以用来在连接状态周围创建自定义 UX. 注: 无法提供这些设备来管理重新连接的逻辑,因为代理商自己负责

警卫

代理机提供全码隔离,并自身安全连接回服务端. 一个代理连接到控制接口安全配置的目录 。 有3个基本安全级别:

• 打开 - 任何应用程序都可以连接到端点 - 这只推荐给开发.
• 应用 - 必须验证一个应用程序的身份并将其注册到目录上才能连接.
• 严格 - 应用程序的身份必须有效,属于目录,用户必须经过认证才能连接.

这一模式允许在参与互通的对应方不易受到偷窥、跨站点描述攻击和未经授权的应用程序进入桌面总线的数据泄漏时,提供强有力的安全.

解决问题

Connectifi是完全的网络,所以所有相同的工具和方法,你用来排除一个Webapp申请代理. 登录员回调还可以为检查和诊断客户端上的任何问题提供更大的灵活性. 一些基准项目需要检查是否与代理人有问题:

• 接口服务的 URL 是否正确 ?
• 您是否有正确的( 对大小写敏感) 和完全合格的 应用程序Name @ directoryName 您正在连接的目录的标识符 ?
• 您的应用程序在目录中注册了吗 ? 注册来源是否与您正在连接的来源相匹配 ?
• 你在用那个吗 FDC3 2.0 API (英语) 在你的应用程序?

下一步

如果你还没和康涅菲合作 我们想听听你的消息 请给我们留言 信息@ connectifi.co。 。 。 .

接下来我们给特工的路线图是:

• 本地客户端和语言支持
• 默认 UX 的更多改进
• UX 更大的配置性