UPush

Java SDK #

Java SDK的集成可参照Rest API项目 (opens new window)

类定义 #

  • 高亮属性为必选，未标记属性都是可选。

消息 #

  • 建议使用UMessage.Builder构建





 



































































































































































public class UMessage {

    /**
     * 推送内容，必选
     */
    private String payload;

    /**
     * 消息唯一标示，如果为空会自动生成，可在发送成功后获取
     */
    private String msgId;

    /**
     * 消息发送者唯一标示，即发送者的用户ID
     */
    private String fromId;

    /**
     * 消息类型，不填写默认为1
     */
    private Integer type;

    /**
     * 额外/扩展信息
     */
    private Map<String, Object> extra;

    /**
     * 通知栏显示内容，为空表示穿透消息
     */
    private UMessageNotification notification;

    /**
     * 指定消息的有效期，单位秒
     * 1表示即时消息，不存储离线消息，无法送达就丢弃。
     * 0或者空时使用系统设置的有效期。有效期不能大于系统配置的消息有效期
     */
    private Integer expires;

    /**
     * 通知类型
     */
    private Integer notifyType;

    /**
     * 延迟时间发送，单位秒
     */
    private Long delayTime;

    /**
     * 手动指定消息的接收者，99%场景不使用。
     * 例如使用接口：UPushMsgTask userPush(UMessage message, String userId)，
     * 其中userId就是消息的接受者，那么在构建消息时无需指定toId。
     */
    private String toId;

    /**
     * Builder  UMessage的构造器
     */
    public static class Builder<T extends Builder> {
        /**
         * 默认构造
         */
        public Builder()

        /**
         * 设置通知类型
         */
        public T notifyType(Integer notifyType)

        /**
         * 把键值对添加到额外信息
         *
         * @param key
         * @param value
         * @return
         */
        public T putExtra(String key, Object value)

        /**
         * 设置额外信息
         */
        public T extra(Map<String, Object> map)

        /**
         * 群组消息@的用户ID数组，只在群组消息有效
         * @param alts alts被添加到extra
         */
        public T setAlts(String[] alts)

        /**
         * 群消息@全体
         */
        public T setAltAll()

        /**
         * voip消息具有最高推送优先级
         */
        public T viop()

        /**
         * 消息发送者ID
         *
         * @param value
         */
        public T fromId(String value)

        /**
         * 消息唯一标示
         *
         * @param value
         * @return
         */
        public T msgId(String value)

        /**
         * 消息内容
         *
         * @param value
         * @return
         */
        public T payload(String value)

        /**
         * 消息类型
         *
         * @param value
         * @return
         */
        public T type(Integer value)

        /**
         * 消息有效期，单位秒，时间不能大于系统配置的offline.msg.expire
         * 1表示即时消息，在线推送不在线丢弃(手机端有三方推送并且是通知栏消息时，会使用三方推送)。
         * 0表示永久消息，直到接收或者超过服务端配置的有效期才会被删除
         * ios的voip是即时消息
         * @param value
         * @return
         */
        public T expires(Integer value)

        /**
         * 消息延迟推送
         * @param delayTime 延迟时间 秒
         * @return
         */
        public T  delayTime(Long delayTime)

        /**
         * 设置通知栏可用（简便的方式，通知栏自动装载）
         * @return
         */
        public T setNotificationEnable()

       /**
         * 手动指定通知栏内容,(不推荐，建议使用自动装载方式)
         * @param notification
         */
        public T notification(UMessageNotification notification)

        /**
         * 参照上面toId说明，绝大多数场景不要使用
         */
        public T toId(String value)

        public UMessage build()
    }
}

群订阅者 #





 






public class UserSubscribeModel {
   /**
     * 用户唯一标示
     */
    private String userId;
    /**
     * 用户名称
     */
    private String name; 
}

消息撤回 #






 






















public class URevokeMessage {

    /**
     * 被撤回的消息唯一标示，必选
     */  
    private String msgId;

    /**
     * 发送者唯一标示
     */
    private String fromId;

    /**
     * 提示语
     */
    private String alert;

    /**
     * 同 UMessage
     */
    private Integer expires;

    /**
     * 消息类型
     */
    private Integer type;
}

通知 #

  • 使用自动装载的方式构建通知可完全忽略此类
public class UMessageNotification {

    /**
     * 标题
     */
    private String title;

    /**
     * 副标题，android系统时副标题拼接在内容前面用":"分割
     */
    private String subTitle;

    /**
     * 通知栏显示内容
     */
    private String body;

    /**
     * 大图标
     */
    private String largeIcon;

    /**
     * 声音描述，ios, android 8.0以下版本
     */
    private String sound;

