版本记录:

版权声明:
©2020爱为物联保留所有权利。未经爱为物联书面授权，严禁将本文档的全部或部分内容用于印刷或制作电子文档。

本文档中包含的信息仅供爱为物联人员、设备的授权用户以及获得爱为物联授权的人员使用，严禁用于其他用途。本文档信息如有更改，恕不另行通知。

商标声明:
Ivyiot™和爱为物联标志是爱为物联的注册商标和服务标志。其他产品、品牌或服务名称是其各自所有者的商标或服务标志。未经爱为物联书面许可，严禁复制、展示或使用其商标或服务标志。

参考文件:
爱为物联不负责提供本文档中随设备引用的所有文档。爱为物联保留决定随产品和服务提供哪些文档的权利。

1. 简介

1.1 文档介绍

本文档介绍了Ivy消息推送对接流程及详细接口对接明细，以便商户集成对接，从而实现客户消息推送服务。

1.2 适用人群

本文档专为需要接入IVY平台的产品、开发、测试等相关人员编写。

2. 流程说明

2.1 前置条件

A. 客户若存在账号系统，请先完成以下流程对接：

• 基于《【账号授权】IVY单点登陆API》对接影子账号获取AccessToken和RefreshToken。
• 使用AccessToken基于《【通用API】IVY云存储API》对接设备管理相关API。

B. 客户不存在账号系统，请先完成以下流程对接：

• 基于《【账号授权】IVY账号授权接口》对接爱为账号系统获取AccessToken和RefreshToken。
• 使用AccessToken基于《【通用API】IVY云存储API》对接设备管理相关API。

2.2 对接流程

2.2.1 消息推送到APP

流程详解：

1. APP调用云端接口获取推送Url和Tag，将其写入IPC配置。
2. APP验证APNS或FCM可达性，调用云端登陆接口。
3. 设备推送消息到云端，云端根据当前用户登陆的终端列表，推送消息。
4. 若用户在终端设备中登出账号，则需要调用IVY云端的登出接口，后续不再收到消息推送。
   

2.2.2 消息推送到云

流程详解：

1. APP调用云端接口获取推送Url和Tag，将其写入IPC配置。
2. 客户开发接受IVY消息接口，给到爱为对接。
3. 设备推送消息到云端，云端根据客户给到的接口下发消息给客户云。客户自行实现消息推送或手机短信等业务。
   

消息返回示例

{
"msg_type": 1,   //消息类型
"title": "One Key to Call", //消息标题
"description": "F10:F10 detected One Key to Call at 00:00!", //消息描述内容
"mac": "44B295A2862C", //设备mac地址
"msgId": 2197686294, //消息ID，唯一
"msgTime": 1556435279//设备消息推送时间
"saveTime": 1556435279 //服务器消息保存时间
}

消息内容

消息类型msg_type

3 接口实现

3.1 IVY接口

HOST_BIZ、HOST_PUSHFEP、signKey请联系爱为相关人员获取

3.1.1 基础子服务信息查询

接口描述:

• 查询用户子服务信息,对于一个用户所返回的数据是固定的,用户只要查询一次即可

请求URL:

• https://{HOST_BIZ}/gateway?service=center.getServerInfo

请求方式:

• GET

请求头:

• 无

请求参数:

返回示例:

{
    "errorCode":"",
    "data":{
        "userId":111111,
        "subtoken":"subtoken",
        "area":"NA",
        "tag":"tag",
        "storeTag":"storeTag",
        "alexaTag":"alexaTag",
        "sendMsgUrl":"sendMsgUrl",
        "sendMsgUrlSecure":"sendMsgUrlSecure",
        "url":"url",
        "storeUrl":"storeUrl",
        "alexaUrl":"alexaUrl",
        "channelCount":0
    }
}

返回参数说明:

错误码说明:

3.1.2 APNS登陆

接口描述:

• APNS登陆

请求URL:

• https://{HOST_PUSHFEP}/apns_login

请求方式:

• POST

请求头:

• 无

请求参数:

返回示例:

{
    "errorCode": "",
    "failureDetails": "ok"
}

返回参数说明:

3.1.3 FCM登陆

