API 参考
圈组

推送payload配置

更新时间: 2024/07/17 17:57:35

云信 IM 服务端支持自定义消息的推送配置。

用户在发送消息或者自定义系统通知时,可以通过入参 payload 来自定义推送配置,包括推送标题,消息类型,点击跳转形式等。为了集成多家厂商的推送服务,云信限定了 payload 的格式(JSON),当用户按照格式正确填写对应的推送参数后,云信将自动解析,并透传给对应的厂商。

payload 格式填写不正确,可能会导致推送不成功。

本文主要介绍云信 payload 字段的使用说明并提供各厂商对应的示例代码。

云信 payload 格式

云信的 payload 参数格式如下:

参数类型说明
pushTitle String公用参数,指定推送消息的标题
apsField JSONAPNs 推送消息中的 aps 参数,可参考 APNs 推送消息示例
hwPassThroughField JSON华为透传消息中的 Message 参数,可参考华为透传消息示例
hwField JSON华为通知栏消息中的 android.notification 参数,可参考华为通知栏消息示例
honorPassThroughField JSON荣耀透传消息中的 Message 参数,可参考荣耀透传消息示例
honorField JSON荣耀通知栏消息中的 Message.android 参数,可参考荣耀通知栏消息示例
vivoField JSONvivo 推送消息的请求体参数,可参考 vivo 推送消息示例
oppoField JSONOPPO 推送消息中的 message 参数,可参考 OPPO 推送消息示例
fcmField JSON旧版谷歌 FCM 推送消息中的 notification 参数,可参考谷歌 FCM 推送消息示例
fcmFieldV1 JSON新版谷歌 FCM 推送消息中的 notification 参数,可参考谷歌 FCM 推送消息示例
  • 小米推送的 extra 参数直接以以下方式传递,可参考小米推送消息示例extra 开头的字段说明详见小米官方文档
    "channel_id": "channel"  // 小米  extra.channel_id
    "channel_name": "channel_name"  // 小米 extra.channel_name
    
  • 魅族推送暂只提供 clickTypeInfo.parameters 的自定义配置,可直接通过 key-value 形式填写对应参数,可参考魅族推送消息示例

云信 payload 示例:

{
    "pushTitle":"",  // 公用参数,指定推送消息的标题
    "apsField":{},  // 等同于APNS推送中的aps参数 
    "fcmField": {}, // 等同于FCM推送中的notification参数 
    "honorPassThroughField": {},  // 荣耀透传消息等同于荣耀推送的Message参数
    "honorField": {},  // 等同于荣耀推送的Message.android参数
    "hwPassThroughField": {}, // 华为Message参数
    "hwField": {
          // android.notification参数直接在此处添加
          "click_action": {}, // 等同于android.notification.click_action参数
          "androidConfig": {
              "category":"",// 等同于AndroidConfig.category
          }
    }
    "oppoField": {}  //等同于Oppo推送的message参数
    "vivoField": {}  // 等同于vivo推送的请求体参数
    
    // 小米推送的extra参数直接以以下方式传递:
    "ticker":"value",
    "notify_foreground":"value"
    
    // 魅族推送暂只提供clickTypeInfo.parameters的自定义配置, 直接在此处填写对应参数
    "key":"value" 
}

第三方推送厂商对应的 payload 示例

APNs推送消息

{
   "pushTitle":"",  // 指定推送消息的标题
   "apsField": {
      "alert" : {
         "title" : "Game Request",
         "subtitle" : "Five Card Draw",
         "body" : "Bob wants to play poker"
      },
      "category" : "GAME_INVITATION"
   },
}

apsField 中的字段说明,详见 APNs 官网文档

小米推送消息

{
    "pushTitle":"",// 推送消息标题
    // 小米推送的 extra 参数直接以以下方式传递:
    "channel_id":""//通知类别(Channel)的ID
    "sound":"",//自定义通知栏消息铃声 URI,铃声文件放在 Android app 的 raw 目录下
    "ticker":"",//开启通知消息在状态栏滚动显示
    "notify_foreground":"1",//开启或关闭 app 在前台时的通知弹出,1:弹出,2:不弹出,默认为1
    "notify_effect":"1",//预定义通知栏消息的点击行为。1:通知栏点击后打开app的Launcher Activity,2:通知栏点击后打开app的任一Activity(开发者还需要传入intent_uri),3:通知栏点击后打开网页(开发者还需要传入web_uri)
    "intent_uri":"",
    "web_uri":"",
    "jobkey":"",
    "app_version":"",//可以接收消息的 app 版本号,用逗号分割
    "app_version_not_in":"",//无法接收消息的app版本号,用逗号分割
    "connpt":"",//指定在特定的网络环境下才能接收到消息。目前仅支持指定 wifi
    "only_send_once":"1"//设置为1,表示该仅设备在线时发送一次,不缓存离线消息进行多次下发
}

