Yunba JavaScript SDK API 手册

Yunba

功能

创建 Yunba 实例。使用在云巴 Portal 上创建应用获取到的 AppKey 创建 Yunba 实例。

new Yunba(obj);

参数说明

名称	类型	说明
obj.server	String	参数可选。服务器的地址。
obj.port	Number	参数可选。服务器的端口。如果使用 SSL/TLS 方式进行连接，则`port`为`443`；否则，`port`为`3000`。
obj.appkey	String	参数必选。应用标识，即，用户在云巴 Portal 上创建应用获取到的 AppKey。

注：

如obj.server中未指定https://或http://，Socket.IO-Client 会根据当前页面的协议, 选择使用 https 或 http 进行连接。在这种情况下，用户需要注意选择合适的port。使用 SSL/TLS 方式进行连接，则port为443；否则，port为3000。
如果想使用 SSL/TLS 方式连接，则obj.server请填写https://sock.yunba.io、port使用443。
免费用户可以试用 RESTful 和 Socket.IO 的加密链路，实际生产使用需要付费。

代码示例

var yunba = new Yunba({server: 'http://sock.yunba.io', port: 3000, appkey: '567a4a754407a3cd028aaf6b'});

//使用 SSL/TLS 方式连接：
var yunba = new Yunba({server: 'https://sock.yunba.io', port: 443, appkey: '567a4a754407a3cd028aaf6b'});

注：上文给出的 AppKey 功能受限，仅供文档举例使用。

init

功能

与 Socket.IO 服务器建立连接。

基本使用

yunba.init(init_callback, reconnect_callback)

参数说明

名称	类型	说明
init_callback	Function	参数可选。通知 init 是否成功。参数 success: 成功返回 true，失败返回 false。
reconnect_callback	Function	参数可选。连接断开后，调用该回调重连。

代码示例

yunba.init(function (success) {
    if (success) {
        yunba.connect_by_customid(customid, callback) ...
    }
}, function () {
    yunba.connect_by_customid(customid, callback) ...
});

connect

功能

兼容旧版本接口，无法保存会话状态（包括离线消息、已订阅的频道和别名），推荐使用 connect_by_customid 代替。

在浏览器支持并开启 cookie 的情况下，会自动生成一个 uid 并保存到 cookie 中然后进行 connect_by_customid 连接，若不支持或没开启 cookie 则只会进行普通的 connect 连接。

注意：如果不使用 connect_by_customid 而使用不带 customid 的 connect，那对云巴来说每次连接的都是新用户，也就是客户端每次连接都会创建一个新的日活，

yunba init()实例初始化后，只表明与服务器建立了 socket 连接，还需要通过connect()方法（推荐使用connect_by_customid()）连接上消息服务器。连接上消息服务器后，才开始收发消息。

基本使用

yunba.connect(callback)

参数说明

名称	类型	说明
callback	Function	callback 的结构为 function (success, msg)，操作成功返回 success == true，失败返回 success == false 和 msg （错误信息）。

代码示例

yunba.connect(function (success, msg) {
    if (!success) {
        console.log(msg);
    }
});

connect_by_customid

功能

与connect()功能一致，不同的是此接口使用特定的会话 ID 进行连接，连接后的会话状态与上次连接一致（包括离线消息、已订阅的频道和别名）。

同时使用多个相同 customid 进行连接时只有一个连接是有效的。

注：customid 和 alias 没有任何关系，如果想通过 customid 发消息，还需要将 alias 设置为 customid。参见set_alias()。

基本使用

yunba.connect_by_customid(customid, callback)

参数说明

名称	类型	说明
customid	String	参数必选。自定义会话 ID。
callback	Function	callback 的结构为 function (success, msg, sessionid)，操作成功返回 success == true 和 sessionid，失败返回 success == false 和 msg （错误信息）。

代码示例

yunba.connect_by_customid('your_app_user_id', function (success, msg, sessionid) {
    if (success) {
        console.log(sessionid);
    } else {
        console.log(msg);
    }
});

disconnect

功能

与connect()相对，通过disconnect()可以断开与消息服务器的连接。

基本使用

msg.disconnect(cb)

参数说明

名称	类型	说明
cb	Function	参数可选。不管断开连接失败还是成功，都会回调此函数。传递回的参数有 success、msg。如果 success 值为 true 表示成功，否则表示失败。如果失败，则返回错误消息 msg。

