mona-runtime

mona 运行时

组件

Link

跳转组件，支持插件/应用间页面跳转

例子

import { Link } from '@bytedance/mona-runtime';

const Index = () => {
  return (
    <div>
      <Link to="/pages/home/index">navigate to home </Link>
    </div>
  );
};

export default Index;

参数说明

| 参数 | 说明 | 是否必填 | 类型 | 默认值 | | ---- | ---------------- | -------- | ------ | ------ | | to | 要跳转的页面路由 | 是 | string | - |

通用 API

navigateTo

路由跳转，跳转到新的页面

例子

import { navigateTo } from '@bytedance/mona-runtime';

navigateTo('/pages/home/index');

redirectTo

路由重定向，跳转并替换当前页面路由

例子

import { redirectTo } from '@bytedance/mona-runtime';

redirectTo('/pages/home/index');

飞鸽 API

飞鸽 API 分为两类

• 以onXXXX开头的监听类 API，该类 API 接受回调函数作为参数，当在飞鸽中相应事件发生时，飞鸽会调用传过来的回调函数。注意: 监听类的方法，只会记录最后一次监听的函数, 建议把监听的结果存入到全局变量。
• 非onXXXX开头的普通的 API，可以直接触发飞鸽中相应的动作

  注意：飞鸽 API 需要在开放平台中拥有相应的插件 API 权限包

addToInputBoxSafely

使用场景

复制信息到输入框，支持文字。

对应权限包

| 权限名称 | 所属权限包 | 所属权限组 | 权限描述 | | ------------------- | ---------- | ---------- | ---------- | | AddToInputBoxSafely | 端操作权限 | 端操作权限 | 端复制能力 |

入参

| 名称 | 类型 | 是否必填 | 描述 | | ------- | ---------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | success | Function | ❌ | 1. 用户未被拉黑   - 正在接待中 ，✅ 可复制   - 用户不在接待中，下列条件同时满足， ✅ 可复制     _ 客服非离线     _ 7 天内有会话     * 当前用户没有正在与其他客服对话 | | fail | ( error: { code: number, message: string } ) => void | ❌ | 复制失败 | | data | string | ✅ | 消息内容，length > 0 |

login

使用场景

获取当前客服登录态 token，通过开放接口换取当前飞鸽登录用户信息

对应权限包

| 权限名称 | 所属权限包 | 所属权限组 | 权限描述 | | -------- | ---------- | ---------- | ------------ | | Login | 端操作权限 | 端操作权限 | 飞鸽登录能力 |

入参

| 名称 | 类型 | 是否必填 | 描述 | | ------- | ---------------------------------------------------- | -------- | ---------------- | | success | ( res: { token: string; shopId: number } ) => void | ❌ | 获取登录态 token | | fail | ( error: { code: number; message: string } ) => void | ❌ | 获取失败 |

错误码

| 错误码 | 错误描述 | 排查 | | ------ | -------------------- | ------------------------------ | | -100 | 未知错误 | 可能主应用内部原因。 | | -101 | 缺参数、入参类型错误 | 检查入参类型 | | -102 | 无权限 | 无权限，到开放平台申请权限包 | | -103 | 应用不提供此能力 | 本身无此能力/ 应用未实现此功能 |

示例代码

import { pigeon } from '@bytedance/mona-runtime';

pigeon.login({
  success: token => {
    // 传输token到自己服务端换以取自己的登录态
  },
  fail: error => {
    console.log(error);
  }, // {code: -100, message: '未知错误'}
});

getInitInfo

使用场景

应用初始化时获取信息。

对应权限

| 权限名称 | 所属权限包 | 所属权限组 | 权限描述 | 对应参数 | | ---------------------- | ------------ | ---------- | -------- | --------------------- | | UserID | 用户数据权限 | 端数据权限 | 用户 ID | user_id | | ShopID | 店铺数据权限 | 端数据权限 | 店铺 ID | shop_id | | CustomsServiceNo | 客服数据权限 | 端数据权限 | 客服编号 | customer_service_id | | CustomsServiceNickName | 客服数据权限 | 端数据权限 | 客服昵称 | customer_service_name |

入参

| 名称 | 类型 | 是否必填 | 描述 | | ------- | ---------------------------------------------------- | -------- | ------------------------------ | | success | (data: InitInfo) => void | ❌ | 会将有权限的数据，透传给插件。 | | fail | ( error: { code: number, message: string } ) => void | ❌ | 获取数据失败 |

出参

错误码

| 错误码 | 错误描述 | 排查 | | ------ | ---------------- | ---------------------------------------------------- | | -100 | 未知错误 | ① 非飞鸽容器环境② 飞鸽内部原因，请咨询官方人员 | | -103 | 应用不提供此能力 | 本身无此能力/ 应用未实现此功能 |

