App 初始化 YunBa SDK。
public static void start(Context context)
public static void start(Context context, String appkey)
public static void start(Context context, String appkey, Map opts)
名称 | 类型 | 说明 |
---|---|---|
context | Context | Android 应用上下文环境 |
appkey | String | YunBa 中注册的 AppKey,如果用户已经在 AndroidManifest.xml 定义了 YUNBA_APPKEY,此处的设置是无效的。 |
opts | Map | 选项,可包含 sub_key (用于获取订阅权限的密钥),pub_key (用于获取发布权限的密钥),sec_key (用于获取管理权限的密钥,切勿外泄),auth_key (用于 access manager 模块中权限管理的动态密钥) |
YunBaManager.start(getApplicationContext());
App 可以订阅
一个或者多个 频道(Topic),以接收来自频道的消息。
public static void subscribe(Context context, String topic, IMqttActionListener mqttAction)
public static void subscribe(Context context, String[] topics, IMqttActionListener mqttAction)
名称 | 类型 | 说明 |
---|---|---|
context | Context | Android 应用上下文环境 |
topic | String | App 订阅的 频道,取值范围详见 参数说明 |
topics | String[] | App 订阅的频道数组列表,取值范围详见 参数说明 |
mqttAction | IMqttActionListener | 成功会回调 onSuccess,失败回调 onFailure |
YunBaManager.subscribe(getApplicationContext(),topic,
new IMqttActionListener() {
@Override
public void onSuccess(IMqttToken asyncActionToken) {
String topic = DemoUtil.join(asyncActionToken.getTopics(), ",");
DemoUtil.showToast( "Subscribe succeed : " + topic, getApplicationContext());
}
@Override
public void onFailure(IMqttToken asyncActionToken, Throwable exception) {
if (exception instanceof MqttException) {
MqttException ex = (MqttException)exception;
String msg = "Subscribe failed with error code : " + ex.getReasonCode();
DemoUtil.showToast(msg, getApplicationContext());
}
}
}
);
App 可以取消订阅
一个或者多个 频道(Topic),以取消接收来自频道的消息。
public static void unsubscribe(Context context, String topic, IMqttActionListener mqttAction)
public static void unsubscribe(Context context, String[] topics, IMqttActionListener mqttAction)
名称 | 类型 | 说明 |
---|---|---|
context | Context | Android 应用上下文环境 |
topic | String | App 订阅的 频道,取值范围详见 参数说明 |
topics | String[] | App 订阅的频道数组列表,取值范围详见 参数说明 |
mqttAction | IMqttActionListener | 成功会回调 onSuccess,失败回调 onFailure |
YunBaManager.unsubscribe(getApplicationContext(), topic,
new IMqttActionListener() {
@Override
public void onSuccess(IMqttToken asyncActionToken) {
String topic = DemoUtil.join(asyncActionToken.getTopics(), ",");
DemoUtil.showToast( "UnSubscribe succeed : " + topic, getApplicationContext());
}
@Override
public void onFailure(IMqttToken asyncActionToken,Throwable exception) {
if (exception instanceof MqttException) {
MqttException ex = (MqttException)exception;
String msg = "unSubscribe failed with error code : " + ex.getReasonCode();
DemoUtil.showToast(msg, getApplicationContext());
}
}
}
);
App 可以向 Topic 发送消息,那么同一应用(AppKey)下任何subscribe
(订阅)此 Topic 的 Client 都会接收到消息。
注:需自定义 Receiver 接收 Publish 消息,可参考 Android SDK 快速入门。
public static void publish(Context context, String topic, String message,IMqttActionListener mqttAction)
名称 | 类型 | 说明 |
---|---|---|
context | Context | Android 应用上下文环境 |
topic | String | App 订阅的 频道,取值范围详见 参数说明 |
message | String | 向目标 topic 的订阅者发布的消息 |
mqttAction | IMqttActionListener | 成功会回调 onSuccess,失败回调 onFailure |
YunBaManager.publish(getApplicationContext(), topic, msg,
new IMqttActionListener() {
@Override
public void onSuccess(IMqttToken asyncActionToken) {
String topic = DemoUtil.join(asyncActionToken.getTopics(), ", ");
String msgLog = "Publish succeed : " + topic;
DemoUtil.showToast(msgLog, getApplicationContext());
}
@Override
public void onFailure(IMqttToken asyncActionToken, Throwable exception) {
if (exception instanceof MqttException) {
MqttException ex = (MqttException)exception;
String msg = "publish failed with error code : " + ex.getReasonCode();
DemoUtil.showToast(msg, getApplicationContext());
}
}
}
);
注:如果需要在接收消息时获取发送者 Alias,可在发送时将 Alias 封装到 Message。可参考 YunBa Android SDK 使用指南中的 获取消息发送者。
App 可以向 Topic 发送消息,那么同一应用(AppKey)下任何subscribe
(订阅)此 Topic 的 Client 都会接收到消息,此 API 可以带有其他参数,如 APN 选项等。
注:需自定义 Receiver 接收 Publish 消息,可参考 Android SDK 快速入门
public static void publish2(Context context, String topic, String message, JSONObject opts, IMqttActionListener mqttAction)
名称 | 类型 | 说明 |
---|---|---|
context | Context | Android 应用上下文环境 |
topic | String | App 订阅的 频道,取值范围详见 参数说明 |
message | String | 向目标 topic 的订阅者发布的消息 |
opts | JSONObject | 向目标 topic 的订阅者发布的消息的选项:如消息有效时间,目标平台,APNs 等等 |
mqttAction | IMqttActionListener | 成功会回调 onSuccess,失败回调 onFailure |
JSONObject opts = new JSONObject();
JSONObject apn_json = new JSONObject();
JSONObject aps = new JSONObject();
aps.put("sound", "bingbong.aiff");
aps.put("badge", 9);
aps.put("alert", "msg from android中文");
apn_json.put("aps", aps);
opts.put("apn_json", apn_json);
YunBaManager.publish2(getApplicationContext(), topic, msg, opts,
new IMqttActionListener() {
@Override
public void onSuccess(IMqttToken asyncActionToken) {
String topic = DemoUtil.join(asyncActionToken.getTopics(), ", ");
String msgLog = "Publish2 succeed : " + topic;
DemoUtil.showToast(msgLog, getApplicationContext());
}
@Override
public void onFailure(IMqttToken asyncActionToken, Throwable exception) {
if (exception instanceof MqttException) {
MqttException ex = (MqttException)exception;
String msg = "publish2 failed with error code : " + ex.getReasonCode();
DemoUtil.showToast(msg, getApplicationContext());
}
}
}
);
publish2
扩展参数 opts 是可选项,如果不填写参数,publish2
的行为与publish
相似(除了 apn_json 参数)。
名称 | 类型 | 说明 |
---|---|---|
qos | number | 如果不填,默认为 1,参数设置请参考 QoS |
apn_json | dict | 如果不填,则不会发送 iOS 端的 APNs 消息;而publish 会发送默认的 APNs 消息。APNs 具体可参考:Apple 官方文档 |
time_to_live | number | 离线消息 保留时间值,单位是秒(例如 2 天 2*24*3600),当前默认值为 3 天 |
向用户 别名 对象发送消息,用于实现点对点的消息发送。
注:需要先
setAlias
进行别名设置
public static void publishToAlias(Context context, String alias, String message,IMqttActionListener mqttAction)
名称 | 类型 | 说明 |
---|---|---|
context | Context | Android 应用上下文环境 |
alias | String | 用户设置的别名信息,同一 AppKey 下唯一,取值范围详见 参数说明 |
message | String | 向设置该目标别名的对象发布的消息 |
mqttAction | IMqttActionListener | 成功会回调 onSuccess,失败回调 onFailure |
YunBaManager.publishToAlias(getApplicationContext(), alias, msg,
new IMqttActionListener() {
@Override
public void onSuccess(IMqttToken asyncActionToken) {
String topic = DemoUtil.join(asyncActionToken.getTopics(), ", ");
String msgLog = "publish to alias succeed : " + topic;
DemoUtil.showToast(msgLog, getApplicationContext());
}
@Override
public void onFailure(IMqttToken asyncActionToken, Throwable exception) {
if (exception instanceof MqttException) {
MqttException ex = (MqttException)exception;
String msg = "publishToAlias failed with error code : " + ex.getReasonCode();
DemoUtil.showToast(msg, getApplicationContext());
}
}
}
);
注:如果需要在接收消息时获取发送者 Alias,可在发送时将 Alias 封装到 Message。可参考 YunBa Android SDK 使用指南中的 获取消息发送者。
向用户别名对象发送消息,用于实现点对点的消息发送,此 API 可以带有其他参数,如 APN 选项等。
注:需要先
setAlias
进行别名设置
public static void publish2ToAlias(Context context, String alias, String message, JSONObject opts, IMqttActionListener mqttAction)
名称 | 类型 | 说明 |
---|---|---|
context | Context | Android 应用上下文环境 |
alias | String | 用户设置的 别名 信息,同一 AppKey 下唯一,取值范围详见 参数说明 |
message | String | 向设置该目标别名的对象发布的消息 |
opts | JSONObject | 向设置该目标别名的对象发布的消息的选项:如消息有效时间,目标平台,APNs 参数等等 |
mqttAction | IMqttActionListener | 成功会回调 onSuccess,失败回调 onFailure |
JSONObject opts = new JSONObject();
JSONObject apn_json = new JSONObject();
JSONObject aps = new JSONObject();
aps.put("sound", "bingbong.aiff");
aps.put("badge", 9);
aps.put("alert", "msg from android中文");
apn_json.put("aps", aps);
opts.put("apn_json", apn_json);
YunBaManager.publish2ToAlias(getApplicationContext(), alias, msg, opts,
new IMqttActionListener() {
@Override
public void onSuccess(IMqttToken asyncActionToken) {
String topic = DemoUtil.join(asyncActionToken.getTopics(), ", ");
String msgLog = "publish2 to alias succeed : " + topic;
DemoUtil.showToast(msgLog, getApplicationContext());
}
@Override
public void onFailure(IMqttToken asyncActionToken, Throwable exception) {
if (exception instanceof MqttException) {
MqttException ex = (MqttException)exception;
String msg = "publish2ToAlias failed with error code : " + ex.getReasonCode();
DemoUtil.showToast(msg, getApplicationContext());
}
}
}
);
publish2ToAlias
扩展参数 opts 是可选项,如果不填写参数,publish2
的行为与publish
相似(除了 apn_json 参数)。
名称 | 类型 | 说明 |
---|---|---|
qos | number | 如果不填,默认为 1 ,参数设置请参考 QoS |
apn_json | dict | 如果不填,则不会发送 iOS 端的 APNs 消息;而publish 会发送默认的 APNs 消息。APNs 具体可参考:Apple 官方文档 |
time_to_live | number | 离线消息 保留时间值,单位是秒(例如 2 天 2*24*3600),当前默认值为 5 天 |
App 可以调用此函数来停止云巴服务,当服务被停止后,长连接断开,所有的 API 都会失效(包括 start API),该 API 可用于 停止接收任何消息;当需要重新连接服务时,必须调用resume
。
public static void stop(Context context)
名称 | 类型 | 说明 |
---|---|---|
context | Context | Android 应用上下文环境 |
YunBaManager.stop(getApplicationContext());
App 可以调用此函数来恢复云巴服务,与stop()
相对应。
public static void resume(Context context)
- context: Android 应用上下文环境。
YunBaManager.resume(getApplicationContext());
App 可以调用此函数来查看云巴服务是否被停止。
public static void isStopped(Context context)
名称 | 类型 | 说明 |
---|---|---|
context | Context | Android 应用上下文环境 |
YunBaManager.isStopped(getApplicationContext());
App 可以调用此函数来绑定账号,用户名,同一应用(AppKey)下每个用户只能指定一个 别名。
public static void setAlias(Context context, String alias, IMqttActionListener mqttAction)
名称 | 类型 | 说明 |
---|---|---|
context | Context | Android 应用上下文环境 |
alias | String | 用户设置的别名信息,取值范围详见 参数说明 |
mqttAction | IMqttActionListener | 成功会回调 onSuccess,失败回调 onFailure |
YunBaManager.setAlias(getApplicationContext(), alias,
new IMqttActionListener() {
@Override
public void onSuccess(IMqttToken asyncActionToken) {
DemoUtil.showToast("success", getApplicationContext());
}
@Override
public void onFailure(IMqttToken asyncActionToken, Throwable exception) {
if (exception instanceof MqttException) {
MqttException ex = (MqttException)exception;
String msg = "setAlias failed with error code : " + ex.getReasonCode();
DemoUtil.showToast(msg, getApplicationContext());
}
}
}
);
App 可以调用此函数来获取当前用户的 别名。
public static void getAlias(Context context, IMqttActionListener mqttAction)
名称 | 类型 | 说明 |
---|---|---|
context | Context | Android 应用上下文环境 |
mqttAction | IMqttActionListener | 成功会回调 onSuccess,失败回调 onFailure |
YunBaManager.getAlias(getApplicationContext(),
new IMqttActionListener() {
@Override
public void onSuccess(IMqttToken mqttToken) {
DemoUtil.showToast("get alias success " + mqttToken.getAlias(), getApplicationContext());
}
@Override
public void onFailure(IMqttToken asyncActionToken, Throwable exception) {
if (exception instanceof MqttException) {
MqttException ex = (MqttException)exception;
String msg = "getAlias failed with error code : " + ex.getReasonCode();
DemoUtil.showToast(msg, getApplicationContext());
}
}
}
);
App 可以查询用户订阅
的 频道 列表,如果不传入参数 alias,则是获取当前用户的频道列表,如果输入参数 alias,则是获取目标 alias 的频道列表。
public static void getTopicList(Context context, IMqttActionListener mqttAction)
public static void getTopicList(Context context, String alias, IMqttActionListener mqttAction)
名称 | 类型 | 说明 |
---|---|---|
context | Context | Android 应用上下文环境 |
alias | String | 用户设置的别名信息,取值范围详见 参数说明 |
mqttAction | IMqttActionListener | 成功会回调 onSuccess,失败回调 onFailure |
YunBaManager.getTopicList(getApplicationContext(),
new IMqttActionListener() {
@Override
public void onSuccess(IMqttToken mqttToken) {
JSONObject result = mqttToken.getResult();
try {
JSONArray topics = result.getJSONArray("topics");
System.out.println(topics.toString());
} catch (JSONException e) {
}
}
@Override
public void onFailure(IMqttToken asyncActionToken, Throwable exception) {
if (exception instanceof MqttException) {
MqttException ex = (MqttException)exception;
String msg = "getTopicList failed with error code : " + ex.getReasonCode();
DemoUtil.showToast(msg, getApplicationContext());
}
}
}
);
App 可以调用此函数来获取输入 Topic 下面所有订阅
用户的 别名。
public static void getAliasList(Context context, String topic, IMqttActionListener mqttAction)
public static void getAliasList(Context context, String topic, boolean disableState, boolean disableAlias, IMqttActionListener mqttAction)
名称 | 类型 | 说明 |
---|---|---|
context | Context | Android 应用上下文环境 |
topic | String | App 订阅的 频道,取值范围详见 参数说明 |
disableState | boolean | 结果是否排除别名状态信息 |
disableAlias | boolean | 结果是否排除别名列表 |
mqttAction | IMqttActionListener | 成功会回调 onSuccess,失败回调 onFailure |
YunBaManager.getAliasList(getApplicationContext(), "t1",
new IMqttActionListener() {
@Override
public void onSuccess(IMqttToken mqttToken) {
JSONObject result = mqttToken.getResult();
try {
JSONArray topics = result.getJSONArray("alias");
System.out.println(topics.toString());
} catch (JSONException e) {
}
}
@Override
public void onFailure(IMqttToken asyncActionToken, Throwable exception) {
if (exception instanceof MqttException) {
MqttException ex = (MqttException)exception;
String msg = "getAliasList failed with error code : " + ex.getReasonCode();
DemoUtil.showToast(msg, getApplicationContext());
}
}
}
);
根据 别名 来获取用户的状态,如是否在线等信息。
public static void getState(Context context, String alias, IMqttActionListener mqttAction)
名称 | 类型 | 说明 |
---|---|---|
context | Context | Android 应用上下文环境 |
alias | String | 用户设置的别名信息,取值范围详见 参数说明 |
mqttAction | IMqttActionListener | 成功会回调 onSuccess,失败回调 onFailure |
YunBaManager.getState(getApplicationContext(), "t1",
new IMqttActionListener() {
@Override
public void onSuccess(IMqttToken mqttToken) {
JSONObject result = mqttToken.getResult();
try {
String status = result.getString("status");
System.out.println("status = " + status);
} catch (JSONException e) {
}
}
@Override
public void onFailure(IMqttToken asyncActionToken, Throwable exception) {
if (exception instanceof MqttException) {
MqttException ex = (MqttException)exception;
String msg = "getState failed with error code : " + ex.getReasonCode();
DemoUtil.showToast(msg, getApplicationContext());
}
}
}
);
App 可以订阅某个频道上的用户的上、下线 及 订阅(或取消订阅)该频道的事件通知。所有用户的状态变化时都发起一个<action android:name="io.yunba.android.PRESENCE_RECEIVED_ACTION" />
的广播,用户 App 的程序监听此 action 的广播就能收到相应状态的变化通知。
public static void subscribePresence(Context context, String topic, IMqttActionListener mqttAction)
名称 | 类型 | 说明 |
---|---|---|
context | Context | Android 应用上下文环境 |
topic | String | App 订阅的 频道,取值范围详见 参数说明 |
mqttAction | IMqttActionListener | 成功会回调 onSuccess,失败回调 onFailure |
YunBaManager.subscribePresence(getApplicationContext(), "t1",
new IMqttActionListener() {
@Override
public void onSuccess(IMqttToken mqttToken) {
DemoUtil.showToast("subscribePresence to topic succeed", getApplicationContext());
}
@Override
public void onFailure(IMqttToken asyncActionToken, Throwable exception) {
if (exception instanceof MqttException) {
MqttException ex = (MqttException)exception;
String msg = "subscribePresence failed with error code : " + ex.getReasonCode();
DemoUtil.showToast(msg, getApplicationContext());
}
}
}
);
<receiver android:name="Your Receiver">
<intent-filter>
<action android:name="io.yunba.android.MESSAGE_RECEIVED_ACTION" />
<action android:name="io.yunba.android.PRESENCE_RECEIVED_ACTION" />
<category android:name="Package Name" />
</intent-filter>
</receiver>
else if(YunBaManager.PRESENCE_RECEIVED_ACTION.equals(intent.getAction())) {
//msg from presence.
String topic = intent.getStringExtra(YunBaManager.MQTT_TOPIC);
String payload = intent.getStringExtra(YunBaManager.MQTT_MSG);
try {
JSONObject res = new JSONObject(payload);
String action = res.optString("action", null);
String alias = res.optString("alias", null);
//process your code
} catch (JSONException e) {
}
}
与subscribePresence
相对应,取消监听对应 Topic 下用户上、下线 及 订阅(或取消订阅)该频道的事件通知。
public static void unsubscribePresence(Context context, String topic, IMqttActionListener mqttAction)
名称 | 类型 | 说明 |
---|---|---|
context | Context | Android 应用上下文环境 |
topic | String | App 订阅的 频道,取值范围详见 参数说明 |
mqttAction | IMqttActionListener | 成功会回调 onSuccess,失败回调 onFailure |
YunBaManager.unsubscribePresence(getApplicationContext(), "t1",
new IMqttActionListener() {
@Override
public void onSuccess(IMqttToken mqttToken) {
String msg = "unsubscribePresence to topic succeed ";
DemoUtil.showToast(msg, getApplicationContext());
}
@Override
public void onFailure(IMqttToken asyncActionToken, Throwable exception) {
if (exception instanceof MqttException) {
MqttException ex = (MqttException)exception;
String msg = "unsubscribePresence failed with error code : " + ex.getReasonCode();
DemoUtil.showToast(msg, getApplicationContext());
}
}
}
);
上报统计信息给云巴后台,用户可以自定义 action,调用这个 API 后,云巴后台会记录相应的 action 被触发的次数。开发者可以在后台查询(注:暂未开放查询)
public static void report(Context context, String action, String data)
名称 | 类型 | 说明 |
---|---|---|
context | Context | Android 应用上下文环境 |
action | String | 上报的操作 |
data | String | 进行操作的 topic |
YunBaManager.report(context, action, data);