代码示例

yunba.disconnect(function (success, msg) {
    if (!success) {
        console.log(msg);
    }
});

set_message_cb

功能

设置收到消息时调用的回调函数。

基本使用

yunba.set_message_cb(cb)

参数说明

名称	类型	说明
cb	Function	参数必选。通过该回调函数监听所订阅频道的推送消息。传递回来的参数 data 是一个 object，包含消息频道（data.topic）与消息内容（data.msg）。如果消息为 presence 消息，data 中会多一个 presence 字段，其中包含 action、alias 和 timestamp。

代码示例

yunba.set_message_cb(function (data) {
    console.log(data.topic);
    console.log(data.msg);
});

功能

增加订阅一个频道。成功订阅后，可以收到来自该频道的消息。新增订阅不会影响已有的订阅。

基本使用

yunba.subscribe(obj,cb)

参数说明

名称	类型	说明
obj.topic	String	参数必选。表示准备收听的频道，取值范围详见参数说明。
obj.qos	Number	参数可选。表示服务质量等级，有三种取值：“0”表示最多送达一次；“1”表示最少送达一次；“2”表示保证送达且仅送达一次。默认为“1”。详见 QoS 的说明。
cb	Function	回调的结构为 function (success, msg)，操作成功返回 success == true，失败返回 success == false 和 msg （错误信息）。

代码示例

yunba.subscribe({'topic': 'my_topic'}, function (success, msg) {
    if (!success) {
        console.log(msg);
    }
});

subscribe_presence

功能

监听某频道下所有用户的上、下线及订阅、取消订阅该频道的事件通知。调用成功后，可以收到所有用户的状态变化。

注意：subscribe_presence 只能监听已经设置了别名的客户端，未设置别名的客户端不会被监听。

参见云巴的实时在线。

基本使用

yunba.subscribe_presence(obj,cb)

参数说明

名称	类型	说明
obj.topic	String	参数必选。表示准备收听的频道，取值范围详见参数说明。
obj.qos	Number	参数可选。表示服务质量等级，有三种取值：“0”表示最多送达一次；“1”表示最少送达一次；“2”表示保证送达且仅送达一次。默认为“1”。详见 QoS 的说明。
cb	Function	callback 的结构为 function (success, msg)，操作成功返回 success == true，失败返回 success == false 和 msg （错误信息）。

代码示例

yunba.subscribe_presence({'topic': 'my_topic'}, function (success, msg) {
    if (!success) {
        console.log(msg);
    }
});

unsubscribe

功能

取消对某一个频道的收听。

基本使用

yunba.unsubscribe(obj,cb)

参数说明

名称	类型	说明
obj.topic	String	参数必选。表示准备取消收听的频道，取值范围详见参数说明。
cb	Function	callback 的结构为 function (success, msg)，操作成功返回 success == true，失败返回 success == false 和 msg （错误信息）。

代码示例

yunba.unsubscribe({'topic': 'my_topic'}, function (success, msg) {
    if (!success) {
        console.log(msg);
    }
});

unsubscribe_presence

功能

取消对某频道下所有用户上、下线及订阅、取消订阅该频道的事件通知的监听。

参见云巴的实时在线。

基本使用

yunba.unsubscribe_presence(obj,cb)

参数说明

名称	类型	说明
obj.topic	String	参数必选。表示准备取消收听的频道，取值范围详见参数说明。
cb	Function	callback 的结构为 function (success, msg)，操作成功返回 success == true，失败返回 success == false 和 msg （错误信息）。

代码示例

yunba.unsubscribe_presence({'topic': 'my_topic'}, function (success, msg) {
    if (!success) {
        console.log(msg);
    }
});

publish

功能

向某个频道发布消息。成功发布后，所有订阅此频道的客户端都会收到消息。

注：接收端需要先通过subscribe()订阅该频道。

基本使用

yunba.publish(obj,cb)

参数说明