    /**
     * 角标数，正数时直接设置角标数，负数时表示角标自增
     */
    private Integer badge;

    /**
     * 自定义通知点击动作
     */
    private String action;

    /**
     * 厂商推送额外/扩展信息，只用用于构建厂商推送，不会推送给客户端。
     * 对厂商推送服务二次开发使用，不做二开请忽略此属性。
     */
    private Map<String, Object> vendorExtra;

    /**
     * 通知channel标示，android独有
     */
    private String channelId;

    /**
     * 类别， ios独有
     */
    private String category;
}

请求 #

public interface UPushTask {

    /**
     * 异步发送，带回调方法
     * @param callback
     */
    void send(UPushCallback callback);

    /**
     * 异步发送，不管关心回调
     */
    void send();

    /**
     * 同步发送
     * @return
     */
    UPushResponse sendSync();

    /**
     * 同步发送
     * @param timeout 等待超时时间，毫秒
     * @return
     */
    UPushResponse sendSync(int timeout);
}

public interface UPushMsgTask extends UPushTask {
    /**
     * 推送目标存在多平台时，用包名来过滤不同平台的设备，包含或排除，向满足包名条件的平台推送
     * @param packageName 指定包名，多个包名时用;分割，前面加!表示排除
     * @return
     */
    UPushMsgTask filterPackageName(String packageName);

    /**
     * 对用户推送时，如果需要把消息同步给fromId其他平台设备，需要调用此方法
     * 推送群消息时排除掉发送设备
     * 全体推送消息时排除掉发送设备
     * 必须配合fromId一起使用
     * @param fromToken 发送设备的pushToken
     * @return
     */
    UPushMsgTask excludeFromToken(String fromToken);

    /**
     * 设置消息画像，如果指定了消息画像，系统内将不使用自动装载方式构建画像。必须配合fromId一起使用。
     * @param portrait
     * @return
     */
    UPushMsgTask setPortrait(UMessagePortrait portrait);
}

public interface UPushCallback {
    /**
     * @param response 应答对象
     */
    void onResponse(UPushResponse response);
}

public class UMessagePortrait {
    private String name;
    private String avatar;
    private String groupName;
    private String groupAvatar;

    public UMessagePortrait() {}
    public UMessagePortrait(String name, String avatar);
    public UMessagePortrait(String name, String avatar, String groupName, String groupAvatar);

    // ...省略属性的set,get方法
}

应答 #

public class UPushResponse {
    /**
     * 应答code, 0成功， 其他请参照错误码
     */
    private Integer code;
    /**
     * 请求成功返回数据
     */
    private Object data;
    /**
     * 返回错误信息
     */
    private String msg;
}
多用户推送，撤回，订阅，取消订阅，可能存在应答code为1部分成功的场景，此时应答data结构为，key是错误码的字符串形式，value是出现此错误用户ID集合，例如： 
{
  errorList: {
    "20003": ["用户ID1", "用户ID1"],
    "20004": ["用户ID3", "用户ID4"]
  }

}

常量 #

通知类型 #

public class NotifyType {

    /**
     * 正常通知
     */
    public static final int DEFAULT = 0;

    /**
     * 接收通知，只显示发送人/标题，消息内容用"您有一条新消息"来代替内容
     */
    public static final int NO_MESSAGE = 1;

    /**
     * 接收通知，不显示发送人/标题，消息内容用"您有一条新消息"来代替内容
     */
    public static final int ONLY_NOTIFY = 2;

    /**
     * 免打扰，接收通知但不提醒
     */
    public static final int NO_DISTURB = 3;
}

错误码 #

错误码
描述
0成功
1部分成功
10000未知错误，未捕获的系统异常
10001未知错误，未捕获的系统异常
10002无效参数
10003无效请求
10004请求超时
10006服务无法连接
10007无效的pushToken
10009服务启动校验出错
10010设备没有授权
20001pushToken不存在
20002pushToken的已经注销
20003用户不存在
20004在黑名单中无法推送
20005群组不存在
20006用户不在群组中
30001撤回超时
30002撤回,校验fromId失败
30003无法撤回不存在的群消息

厂商类型 #

厂商
厂商缩写
厂商类型
苹果APNS1
小米XIAOMI2
华为HUAWEI3
OPPOOPPO4
VIVOVIVO5
谷歌FCM7
魅族MEIZU8
荣耀HONOR9

初始化 #

/**
  * 构建推送对象
  *
  * @param appSecret 创建项目生成的AppSecret
  * @param addr      master服务器地址，如果master使用负载均衡，这里传入负载地址，端口同理
  * @param port      master服务器端口
  */