接口描述:

• FCM登陆

请求URL:

• https://{HOST_PUSHFEP}/FCM_login

请求方式:

• POST

请求头:

• 无

请求参数:

返回示例:

{
    "errorCode": "",
    "failureDetails": "ok"
}

返回参数说明:

3.1.4 极光登陆

接口描述:

• FCM登陆

请求URL:

• https://{HOST_PUSHFEP}/jpush_login

请求方式:

• POST

请求头:

• 无

请求参数:

返回示例:

{
    "errorCode": "",
    "failureDetails": "ok"
}

返回参数说明:

3.1.5 APNS登出

接口描述:

• APNS登出

请求URL:

• https://{HOST_PUSHFEP}/apns_logout

请求方式:

• POST

请求头:

• 无

请求参数:

返回示例:

{
    "errorCode": "",
    "failureDetails": "ok"
}

返回参数说明:

3.1.6 FCM登出

接口描述:

• FCM登出

请求URL:

• https://{HOST_PUSHFEP}/FCM_logout

请求方式:

• POST

请求头:

• 无

请求参数:

返回示例:

{
    "errorCode": "",
    "failureDetails": "ok"
}

返回参数说明:

3.1.7 极光登出

接口描述:

• APNS登出

请求URL:

• https://{HOST_PUSHFEP}/jpush_logout

请求方式:

• POST

请求头:

• 无

请求参数:

返回示例:

{
    "errorCode": "",
    "failureDetails": "ok"
}

返回参数说明:

3.1.8 查询所有设备的最近报警消息

接口描述:

• 查询所有设备的最近的一组报警消息

请求URL:

• https://{HOST_PUSH}/push-msg/queryDevicesLatest

请求方式:

• GET

请求头:

• 无

请求参数:

返回示例:

{
    "errorCode": "",
    "data": {
        "minMsgNum": 100,
        "msgList": []
    }
}

返回参数说明:

3.1.9 查询设备报警推送开关

接口描述:

• 查询设备报警推送开关

请求URL:

• https://{HOST_PUSH}/push/subscribe_status

请求方式:

• GET

请求头:

• 无

请求参数:

返回示例:

{
    "errorCode": "",
    "data": [
        {
            "ipcMac": "A0ECA78ED37C",
            "tag": "02c7b864bd744c7e96a79fac457a371c",
            "subscribed": true
        }
    ]
}

返回参数说明:

3.1.10 打开设备报警推送开关

接口描述:

• 打开设备报警推送开关, app可收到来自设备的报警信息

请求URL:

• https://{HOST_PUSH}/push/open

请求方式:

• POST

请求头:

• 无

请求参数:

返回示例:

{
    "errorCode": ""
}

返回参数说明:

3.1.11 关闭设备报警推送开关

接口描述:

• 关闭设备报警推送开关,App将无法收到来自设备的报警

请求URL:

• https://{HOST_PUSH}/push/close

请求方式:

• POST

请求头:

• 无

请求参数:

返回示例:

{
    "errorCode": ""
}

返回参数说明:

3.2 客户接口

3.2.1 接收推送信息接口

接口描述:

• 消息推送服务器方式接入必须实现此接口
• IVY服务使用此 API来推送消息到商户服务器。
• 发起者： IVY服务
• 接受者： 商户服务端

请求URL:

• 自定义（但需要给到我司，参考：/notify/receiveMsg）

请求方式:

• POST

请求头:

请求Body:【详细参照2.2.2 消息推送到云返回示例】

{
    "msg_type":1,
    "title":"One Key to Call",
    "description":"F10:F10 detected One Key to Call at 00:00!",
    "mac":"44B295A2862C",
    "msgId":2197686294,
    "msgTime":1556435279,
    "saveTime":1556435279
}

响应状态码:

• 200 请求成功
• 401 请求失败

返回示例:

正确时返回:

Response Code： 200
Response Body：
{
    "errorCode":"",
    "failureDetails":""
}

失败时返回:

Response Code： 401
Response Body：
{
    "failureDetails":"token is invalid",
    "errorCode":"xxxxxx"
}

返回参数说明:

错误码说明:

• 无