/bridge

淘宝旅行客户端Hybrid桥协议

Primary LanguageHTML

Native2H5

mClient协议约定及优先级梳理 v0.1

Overview

  • H5 WebView特性方法
  • 客户端协议接口约定（握手通讯）
  • 客户端页面跳转及跳转拦截
  • 客户端唤醒（调研总结）
  • 降级方案（页面生存环境自适应）
面向Android和iOS的JS调用原理

  1. Android 通过桥（客户端暴露在WebView全局对象下的一个对象，内挂各种API方法）的方式进行调用，如window['Android_Bridge']['method'](JSON)。

  2. iOS通过自定义Scheme（如native://method?data=JSON）方式调用。

  3. 需要回调的接口需要将函数名称在调用时一并传给客户端，同时将回调函数通过唯一名称挂在全局，待客户端执行回调后移除该全局函数。

  4. 握手通讯，mclient初始化时发送ready消息，当客户端拦截到ready消息后返回Ok状态码，mclient拿到成功状态码后则认为初始化完成，否则将认为页面自身处在非客户端或者第三方WebView环境中进行执行降级逻辑处理。

mClient是为H5和客户端交互通讯而产生的一个中间件，即一个JavaScript的SDK。负责处理H5和客户端的方法调用、通信及H5页面自身的降级处理（非内嵌在客户端的情况）。

H5内嵌客户端需要借助WebView完成自身的展现和“存活”，H5自身由于权限有限，有些功能和特性需要借助客户端辅助提供一些属性和方法来实现。如设备蜂鸣、震动，网络类型的识别（2G/3G/Wifi等）相关特性，除此之外还有一些特有的事件（如点击back键，网络变化，电量报警等）。倘若WebView的功能能够足够完善，H5就能够更大的发挥其优势，就会有更大的用武之地。下面是参考借鉴PhoneGap所罗列的一些常用的属性、方法抑或事件（排序按照优先级由高到低，非必要的特性已经暂时从下表中去除）。

Storage

Objects:
  • localStorage
localStorage

开启本地存储特性

UserAgent

请参照规范格式设置WebView的UserAgent，避免页面进行设备适配时取不到该字段的值或者取到的信息不正确。

Connection

Properties
  • connection.type
Constants
  • Connection.UNKNOWN
  • Connection.ETHERNET
  • Connection.WIFI
  • Connection.CELL_2G
  • Connection.CELL_3G
  • Connection.CELL_4G
  • Connection.CELL
  • Connection.NONE
connection.type

获取当前用户网络环境类型，wifi/2G/3G, etc.

备注：mclient提供JavaScript钩子，通过钩子获取设备当前所处的网络环境及网络类型。iOS若在非Wifi网络环境下无法区分2G/3G状态，则默认认为是3G即可。

Notification

Methods:
  • alert
  • confirm
  • prompt
  • beep
  • vibrate
notification.alert

警告提示框

notification.confirm

确认提示框

notification.prompt

提示对话框

notification.beep

蜂鸣声

notification.vibrate

设备震动

Device

Properties:
  • name
  • mclient
  • platform
  • uuid
  • model
  • version
device.name

设备名称

device.mclient

当前所用mclient的版本号

device.platform

平台类型

device.uuid

设备全球唯一标识

device.model

设备信息

device.version

操作系统版本号

Events

按照优先级排序

  • backbutton
  • deviceready
  • online
  • offline
  • pause
  • resume
  • batterycritical
  • batterylow
  • batterystatus
  • menubutton
  • searchbutton
  • startcallbutton
  • endcallbutton
  • volumedownbutton
  • volumeupbutton
  • shake

Client

Properties:
  • version
client.version

客户端版本号

InAppBrowser

Methods:
  • window.open
window.open

Events:

  • loadstart
  • loadstop
  • loaderror
  • exit

页面跳转/拦截

跳转的页面类型：
  • 商品详情页
  • 系统登录框
  • 跳转到AppStore
  • 任意页面（如客户端首页）
跳转方式：
  • 协议约定方式
  • 客户端拦截（借鉴主站客户端方式，规则是否能做成可配置的更加灵活）

协议约定

下述为原有的协议约定（是否需要调整或者变更还待确定），如有改动或者新增请及时同步变更信息。

a. 单VIEW操作
方法名 说明 需要的参数名
open_system_browser 用浏览器打开url url
client_appstore_call 跳转到appstore url
set_browser_title 设置顶部title title
client_page_back 客户端页面回退（back到webview上一页） -
client_alert 警告提示框，要求客户端自定义风格 title, msg, ok_wording, callback
client_confirm 确认提示框，俩按钮的提示框 title, msg, ok_wording, cancle_wording, ok_callback, cancel_callback
get_client_info 获取客户端类型/版本信息 callback
get_client_location 获取客户端定位信息 callback, failback
show_loading 显示菊花
close_loading 关闭菊花
b. 多VIEW操作
方法名 说明 需要的参数名
open 跳转(进入)到下一个view url, param, callback
back 回退到上一个view args, callback
c. 通用操作
方法名 说明 需要的参数名
start_data_statistics 客户端埋点 control_type, control_name, args

注释：

  • control_type: 埋点类型，0为page, 1为button, etc.
  • control_name: 埋点名称，如1ActGoodsList.
  • args: 为了方便扩展灵活的附加参数对象。

降级方案

当“握手”信号检测不到响应时，即认为非客户端，按照H5页面逻辑处理。

统一封装

完善mClient形成统一的API接口供页面调用，针对客户端和H5自适应的逻辑处理应由mClient内部完成，业务方应当不需要关注。