UPushClient(String appSecret, String addr, int port)

设备推送 #

/**
  * pushToken推送
  * @param message    消息
  * @param pushToken  推送设备唯一标示
  * @return
  */
UPushTask tokenPush(UMessage message, String pushToken)

/**
  * 多pushToken推送
  * @param message     消息
  * @param pushTokens  pushToken集合
  * @return
  */
UPushTask tokensPush(UMessage message, Collection<String> pushTokens)

/**
  * pushToken消息撤回
  * @param revokeMessage 撤回消息
  * @param pushToken     推送设备唯一标示
  * @return
  */
UPushTask tokenRevoke(URevokeMessage revokeMessage, String pushToken)

/**
  * 多pushToken消息撤回
  * @param revokeMessage  撤回消息
  * @param pushTokens     pushToken集合
  * @return
  */
UPushTask tokensRevoke(URevokeMessage revokeMessage, Collection<String> pushTokens)

用户推送 #

  • 推荐使用
/**
  * 用户推送
  * @param message  消息
  * @param userId   用户ID
  * @return
  */
UPushMsgTask userPush(UMessage message, String userId)

/**
  * 多用户推送
  * @param message  消息
  * @param userIds  用户ID集合
  * @return
  */
UPushMsgTask usersPush(UMessage message, Collection<String> userIds)

/**
  * 用户消息撤回
  * @param revokeMessage  撤回消息
  * @param userId         用户ID
  * @return
  */
UPushMsgTask userRevoke(URevokeMessage revokeMessage, String userId)

/**
  * 多用户消息撤回
  * @param revokeMessage   撤回消息
  * @param userIds         用户ID集合
  * @return
  */
UPushMsgTask usersRevoke(URevokeMessage revokeMessage, Collection<String> userIds)

/**
  * 删除用户
  * @param userId
  * @return
  */
UPushTask deleteUser(String userId)

/**
  * 删除多个用户
  * @param userIds
  * @return
  */
UPushTask deleteUsers(Collection<String> userIds)

群组推送 #

  • 抽象意义上的群组。groupId可以理解为群组唯一标示，组织唯一标示，订阅项唯一标示，标签唯一标示等等，是对业务系统中某个范围推送领域的抽象，不局限于'群组'的表意。下面不在对群组的含义进行赘述！
/**
  * 群组推送
  * @param message  消息
  * @param groupId  群组ID
  * @return
  */
UPushMsgTask groupPush(UMessage message, String groupId)

/**
  * 对群组里指定用户推送
  * @param message   消息
  * @param groupId   群组ID
  * @param userIds   群成员ID集合
  * @return
  */
public UPushMsgTask groupPush(UMessage message, String groupId, Collection<String> userIds)

/**
  * 群组消息撤回
  * @param message  撤回消息
  * @param groupId  群组ID
  * @return
  */
UPushMsgTask groupRevoke(URevokeMessage message, String groupId)

全局推送 #

/**
  * 全体推送
  * @param message 消息
  * @return
  */
UPushMsgTask pushAll(UMessage message)

/**
  * 广播推送，即只对在线设备推送
  * @param message 消息
  * @return
  */
UPushMsgTask broadcast(UMessage message)

延迟消息撤回 #

  • 在延迟消息未推送之前，请使用此方法，其他撤回无效。
/**
  * 延迟消息撤回
  * @param msgId 消息ID
  * @return
  */
UPushTask delayMessageRevoke(String msgId)

群组/订阅 #

  • 推荐使用用户订阅群组
/**
  * pushToken订阅群组
  * @param groupId     群组ID
  * @param pushToken   推送设备唯一标示
  * @return
  */
UPushTask tokenSubscribe(String groupId, String pushToken)

/**
  * 多pushToken订阅群组
  * @param groupId     群组ID
  * @param pushTokens  pushToken集合
  * @return
  */
UPushTask tokensSubscribe(String groupId, Collection<String> pushTokens)

/**
  * pushToken订阅多群组
  * @param groupIds   群组ID集合
  * @param pushToken  推送设备唯一标示
  * @return
  */
UPushTask tokenMultiSubscribe(Collection<String> groupIds, String pushToken)

/**
  * pushToken取消订阅群组
  * @param groupId    群组ID
  * @param pushToken  推送设备唯一标示
  * @return
  */
UPushTask tokenUnsubscribe(String groupId, String pushToken)

/**
  * 多pushToken取消订阅群组
  * @param groupId     群组ID
  * @param pushTokens  pushToken集合
  * @return
  */
UPushTask tokensUnsubscribe(String groupId, Collection<String> pushTokens)