名称	类型	说明
obj.topic	String	参数必选。表示目标频道，取值范围详见参数说明。
obj.msg	String	参数必选。表示消息体。
obj.messageId	String	消息 ID，64 位整型数转化成 String。发布消息时可以指定，如果不填，则由系统自动生成。
obj.qos	Number	参数可选。表示服务质量等级，有三种取值：“0”表示最多送达一次；“1”表示最少送达一次；“2”表示保证送达且仅送达一次。默认为“1”。详见 QoS 的说明。
cb	Function	callback 的结构为 function (success, msg)，操作成功返回 success == true，失败返回 success == false 和 msg （错误信息）。如果发送成功返回含有 messageId 的 msg，发送失败返回错误消息 msg。

代码示例

yunba.publish({'topic': 'my_topic', 'msg': 'test_message','messageId': 199900724, 'qos': 1}, function (success, msg) {
    if (!success) {
        console.log(msg);
    }
});

publish2

功能

publish()的升级版本，支持更多参数。

基本使用

yunba.publish2(obj,cb)

参数说明

名称	类型	说明
obj.topic	String	参数必选。表示目标频道，取值范围详见参数说明。
obj.msg	String	参数必选。表示消息体。
obj.opts	Dict	扩展参数。
cb	Function	callback 的结构为 function (success, msg)，操作成功返回 success == true，失败返回 success == false 和 msg （错误信息）。如果发送成功返回含有 messageId 的 msg，发送失败返回错误消息 msg。

扩展参数说明

publish2()与publish2_to_alias()的扩展参数都是可选项。如果不填写参数，则publish2()/publish2_to_alias()的行为与publish()/publish_to_alias()相似，只有一点不同：publish()/publish_to_alias()会发送默认的 APN，而publish2()/publish2_to_alias()如果不填写 apn_json，则不会发送 APN。

名称	类型	说明
qos	Number	服务质量等级。有三种取值：“0”表示最多送达一次；“1”表示最少送达一次；“2”表示保证送达且仅送达一次。默认为“1”。详见 QoS 的说明。
apn_json	Dict	如果不填，则不会发送 APN。 APN 参考：Apple 官方文档及云巴相关文档。
messageId	String	消息 ID，64 位整型数转化成 String。发布消息时可以指定，如果不填，则由系统自动生成。
time_to_live	Number	用来设置离线消息保留多久。单位为秒（例如，3600 代表 1 小时），默认值为 3 天，最大不超过 15 天。

代码示例

yunba.publish2({
    'topic': 'myTopic',
    'msg': 'publish2message',
    'opts': {
        'qos': 1,
        'time_to_live': 36000,
        'apn_json': {
            'aps': {'sound': 'bingbong.aiff', 'badge': 3, 'alert': 'yunba'}
        },
        'messageId': '11833652203486491113'
    }
}, cb)

publish_to_alias

功能

向某个别名发布消息。发布成功后，该别名的客户端会收到消息。用于实现点对点的消息发送。

注：接收方需要先通过setAlias()设置别名。

基本使用

yunba.publish_to_alias(obj, cb)

参数说明

名称	类型	说明
obj.alias	String	参数必选。表示目标别名，取值范围详见参数说明。
obj.msg	String	参数必选。表示消息体。
obj.messageId	String	消息 ID，64 位整型数转化成 String。发布消息时可以指定，如果不填，则由系统自动生成。
obj.qos	Number	参数可选。表示服务质量等级，有三种取值：“0”表示最多送达一次；“1”表示最少送达一次；“2”表示保证送达且仅送达一次。默认为“1”。详见 QoS 的说明。
cb	Function	callback 的结构为 function (success, msg)，操作成功返回 success == true，失败返回 success == false 和 msg （错误信息）。如果发送成功返回含有 messageId 的 msg，发送失败返回错误消息 msg。

代码示例

yunba.publish_to_alias({
    'alias': 'my_alias',
    'msg': 'test_message',
    'messageId': 199900724,
    'qos': 1
    }, function (success, msg) {
        if (!success) {
            console.log(msg);
        }
    });

publish2_to_alias

功能

publish_to_alias()的升级版本，支持更多参数。

注：接收方需要先通过setAlias()设置别名。

基本使用

yunba.publish2_to_alias(obj,cb)

参数说明

名称	类型	说明
obj.alias	String	参数必选。表示目标别名，取值范围详见参数说明。
obj.msg	String	参数必选。表示消息体。
obj.opts	Dict	扩展参数。
cb	Function	callback 的结构为 function (success, msg)，操作成功返回 success == true，失败返回 success == false 和 msg （错误信息）。如果发送成功返回含有 messageId 的 msg，发送失败返回错误消息 msg。

