YunBa Android SDK API 手册

start

功能

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 模块中权限管理的动态密钥）

Code Example

YunBaManager.start(getApplicationContext());

subscribe

功能

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

Code Example

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());
       }

    }
  }
);

unsubscribe

功能

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

Code Example

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());
        }
    }
  }
);

publish

功能

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

Code Example

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 使用指南中的 获取消息发送者。

publish2

功能

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

Code Example

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 天

publishToAlias

功能

向用户 别名 对象发送消息，用于实现点对点的消息发送。

注：需要先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

Code Example

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 使用指南中的 获取消息发送者。

publish2ToAlias

功能

向用户别名对象发送消息，用于实现点对点的消息发送，此 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

Code Example

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 天

stop

功能

App 可以调用此函数来停止云巴服务，当服务被停止后，长连接断开，所有的 API 都会失效（包括 start API），该 API 可用于 停止接收任何消息；当需要重新连接服务时，必须调用resume。

函数原型

public static void stop(Context context)

参数说明

名称	类型	说明
context	Context	Android 应用上下文环境

Code Example

YunBaManager.stop(getApplicationContext());

resume

功能

App 可以调用此函数来恢复云巴服务，与stop()相对应。

函数原型

public static void resume(Context context)

参数说明

• context: Android 应用上下文环境。

Code Example

YunBaManager.resume(getApplicationContext());

isStopped

功能

App 可以调用此函数来查看云巴服务是否被停止。

函数原型

public static void isStopped(Context context)

参数说明

名称	类型	说明
context	Context	Android 应用上下文环境

Code Example

YunBaManager.isStopped(getApplicationContext());

setAlias

功能

App 可以调用此函数来绑定账号，用户名，同一应用（AppKey）下每个用户只能指定一个 别名。

函数原型

public static void setAlias(Context context, String alias, IMqttActionListener mqttAction)

参数说明

名称	类型	说明
context	Context	Android 应用上下文环境
alias	String	用户设置的别名信息，取值范围详见 参数说明
mqttAction	IMqttActionListener	成功会回调 onSuccess，失败回调 onFailure

Code Example

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());
             }
        }
    }
);

getAlias

功能

App 可以调用此函数来获取当前用户的 别名。

函数原型

public static void getAlias(Context context, IMqttActionListener mqttAction)

参数说明

名称	类型	说明
context	Context	Android 应用上下文环境
mqttAction	IMqttActionListener	成功会回调 onSuccess，失败回调 onFailure

Code Example

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());
             }
        }
    }
);

getTopicList

功能

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

Code Example

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());
             }
        }
    }
);

getAliasList

功能

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

Code Example

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());
             }
        }
    }
);

getState

功能

根据 别名 来获取用户的状态，如是否在线等信息。

函数原型

public static void getState(Context context, String alias, IMqttActionListener mqttAction)

参数说明

名称	类型	说明
context	Context	Android 应用上下文环境
alias	String	用户设置的别名信息，取值范围详见 参数说明
mqttAction	IMqttActionListener	成功会回调 onSuccess，失败回调 onFailure

Code Example

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());
             }
        }
    }
);

subscribePresence

功能

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

Code Example

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 监听状态变化的 AndroidManifest.xml 配置

<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>

自定义 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) {

                }
        }

unsubscribePresence

功能

与subscribePresence相对应，取消监听对应 Topic 下用户上、下线 及 订阅（或取消订阅）该频道的事件通知。

函数原型

public static void unsubscribePresence(Context context, String topic, IMqttActionListener mqttAction)

参数说明

名称	类型	说明
context	Context	Android 应用上下文环境
topic	String	App 订阅的 频道，取值范围详见 参数说明
mqttAction	IMqttActionListener	成功会回调 onSuccess，失败回调 onFailure

Code Example

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());
             }
        }
    }
);

report

功能

上报统计信息给云巴后台，用户可以自定义 action，调用这个 API 后，云巴后台会记录相应的 action 被触发的次数。开发者可以在后台查询（注：暂未开放查询）

函数原型

public static void report(Context context, String action, String data)

参数说明

名称	类型	说明
context	Context	Android 应用上下文环境
action	String	上报的操作
data	String	进行操作的 topic

Code Example

YunBaManager.report(context, action, data);