/**
  * 用户订阅群组
  * @param groupId   群组ID
  * @param userModel 订阅用户
  * @return
  */
UPushTask userSubscribe(String groupId, UserSubscribeModel userModel)

/**
  * 多用户订阅群组
  * @param groupId    群组ID
  * @param userModels 订阅用户集合
  * @return
  */
UPushTask usersSubscribe(String groupId, Collection<UserSubscribeModel> userModels)

/**
  * 用户取消订阅群组
  * @param groupId   群组ID
  * @param userId    用户ID
  * @return
  */
UPushTask userUnsubscribe(String groupId, String userId)

/**
  * 多用户取消订阅群组
  * @param groupId  群组ID
  * @param userIds  userId集合
  * @return
  */
UPushTask usersUnsubscribe(String groupId, Collection<String> userIds)

/**
  * 用户取消订阅多群组
  * @param groupIds
  * @param userId
  * @return
  */
UPushTask usersUnsubscribe(Collection<String> groupIds, String userId)

/**
  * 删除订阅项，删除后并不会影响群离线消息
  * @param groupId   群组ID
  * @return
  */
UPushTask deleteGroup(String groupId)

设置 #

/**
  * 设置推送设备的通知类型
  * @param pushToken   推送设备唯一标示
  * @param notifyType  通知类型
  * @return
  */
UPushTask setNotifyTypeForToken(String pushToken, Integer notifyType)

/**
  * 设置推送设备在接收群组消息时的通知类型
  * @param groupId     群组ID
  * @param pushToken   推送设备唯一标示
  * @param notifyType  通知类型
  * @return
  */
UPushTask setGroupNotifyTypeForToken(String groupId, String pushToken, Integer notifyType)

/**
  * 设置用户在接收群组消息时的通知类型
  * @param groupId      群组ID
  * @param userId       用户ID
  * @param notifyType   通知类型
  * @return
  */
UPushTask setGroupNotifyTypeForUser(String groupId, String userId, Integer notifyType)

/**
  * 设置用户接收fromId消息的通知类型
  * @param fromId       消息发送者唯一标示，即发送者的用户ID
  * @param userId       用户ID
  * @param notifyType   通知类型
  * @return
  */
UPushTask setNotifyTypeForFromId(String fromId, String userId, Integer notifyType)

/**
  * 设置用户接收fromId消息时显示fromId的别名。可以理解为接收者给发送者设置的别名。
  * @param fromId   消息发送者唯一标示，即发送者的用户ID
  * @param userId   用户ID
  * @param alias    别名/备注名
  * @return
  */
UPushTask setAliasForFromId(String fromId, String userId, String alias)

/**
  * 设置用户在群组中的别名
  * @param groupId   群组ID
  * @param userId    用户ID
  * @param alias     别名/备注名
  * @return
  */
UPushTask setAliasForUserInGroup(String groupId, String userId, String alias)

/**
  * 设置用户消息画像。可以理解为发送者给自己设置的名字和头像。
  * @param userId    用户唯一标示
  * @param name      用户名字，可空
  * @param avatar    用户头像，可空，建议为Url或者通过系统配置项msg.avatar.url.prefix拼接为Url。下面头像参数不再赘述。
  * @return
  */
UPushTask setPortraitForUser(String userId, String name, String avatar)

/**
  * 设置群组消息画面
  * @param groupId   群组ID
  * @param name      群组名，可空
  * @param avatar    群组头像，可空
  * @return
  */
UPushTask setPortraitForGroup(String groupId, String name, String avatar)

其他 #

  • tokenReplace 如果业务系统完全不使用用户推送时，表示业务系统自行维护推送设备和用户的关系，业务系统发现pushToken变更时调用此方法，来保证之前pushToken的订阅能转移到新pushToken中，以及之前pushToken的离线消息会推送给新pushToken。建议业务系统整体上使用用户方式，用户推送，用户订阅，把这些复杂的关系维护交给UPush来完成。
  • pushToken 相关接口是从版本1延续下来的，一方面是为了保证接口的完整性，另一方面在某些特殊场景依然需要对指定设备进行推送，如扫码登录，扫码支付等。
/**
  * 业务系统发现pushToken变更时调用此方法
  * @param previousToken  之前的pushToken
  * @param currentToken   变更后的pushToken
  * @return
  */
UPushTask tokenReplace(String previousToken, String currentToken)

/**
  * 取得设备在线状态
  * @param pushToken  设备的pushToken
  * @return { status }, status:  1 在线，0 离线，-1 注销，-2 pushToken不存在
  */
public UPushTask getOnlineStatus(String pushToken)
上次更新: 8/27/2024, 7:32:38 PM

Rest API