扩展参数说明

名称	类型	说明
qos	Number	服务质量等级。有三种取值：“0”表示最多送达一次；“1”表示最少送达一次；“2”表示保证送达且仅送达一次。默认为“1”。详见 QoS 的说明。
apn_json	Dict	如果不填，则不会发送 APN。 APN 参考：Apple 官方文档及云巴相关文档。
messageId	String	消息 ID，64 位整型数转化成 String。发布消息时可以指定，如果不填，则由系统自动生成。
time_to_live	Number	用来设置离线消息保留多久。单位为秒（例如，3600 代表 1 小时），默认值为 5 天，最大不超过 15 天。

代码示例

yunba.publish2_to_alias({
    'alias': 'myAlias',
    'msg': 'publish_2_alias_message',
    'opts': {
        'qos': 1,
        'time_to_live': 36000,
        'apn_json': {
            'aps': {'sound': 'bingbong.aiff', 'badge': 3, 'alert': 'yunba'}
        },
        'messageId': '11833652203486491113'
    }
}, cb)

set_alias

功能

用来设置用户名，即绑定账号。每个用户只能指定一个别名。

将set_alias()的alias参数设置为空字符串即可取消别名。

基本使用

yunba.set_alias(alias, cb);

参数说明

名称	类型	说明
obj.alias	String	参数必选。表示所指定的别名，取值范围详见参数说明。
cb	Function	参数可选。无论 alias 是否设置成功都会回调此函数。传递回的参数有 data。data.success 值为 true 表示 alias 设置成功，否则为失败。如果失败，则返回错误消息 data.msg。

代码示例

yunba.set_alias({'alias': 'my_alias'}, function (data) {
    if (!data.success) {
        console.log(data.msg);
    }
});

get_alias

功能

获取当前用户的别名。

基本使用

yunba.get_alias(cb);

参数说明

名称	类型	说明
cb	Function	传递回的参数 data.alias 为当前用户的别名。

yunba.get_alias(function(data) {
    console.log(data.alias);
});

get_state

功能

可以通过get_state()查看传入的用户别名的在线状态。

基本使用

yunba.get_state(alias,cb)

参数说明

名称	类型	说明
alias	String	参数必选。参数为要查询状态的 alias 名称，取值范围详见参数说明。
cb	Function	参数可选。无论查询结果如何都会回调此函数。传递回的参数有 success、data、data.messageId、error_msg。查询成功 success 为 true 否则为 false，data 表示在线状态，success 为 false 时 error_msg 有效。

代码示例

yunba.get_state(alias, function (data) {
    if (data.success) {
        console.log(data.data);
    } else {
        console.log(data.error_msg);
    }
});

get_topic_list

功能

查询用户订阅的频道列表。如果传入参数 alias，是获取目标用户（别名）的频道列表；如果不传入参数 alias，则是获取当前用户的频道列表。

基本使用

yunba.get_topic_list(alias, cb)

参数说明

名称	类型	说明
alias	String	用户设置的别名信息，取值范围详见参数说明。
cb	Function	无论查询结果如何都会回调此函数。传递回的参数有 success、data.topics、error_msg。查询成功 success 为 true，否则为 false。data.topics 为订阅的`topic`列表，类型 List，success 为 true 时有效。success 为 false 时 error_msg 有效。

代码示例

yunba.get_topic_list('my_alias', function (success, data) {
    if (success) {
        data.topics.forEach(function (topic) {
            console.log(topic);
        });
    } else {
        console.log(data.error_msg);
    }
});

get_alias_list

功能

通过调用此函数可以获取该 topic 下所有订阅用户的别名。

基本使用

yunba.get_alias_list(topic, cb)

参数说明

名称	类型	说明
topic	String	App 订阅的频道，取值范围详见参数说明。
cb	Function	无论查询结果如何都会回调此函数。传递回的参数有 success、data.alias、error_msg。查询成功 success 为 true，否则为 false。data.alias 为订阅的`alias`列表，类型 List，success 为 true 时有效。success 为 false 时 error_msg 有效。

代码示例

yunba.get_alias_list('my_topic', function (success, data) {
    if (success) {
        data.alias.forEach(function (alias) {
            console.log(alias);
        });
    } else {
        console.log(data.error_msg);
    }
});