extra 开头的字段说明详见小米官方文档

华为推送消息

华为推送消息分类通知栏消息和透传消息,两种类型分别传入 hwPassThroughFieldhwField JSON 字符串来自定配置。

  • 如果一条消息的 payload 中同时包含 hwPassThroughField 和 hwField,则该推送会作为透传消息。即 hwPassThroughField 生效,hwField 的字段无效。
  • 其他字段说明详见华为官方文档

华为通知栏消息

{
    "pushTitle":"",//消息标题
    "hwField": {
        "click_action": { "type": 1},//消息点击行为。type为1:打开应用自定义页面,type为2:点击后打开特定URL,type为3:点击后打开应用
        "badge": {},//Android通知消息角标控制
        "style":1,//通知栏样式,取值如下:0:默认样式1:大文本样式 3:Inbox样式
        "androidConfig": {
            "collapse_key":-1,//用户设备离线时,Push 服务器对离线消息缓存机制,默认为-1,详见官方文档 AndroidConfig.collapse_key
            "urgency":"NORMAL",//透传消息投递优先级,详见官方文档AndroidConfig.urgency
            "category":"IM",//标识消息类型,用于标识高优先级透传场景,详见官方文档 AndroidConfig.category
            "data":""//自定义消息负载,详见官方文档AndroidConfig.data
        }
    }
}

华为透传消息

{
    "pushTitle":"",//消息标题
    "hwPassThroughField": {
        "data":"{\"1111\":\"22222\"}",//自定义消息负载,只支持字符串或json格式字符串
        "android": {
            "collapse_key":-1,//用户设备离线时,Push服务器对离线消息缓存机制,默认为-1,详见官方文档AndroidConfig.collapse_key
            "urgency":"NORMAL",//透传消息投递优先级,详见官方文档AndroidConfig.urgency
            "category":"IM",//标识消息类型,用于标识高优先级透传场景,,详见官方文档AndroidConfig.category
        }
    }
}

荣耀推送消息

荣耀推送消息分类通知栏消息和透传消息,两种类型分别传入 honorPassThroughFieldhonorField JSON 字符串来自定配置。

  • 如果一条消息的 payload 中同时包含 honorPassThroughField 和 honorField,则该推送会作为透传消息。即 honorPassThroughField 生效,honorField 的字段无效。
  • 其他字段说明详见荣耀官方文档

荣耀通知栏消息

{
    "pushTitle":"",  // 消息标题
    "honorField":{  
        "biTag": "biTag001",  // AndroidConfig.biTag
        "data": "",  // AndroidConfig.data
        "notification": {  // AndroidNotification
            "bigBody": "the big body",
            "bigTitle": "the big title",
            "body": " the big body",
            "title": " the big title",
            "buttons": [{
                    "actionType": 0,
                    "data": "",
                    "intent": "",
                    "intentType": 0,
                    "name": "test"
            }],
            "clickAction": {//	消息点击行为
                "action": "",
                "intent": "intent://com.hihonor.codelabpush",
                "type": 1,//1为打开应用自定义页面,2为点击后打开特定URL,3为点击后打开应用
                "url": "https://www.vmall.com"
            },
            "image": "https://res.vmallres.com/SXppnESYv4K11DBxDFc2.png",
            "importance": "NORMAL",
            "style": 0,
            "when": "2014-10-02T15:01:23.045123456Z"
        }
    }
}

荣耀透传消息

{
    "pushTitle":"",  //消息标题
    "honorPassThroughField": {
        "data":"{\"1111\":\"22222\"}",  // message.data
        "android": {
            "biTag":"",  // AndroidCofig.biTag
        }
    }
}

vivo推送消息