示例代码

import { pigeon } from '@bytedance/mona-runtime';

pigeon.getInitInfo({
  success: data => {
    //  {
    //    user_id: '',
    //    customer_service_id '': ,
    //    customer_service_name: '',
    //    shop_id: ''
    //  }
    console.log(data);
  },
  fail: error => {
    console.log(error);
  }, // {code: -100, message: '未知错误'}
});

onCurrentCustomerChange

使用场景

监听用户改变，当切换飞鸽左侧的用户时，会触发该 API 回调。 没申请 user_id 权限包时，将不会监听到对应变化。

对应权限

| 权限名称 | 所属权限包 | 所属权限组 | 权限描述 | 对应参数 | | -------- | ------------ | ---------- | -------- | -------- | | UserID | 用户数据权限 | 端数据权限 | 用户 ID | user_id |

出参

| | 类型 | 含义 | | -------- | ----------------------------- | ----------- | | UserInfo | {user_id: string} | 用户 openid |

示例代码

import { pigeon } from '@bytedance/mona-runtime';

pigeon.onCurrentCustomerChange(data => {
  console.log(data);
  // {
  //   user_id: 'xxxxxxx',
  // }
});

onShow

使用场景

监听插件展示，当插件在飞鸽中前台展示时，会触发该 API 回调

• 自定义按钮跳转, 会携带部分参数。申请权限后，才会携带相应数据。

• 从 tab 点击进入

参数对应权限包

| 位置 | 入口 | 权限名称 | 所属权限包 | 所属权限组 | 权限描述 | 对应参数 | | ------ | ------------ | :---------: | :------------: | :--------: | :-------: | :-----------: | | 位置 1 | 售后单入口 | AfterSaleID | 售后单数据权限 | 端数据权限 | 售后单 ID | after_sale_id | | 位置 2 | 商品单入口 | SkuOrderID | 订单数据权限 | 端数据权限 | sku 单 ID | sku_order_id | | 位置 3 | 店铺单入口 | OrderID | 订单数据权限 | 端数据权限 | 订单 ID | order_id | | 位置 4 | 商品列表入口 | ProductID | 商品数据权限 | 端数据权限 | 商品 ID | product_id |

出参

| key | 类型 | 含义 | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | showFrom | 0 | 1 | 2 | 3 | 4 | 0：点击 tab 进入自定义按钮跳转1：店铺单进入 order_id2：商品单进入 sku_order_id3：售后单进入 after_sale_id4：商品列表进入 product_id | | query | interface InitInfo {order_id?: string;sku_order_id?: product_id;after_sale_id?: string;product_id?: string;} | 官方参数。申请权限后，自定义按钮跳转会携带位置对应参数。 | | extraData | Record<string,string> | 自定义按钮中配置的参数路径【飞鸽】-【客服管理】-【应用管理】- 【应用设置】-【非官方插件-设置】 |

示例代码

import { pigeon } from '@bytedance/mona-runtime';

pigeon.onShow(data => {
  console.log(data);
  // {
  //   showFrom: 0,
  //   query: {},
  //   extraData: {},
  // }
});

店铺装修 API

1.拉取ts声明

使用MaxSubAutoTypeWebpackPlugin插件，并在启动项目时便会自动拉取ts声明。

//webpack.config.js
const { MaxSubAutoTypeWebpackPlugin } = require("@bytedance/mona-plugin-events");

module.exports = {
  // ....
  plugins: [
    // ...
    new MaxSubAutoTypeWebpackPlugin(),
  ]
};
//运行webpack serve 获得代码提示

2.使用JsApi

import {max} from '@bytedance/mona-runtime';
//假设店铺端注册了getUserInfo以及getUserInfoSync两个方法
//调用同步getUserInfoSync方法
let user=max.getUserInfoSync({userName:'kenny'});
//调用异步getUserInfo方法
max.getUserInfo({userName:kenny}).then(res=>{console.log(res)}).catch(err=>console.error(err))

3.注册装修组件端api

通过on或once前缀的方法调用，便可进行api注册

import {max} from '@bytedance/mona-runtime';
//同步方法注册
max.onShowSync((data)=>{},{isSync:true});
//异步方法注册
max.onShow((data)=>{});

//使用once，调用一次后自动注销api
//同步方法注册
max.onceShowSync((data)=>{},{isSync:true});
//异步方法注册
max.onceShow((data)=>{});

使用off前缀方法可对api进行手动移除

import {max} from '@bytedance/mona-runtime';
let listener=max.onShow((data)=>{});
max.offShow(listener);