首页卡片服务接口协议 v1

一、说明

为规范与指导轻应用提供首页卡片服务，特此制定《首页卡片服务接口协议》。

微哨首页卡片由轻应用提供数据接口API，微哨门户（App、微信企业号）根据API提供的数据进行卡片的展示。接口地址可在微哨管理平台进行配置。

二、接口要求

请求

首页卡片数据接口应支持HTTP GET请求。

参数

请求格式：http(s)://[API地址]?v=[version]&verify=[verify]&domain=[domain]&eb=[eb]

其中： | -------- | :----: | -------- | | domain |string | 所在教育局域名| | eb |string | 所在学校域名| | v | string |表示协议版本号 | | verify | string | 访问令牌，可用于通过微哨开放平台API获取用户信息 |

返回

首页卡片数据接口应返回JSON格式，示例：

{
  "meta": {
    "name": "一卡通", // 可选，卡片展示时默认使用应用名称
    "icon": "http://ecard.com/icon.png", // 可选，卡片展示时默认使用应用图标
    "template": "1"
  },
  "data": [
    item1, item2, ...
  ]
}

其中：

卡片的元信息通过meta字段返回，包括name（名称）、icon（图标）、template（卡片模板），卡片的具体数据通过data字段返回。data下的数据格式应与应用所选择的template对应，否则可能会无法解析。

目前，v1版本支持如下模板：

1、文字型

此类型卡片用于展示以文字信息为主的新闻、通知、公告等类型的应用。默认显示前4条数据，展开可显示最多8条数据。（样式可参见附图“校内通知”）

template = 1
item = {
  "title": "标题",
  "url": "http://abc.com/news/1", // 可选
  "time": 1488882500 // UNIX时间戳（秒）
}

2、图文型1

此类型卡片用于展示以图片+文字信息为主的新闻、通知、公告等类型的应用。默认显示前2条数据，展开可显示最多4条数据。（样式可参见附图“校内新闻”）

template = 2
item: {
  "title": "标题",
  "content": "内容内容内容",
  "image": "http://abc.com/news/1.png", // 可选，建议不为空。如果为空则会显示占位图标。
  "url": "http://abc.com/news/1" // 可选
}

3、图文型2

此类型卡片用于展示以图片+文字信息为主的新书、活动安排等类型的应用。可横向滑动显示最多10条数据。（样式可参见附图“新书”）

template = 3
item: {
  "title": "标题",
  "subtitle": "副标题",
  "image": "http://abc.com/news/1.png", // 可选，建议不为空。如果为空则会显示占位图标。
  "url": "http://abc.com/news/1" // 可选
}

4、表格类

此类型卡片用于展示课表、日程等表格类信息的应用。默认显示前7行数据，展开可显示最多14行数据。（样式可参见附图“课表查询”）

template = 4
item: {
  "columns": 3, // 每行列数，取值为1~4
  "data": [
    {
      "span": 3, // 可选，表示各单元格宽度，每项取值1~12，表示该单元格所跨越的列数（整体宽度等分12列）。
      "text": "第一行第一列",
      "color": "#0f0" // 可选，RGB格式颜色，表示text的颜色
    },
    ...
  ]
}

注：span如果设置，则在该行所有单元格中都应存在，且各单元格的span值相加应等于12，否则该行视为无效数据不予显示；如果未设置span值，则默认按照data所提供的列数均分。

5、数据类

此类型卡片用于展示以数据类为主（如一卡通、工资）的应用。默认可显示前3组数据，展开可显示最多6组数据。（样式可参见附图“校园一卡通”）

template = 5
item: {
  "title": "今日支出",
  "value": "-123",
  "color": "#f00" // 可选，RGB格式颜色，表示value的颜色
}