{
    "pushTitle":"",//消息标题
    "vivoField": {
        "skipType":"1",//点击跳转类型 1:打开APP首页 2:打开链接 3:自定义 4:打开app内指定页面,默认为1
        "skipContent":"",//跳转内容,与skipType对应
        "classification":"0",//消息类型 0:运营类消息,1:系统类消息。默认为0
        "networkType":"-1",//网络方式 -1:不限,1:wifi下发送,不填默认为-1
        "pushMode":"0",//推送模式 0:正式推送;1:测试推送,不填默认为0
        "category":"IM" // 二级分类
    }
}

vivoField 中的字段说明,详见 vivo 官方文档

OPPO推送消息

{
    "pushTitle":"",//消息标题
    "oppoField": {
            "channel_id": "", //指定下发的通道ID
            "click_action_type": "", //点击通知栏后触发的动作类型。0(默认0.启动应用;1.跳转指定应用内页(action标签名);2.跳转网页;4.跳转指定应用内页(全路径类名);5.跳转Intent scheme URL: "",
            "click_action_activity": "",
            "click_action_url": "",
            "action_parameters": "",
            "style": 1, //通知栏样式
            "action_parameters": 
            "sub_title": "", // 子标题
            "network_type": 0, //推送的网络环境类型
    }
}

oppoField 中的字段说明,详见 OPPO 官方文档

魅族推送消息

{
    "pushTitle":"",//消息标题
    // 魅族推送暂只提供 clickTypeInfo.parameters 的自定义配置, 直接在此处填写对应参数
    "key":"value",  // clickTypeInfo.parameters中的自定义字段
    "key":"value"  // clickTypeInfo.parameters中的自定义字段
}

clickTypeInfo.parameters 的自定义配置说明,详见魅族官方文档

谷歌FCM推送消息

旧版

{
    "fcmField": {
        "analytics_label":"统计字段,对应官方文档中fcm_options字段中的analytics_label",
        "icon":"string",
        "color":"string",
        "sound":"string",
        "tag":"string",
        "click_action":"string",
        "body_loc_key":"string",
        "body_loc_args": [
            "string"
        ],
        "title_loc_key":"string",
        "title_loc_args": [
        ],
        "channel_id":"string",
        "ticker":"string",
        "sticky":"boolean",
        "event_time":"string",
        "local_only":"boolean",
        "notification_priority":"",
        "default_sound":"boolean",
        "default_vibrate_timings":"boolean",
        "default_light_settings":"boolean",
        "vibrate_timings": [
            "string"
        ],
        "visibility":"",
        "notification_count":"integer",
        "light_settings": {

        },
        "image":"string"
    },
    "key":"value",
}

更多字段信息请参考官方文档

新版(FCM HTTP V1 推送)

使用 FCM HTTP V1 协议推送需要申请 HTTP V1 鉴权证书。当使用该版本证书进行推送时,payload 中应使用 "fcmFieldV1" 字段配置自定义推送参数。使用旧版本证书推送时,应使用"fcmField"字段配置自定义推送参数。新版本证书和旧版本证书可以同时使用,服务器会根据用户SDK中配置的证书版本选取推送通道。

FCM HTTP V1 推送的更多信息请参考官方文档

{
    "fcmFieldV1":{
        "validate_only": true,
        "message": {
          "needNotification": false, // 是否需要自动填充notification字段,默认true,当需要使用数据消息时,此字段需要设置为false
          "notification": {
            "image": "string"
          },
          "data": {
            "name": "wrench",
            "mass": "1.3kg",
            "count": "3" 
          },
          "android": {
            "restricted_package_name": "string",
            "data": {
              "string": "string",
            },
            "notification": {
              "channel_id": "string",
              "color": "string",
            },
            "fcm_options": {
              "analytics_label": "string"
            },
            "direct_boot_ok": true
          }
        }
    }    
}

相关参考文档

更多推送参数说明请参考第三方推送厂商的官方文档:

此文档是否对你有帮助?
有帮助
去反馈
  • 云信 payload 格式
  • 第三方推送厂商对应的 payload 示例
  • APNs推送消息
  • 小米推送消息
  • 华为推送消息
  • 华为通知栏消息
  • 华为透传消息
  • 荣耀推送消息
  • 荣耀通知栏消息
  • 荣耀透传消息
  • vivo推送消息
  • OPPO推送消息
  • 魅族推送消息
  • 谷歌FCM推送消息
  • 相关参考文档