融云广播推送开发指南

    概述

    依托融云在即时通讯领域深厚的技术积累及多年稳定可靠的消息推送服务能力,融云决定推出广播推送产品。融云广播推送服务产品重视对推送效果的数据真实性和公开透明,从可推送总人数到实际推送人数、Android / iOS 各自达到率和打开率,全面真实的数据反应,帮助您及时调整运营方案。

    客户端使用说明

    SDK 支持

    要求使用 2.3.8 及以上版本的融云 SDK,老版本用户需要先升级 SDK 版本后才能从使用。

    iOS 集成指南

    1、开发者在执行融云 SDK 初始化方法 init 后,可以调用 recordLaunchOptionsEvent 接口统计推送点击率,通过 getPushExtraFromLaunchOptions 接口获取推送的自定义附加信息。代码示例如下:

    - (BOOL)application:(UIApplication *)application
        didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
        //开发者自己的业务代码
    
        //初始化融云SDK
        [[RCIM sharedRCIM] initWithAppKey:RONGCLOUD_IM_APPKEY];
    
        //开发者自己的业务代码
    
       /**
       * 统计推送打开率
       */
      [[RCIMClient sharedRCIMClient] recordLaunchOptionsEvent:launchOptions];
    
      /**
       * 获取融云推送服务扩展字段
       * nil 表示该启动事件不包含来自融云的推送服务
       */
      NSDictionary *pushServiceData = [[RCIMClient sharedRCIMClient] getPushExtraFromLaunchOptions:launchOptions];
      if (pushServiceData) {
        NSLog(@"该启动事件包含来自融云的推送服务");
        for (id key in [pushServiceData allKeys]) {
          NSLog(@"%@", pushServiceData[key]);
        }
      } else {
          NSLog(@"该启动事件不包含来自融云的推送服务");
      }
    }
    

    2、收到远程推送后,可以调用 recordRemoteNotificationEvent 接口统计推送点击率,通过 getPushExtraFromRemoteNotification 接口获取推送的扩展字段。代码示例如下:

    - (void)application:(UIApplication *)application
        didReceiveRemoteNotification:(NSDictionary *)userInfo {
    
        /**
         * 统计推送打开率
         */
        [[RCIMClient sharedRCIMClient] recordRemoteNotificationEvent:userInfo];
    
        /**
         * 获取融云推送服务扩展字段
         * nil 表示该启动事件不包含来自融云的推送服务
         */
        NSDictionary *pushServiceData = [[RCIMClient sharedRCIMClient] getPushExtraFromRemoteNotification:userInfo];
        if (pushServiceData) {
            NSLog(@"该远程推送包含来自融云的推送服务");
            for (id key in [pushServiceData allKeys]) {
                NSLog(@"key = %@, value = %@", key, pushServiceData[key]);
            }
        } else {
            NSLog(@"该远程推送不包含来自融云的推送服务");
        }
    
    }
    

    Android 集成指南

    1、在 AndroidManifest.xml 文件里面,加上对应 push 统计消息的 url 过滤。以 TestPushActivity 为例如下:

    <activity
     android:name=“.activity.TestPushActivity"
     android:launchMode="singleTask"
     android:screenOrientation="portrait">
    
     <intent-filter>
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
    
      <data
        android:host="此处为你的包名"
        android:pathPrefix="/push_message"
        android:scheme="rong" />
     </intent-filter>
    </activity>
    

    2、在 TestPushActivity 里可以通过 intent.getData() 方法获取 url 里各数据内容,并根据业务需要进行处理,示例代码如下:

    /**
     * 当前 Activity 只是演示了一个操作过程,未加载任何 view,
     */
    public class TestPushActivity extends Activity {
    
        @Override
        protected void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);
    
            Intent intent = getIntent();
            getPushMessage(intent);
        }
    
        @Override
        protected void onNewIntent(Intent intent) {
            super.onNewIntent(intent);
            getPushMessage(intent);
        }
    
        /**
         * Android push 消息
         */
        private void getPushMessage(Intent intent) {
    
            if (intent != null && intent.getData() != null && intent.getData().getScheme().equals("rong")) {
    
                //该条推送消息的内容。
                String content = intent.getData().getQueryParameter("pushContent");
                //标识该推送消息的唯一 Id。
                String id = intent.getData().getQueryParameter("pushId");
                //用户自定义参数 json 格式,解析后用户可根据自己定义的 Key 、Value 值进行业务处理。
                String extra = intent.getData().getQueryParameter("extra");
                //统计通知栏点击事件.
                RongIMClient.recordNotificationEvent(id);
                Log.d("TestPushActivity", "--content:" + content + "--id:" + id + "---extra:" + extra);
            }
        }
    }
    

    url 携带字段说明:

    字段名 描述
    pushContent 该条推送消息的内容。
    pushId 标识该推送消息的唯一 Id。
    extra 用户自定义参数 json 格式,解析后用户可根据自己定义的 KeyValue 值进行业务处理。

    Server API 广播推送

    广播推送可精准及时的向符合条件的应用中用户推送消息,帮助开发者提升用户忠诚度及留存率。广播推送服务包括两个功能:一个是发送广播消息,一个是推送(Push):

    • 广播(Broadcast) 是一种业务概念,是通过后台管理界面或者调用服务端接口,向 App 中的所有用户发送一条消息。

    • 推送(Push) 是一种技术概念,是指从服务端实时发送信息到客户端。

      大家概念中的典型推送服务是类似 APNS(Apple Push Notification Service)GCM(Google Cloud Messaging) 等服务。在国内,由于谷歌服务不能使用,因此您的应用必须使用第三方或者自己研发的服务来推送。

      因为融云是使用长连接技术来实现 IM 服务的,和典型的 Push 服务具有相同的长连接机制,所以,很多开发者也会直接使用融云来实现推送功能。

      在某些场合,iOS 平台的推送(通过 APNS 的 Push)和远程通知(Remote Notification)表示相同的意思,可以互相替换使用。

    添加标签 方法

    为应用中的用户添加标签,如果某用户已经添加了标签,再次对用户添加标签时将覆盖之前设置的标签内容。

    方法名:/user/tag/set

    签名方法:请参考 通用 API 接口签名规则

    URL:https://api.cn.ronghub.com/user/tag/set.[format]

    [format] 表示返回格式,可以为 jsonxml,注意不要带 [ ]。

    HTTP 方法:POST

    请注意:发送请求时 HTTP Request Header 中的 Content-Type 类型必须为 application/json

    示例

    HTTP 请求:

    POST /user/tag/set.json HTTP/1.1
    Host: api.cn.ronghub.com
    App-Key: uwd1c0sxdlx2
    Nonce: 14314
    Timestamp: 1408706337
    Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {"userId":"31232","tags":["bj","男"]}
    

    表单参数

    名称 类型 说明
    userId String 用户 Id。(必传)
    tags String[] 用户标签,一个用户最多添加 20 个标签,每个 tags 最大不能超过 40 个字节,标签中不能包含特殊字符。(必传)

    返回值

    名称 类型 说明
    code int 返回码,200 为正常。

    JSON 格式:

    {"code":200}
    

    XML 格式:

    <xml><code>200</code></xml>
    

    返回值请参考 API 方法返回值说明

    广播消息 方法

    此方法与 /message/broadcast 广播消息方法发送机制一样,可选择更多发送条件。
    该功能开发环境下可免费使用。生产环境下,您需要在开发者后台“应用/IM 服务/高级功能设置”中开通公有云专业版后,在“广播消息和推送”中,开启后才能使用。收费详情

    方法名:/push

    调用频率:推送和广播消息合计每小时只能发送 2 次,每天最多发送 3 次。

    签名方法:请参考 通用 API 接口签名规则

    URL:https://api.cn.ronghub.com/push.[format]

    [format] 表示返回格式,可以为 jsonxml,注意不要带 [ ]。

    HTTP 方法:POST

    请注意:发送请求时 HTTP Request Header 中的 Content-Type 类型必须为 application/json,SDK 中会话类型为 SYSTEM

    示例

    HTTP 请求:

    POST /push.json HTTP/1.1
    Host: api.cn.ronghub.com
    App-Key: uwd1c0sxdlx2
    Nonce: 14314
    Timestamp: 1408706337
    Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {"platform":["ios","android"],"fromuserid": "fromuseId1","audience":{"tag":["女","年轻"],"tag_or":["北京","上海"],"userid":["123","456"],"is_to_all":false},"message": {"content": "{\"content\":\"1111\",\"extra\":\"aa\"}","objectName": "RC:TxtMsg"},"notification":{"alert":"this is a push","ios": {"alert": "override alert","extras": {"id": "1","name": "2"}},"android": {"alert": "override alert","extras": {"id": "1","name": "2"}}}}
    

    向指定标签推送 HTTP 请求示例:

    POST /push.json HTTP/1.1
    Host: api.cn.ronghub.com
    App-Key: uwd1c0sxdlx2
    Nonce: 14314
    Timestamp: 1408706337
    Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {"platform":["ios","android"],"fromuserid": "fromuseId1","audience":{"tag":["女","年轻","北京"]},"message": {"content": "{\"content\":\"1111\",\"extra\":\"aa\"}","objectName": "RC:TxtMsg"},"notification":{"alert":"this is a push"}}
    

    向指定用户推送 HTTP 请求示例:

    POST /push.json HTTP/1.1
    Host: api.cn.ronghub.com
    App-Key: uwd1c0sxdlx2
    Nonce: 14314
    Timestamp: 1408706337
    Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {"platform":["ios","android"],"fromuserid": "fromuseId1","audience":{"userid":["123","456"]},"message": {"content": "{\"content\":\"1111\",\"extra\":\"aa\"}","objectName": "RC:TxtMsg"},"notification":{"alert":"this is a push"}}
    

    向应用内所有用户推送 HTTP 请求示例:

    POST /push.json HTTP/1.1
    Host: api.cn.ronghub.com
    App-Key: uwd1c0sxdlx2
    Nonce: 14314
    Timestamp: 1408706337
    Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {"platform":["ios","android"],"fromuserid": "fromuseId1","audience":{"is_to_all":true},"message": {"content": "{\"content\":\"1111\",\"extra\":\"aa\"}","objectName": "RC:TxtMsg"},"notification":{"alert":"this is a push"}}
    

    iOS、Android 平台显示不同推送内容 HTTP 请求示例:

    POST /push.json HTTP/1.1
    Host: api.cn.ronghub.com
    App-Key: uwd1c0sxdlx2
    Nonce: 14314
    Timestamp: 1408706337
    Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {"platform":["ios","android"],"fromuserid": "fromuseId1","audience":{"is_to_all":true},"message": {"content": "{\"content\":\"1111\",\"extra\":\"aa\"}","objectName": "RC:TxtMsg"},"notification":{"alert":"this is a push","ios": {"alert": "iOS 通知显示内容","extras": {"id": "1","name": "2"}},"android": {"alert": "Android 通知显示内容","extras": {"id": "1","name": "2"}}}}
    

    表单参数

    名称 类型 说明
    platform String[] 目标操作系统,iOS、Android 最少传递一个。如果需要给两个系统推送消息时,则需要全部填写。(必传)
    fromuserid String 发送人用户 Id。(必传)
    audience String 推送条件,包括: tag、userid、is_to_all。(必传)
    tag String[] 用户标签,每次发送时最多发送 20 个标签,标签之间为 AND 的关系,is_to_all 为 true 时参数无效。(非必传)
    tag_or String[] 用户标签,每次发送时最多发送 20 个标签,标签之间为 OR 的关系,is_to_all 为 true 时参数无效,tag_or 同 tag 参数可以同时存在。(非必传)
    userid String[] 用户 Id,每次发送时最多发送 1000 个用户,如果 tag 和 userid 两个条件同时存在时,则以 userid 为准,如果 userid 有值时,则 platform 参数无效,is_to_all 为 true 时参数无效。(非必传)
    is_to_all String 是否全部推送,false 表示按 tag 、tag_or 或 userid 条件推送,true 表示向所有用户推送,tag、tag_or 和 userid 条件无效。(必传)
    content String 发送消息内容,参考融云 Server API 消息类型表.示例说明;如果 objectName 为自定义消息类型,该参数可自定义格式。(必传)
    objectName String 消息类型,参考融云 Server API 消息类型表.消息标志;可自定义消息类型,长度不超过 32 个字符。(必传)
    notification String 按操作系统类型推送消息内容,如 platform 中设置了给 iOS 和 Android 系统推送消息,而在 notification 中只设置了 iOS 的推送内容,则 Android 的推送内容为最初 alert 设置的内容。(非必传)
    alert String 默认推送消息内容,如填写了 iOS 或 Android 下的 alert 时,则推送内容以对应平台系统的 alert 为准。(必传)
    ios String 设置 iOS 平台下的推送及附加信息。
    android String 设置 Android 平台下的推送及附加信息。
    alert String iOS 或 Android 不同平台下的推送消息内容,传入后默认的推送消息内容失效,不能为空。(非必传)
    extras String iOS 或 Android 不同平台下的附加信息,如果开发者自己需要,可以自己在 App 端进行解析。(非必传)

    通知提示状态说明:

    • 1、App 前台可见时 SDK 处于前台状态,这时发送广播消息时,不提示通知。
    • 2、App 处于后台活跃状态或暂停状态,这时发送广播消息时,提示的通知内容,为您设置的 alert 内容。
    设置 objectName 推送其他消息类型,详细请参考融云消息类型表.消息标志

    返回值

    名称 类型 说明
    code int 返回码,200 为正常。
    id String 广播消息唯一标识。

    JSON 格式:

    {"code":200,"id":"50whSR6kQiHb7YgFwQzXIb"}
    

    XML 格式:

    <xml><code>200</code><id>50whSR6kQiHb7YgFwQzXIb</id></xml>
    

    返回值请参考 API 方法返回值说明

    推送 方法

    该功能在开发环境下可免费使用。生产环境下,您需要登录开发者后台,在“应用/IM 服务/高级功能设置”中开通公有云专业版后,在“服务器端发送广播消息”中,开启后才能使用。收费详情

    方法名:/push

    调用频率:推送和广播消息合计每小时只能发送 2 次,每天最多发送 3 次。

    签名方法:请参考 通用 API 接口签名规则

    URL:https://api.cn.ronghub.com/push.[format]

    [format] 表示返回格式,可以为 jsonxml,注意不要带 [ ]。

    HTTP 方法:POST

    请注意:发送请求时 HTTP Request Header 中的 Content-Type 类型必须为 application/json,SDK 中会话类型为 PUSH_SERVICE

    示例

    HTTP 请求:

    POST /push.json HTTP/1.1
    Host: api.cn.ronghub.com
    App-Key: uwd1c0sxdlx2
    Nonce: 14314
    Timestamp: 1408706337
    Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {"platform":["ios","android"],"audience":{"tag":["女","年轻"],"tag_or":["北京","上海"],"userid":["123","456"],"is_to_all":false},"notification":{"alert":"this is a push","ios": {"title": "标题","alert": "override alert","extras": {"id": "1","name": "2"}},"android": {"alert": "override alert","extras": {"id": "1","name": "2"}}}}
    

    向指定标签推送 HTTP 请求示例:

    POST /push.json HTTP/1.1
    Host: api.cn.ronghub.com
    App-Key: uwd1c0sxdlx2
    Nonce: 14314
    Timestamp: 1408706337
    Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {"platform":["ios","android"],"audience":{"tag":["女","年轻","北京"]},"notification":{"alert":"this is a push"}}
    

    向指定用户推送 HTTP 请求示例:

    POST /push.json HTTP/1.1
    Host: api.cn.ronghub.com
    App-Key: uwd1c0sxdlx2
    Nonce: 14314
    Timestamp: 1408706337
    Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {"platform":["ios","android"],"audience":{"userid":["123","456"]},"notification":{"alert":"this is a push"}}
    

    向应用内所有用户推送 HTTP 请求示例:

    POST /push.json HTTP/1.1
    Host: api.cn.ronghub.com
    App-Key: uwd1c0sxdlx2
    Nonce: 14314
    Timestamp: 1408706337
    Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {"platform":["ios","android"],"audience":{"is_to_all":true},"notification":{"alert":"this is a push"}}
    

    iOS、Android 平台显示不同推送内容 HTTP 请求示例:

    POST /push.json HTTP/1.1
    Host: api.cn.ronghub.com
    App-Key: uwd1c0sxdlx2
    Nonce: 14314
    Timestamp: 1408706337
    Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {"platform":["ios","android"],"audience":{"is_to_all":true},"notification":{"alert":"this is a push","ios": {"alert": "iOS 平台显示内容","extras": {"id": "1","name": "2"}},"android": {"alert": "Android 平台显示内容","extras": {"id": "1","name": "2"}}}}
    

    设置 iOS 角标数 HTTP 请求示例:

    POST /push.json HTTP/1.1
    Host: api.cn.ronghub.com
    App-Key: uwd1c0sxdlx2
    Nonce: 14314
    Timestamp: 1408706337
    Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {"platform":["ios","android"],"audience":{"is_to_all":true},"notification":{"alert":"this is a push","ios": {"alert": "iOS 平台显示内容","badge":2,"extras": {"id": "1","name": "2"}},"android": {"alert": "Android 平台显示内容","extras": {"id": "1","name": "2"}}}}
    

    设置 iOS 推送标题请求示例:

    POST /push.json HTTP/1.1
    Host: api.cn.ronghub.com
    App-Key: uwd1c0sxdlx2
    Nonce: 14314
    Timestamp: 1408706337
    Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {"platform":["ios","android"],"audience":{"is_to_all":true},"notification":{"alert":"this is a push","ios": {"title": "iOS 平台显示标题","alert": "iOS 平台显示内容","extras": {"id": "1","name": "2"}},"android": {"alert": "Android 平台显示内容","extras": {"id": "1","name": "2"}}}}
    

    表单参数

    名称 类型 说明
    platform String[] 目标操作系统,iOS、Android 最少传递一个。如果需要给两个系统推送消息时,则需要全部填写。(必传)
    audience String 推送条件,包括:tag 、userid 、 is_to_all。(必传)
    tag String[] 用户标签,每次发送时最多发送 20 个标签,标签之间为 AND 的关系,is_to_all 为 true 时参数无效。(非必传)
    tag_or String[] 用户标签,每次发送时最多发送 20 个标签,标签之间为 OR 的关系,is_to_all 为 true 时参数无效,tag_or 同 tag 参数可以同时存在。(非必传)
    userid String[] 用户 Id,每次发送时最多发送 1000 个用户,如果 tag 和 userid 两个条件同时存在时,则以 userid 为准,如果 userid 有值时,则 platform 参数无效,is_to_all 为 true 时参数无效。(非必传)
    is_to_all String 是否全部推送,false 表示按 tag 、tag_or 或 userid 条件推送,true 表示向所有用户推送,tag、tag_or 和 userid 条件无效。(必传)
    notification String 按操作系统类型推送消息内容,如 platform 中设置了给 iOS 和 Android 系统推送消息,而在 notification 中只设置了 iOS 的推送内容,则 Android 的推送内容为最初 alert 设置的内容。(非必传)
    alert String notification 下 alert,默认推送消息内容,如填写了 iOS 或 Android 下的 alert 时,则推送内容以对应平台系统的 alert 为准。(必传)
    ios String 设置 iOS 平台下的推送及附加信息。
    android String 设置 Android 平台下的推送及附加信息。
    title String 通知栏显示的推送标题,仅针对 iOS 平台,支持 iOS 8.2 及以上版本,参数在 ios 节点下设置,详细可参考“设置 iOS 推送标题请求示例”。(非必传)
    alert String iOS 或 Android 不同平台下的推送消息内容,传入后默认的推送消息内容失效,不能为空。(非必传)
    extras String iOS 或 Android 不同平台下的附加信息,如果开发者自己需要,可以自己在 App 端进行解析。(非必传)
    badge int 应用角标,仅针对 iOS 平台;不填时,表示不改变角标数;为 0 或负数时,表示 App 角标上的数字清零;否则传相应数字表示把角标数改为指定的数字,最大不超过 9999,参数在 ios 节点下设置,详细可参考“设置 iOS 角标数 HTTP 请求示例”。(非必传)

    返回值

    名称 类型 说明
    code int 返回码,200 为正常。
    id String 推送唯一标识。

    JSON 格式:

    {"code":200,"id":"50whSR6kQiHb7YgFwQzXIb"}
    

    XML 格式:

    <xml><code>200</code><id>50whSR6kQiHb7YgFwQzXIb</id></xml>
    

    返回值请参考 API 方法返回值说明

    开发者站点广播推送

    为方便运营人员使用,融云开发者后台提供了广播推送功能。包括:推送广播消息

    推送:是指从服务端实时发送信息到客户端,与广播消息的区别是客户端会收到远程推送通知,不会收到聊天消息。如图:

    image

    广播消息:是向 App 中的用户发送一条消息,与推送的区别是用户在线时客户端会收到聊天消息(如图 1),不在线时会收到远程推送通知,下次上线后会以离线消息方式发送(如图 2) 。

    image
    图 1
    image
    图 2

    更多概念解析请参见融云消息与推送概念答疑