自定义推送规则

2026-11-06

多端登录场景下，如果用户希望当某些平台的账号在线时，部分其他平台上的账号不收到离线推送通知，可以通过自定义推送规则实现。

前提条件

在实现“自定义推送规则”功能之前，请确保：

已实现多端登录.

实现流程

用户离线推送规则变化通知

如需用户自定义规则时收到通知，请监听 onUserRuleUpdated 回调。

// 监听用户自定义规则
zim.on('userRuleUpdated', (zim: ZIM, data: ZIMUserRuleUpdatedEventResult) => {
    // 离线推送规则
    const offlinePushRule = data.userRule.offlinePushRule;
});

// 监听用户自定义规则
zim.on('userRuleUpdated', (zim: ZIM, data: ZIMUserRuleUpdatedEventResult) => {
    // 离线推送规则
    const offlinePushRule = data.userRule.offlinePushRule;
});

设置离线推送规则

如需支持用户自定义推送规则时，开发者需要构造 ZIMUserOfflinePushRule，规定用户在哪些平台上在线（onlinePlatforms）时，哪些平台无需接收离线推送（notToReceiveOfflinePushPlatforms）。

自 3.3.0 版本起，ZIMUserOfflinePushRule 新增以下字段：

字段	说明
`offlinePushEnabled`	离线推送总开关，默认开启。关闭后，消息和呼叫的离线推送均不下发。
`messageOfflinePushEnabled`	消息离线推送开关，默认开启。仅影响消息离线推送，不影响呼叫离线推送。
`callOfflinePushEnabled`	呼叫离线推送开关，默认开启。仅影响呼叫离线推送，不影响消息离线推送。
`doNotDisturbRule`	免打扰时间规则，规则生效期间，消息和呼叫的离线推送均不下发。详细请参考设置免打扰时间规则。

调用 updateUserOfflinePushRule 接口，设置上述规则。

const offlinePushRule: ZIMUserOfflinePushRule = {
    // 当用户 Win、MacOS、Linux 平台登录时
    onlinePlatforms: [1, 4, 5],
    // 用户在 iPhoneOS、iPadOS、Android 上不收到离线推送
    notToReceiveOfflinePushPlatforms: [2, 3, 9],
    // 离线推送总开关，默认开启（自 3.3.0 版本起支持）
    offlinePushEnabled: true,
    // 消息离线推送开关，仅影响消息离线推送，默认开启（自 3.3.0 版本起支持）
    messageOfflinePushEnabled: true,
    // 呼叫离线推送开关，仅影响呼叫离线推送，默认开启（自 3.3.0 版本起支持）
    callOfflinePushEnabled: true,
};

zim.updateUserOfflinePushRule(offlinePushRule)
    .then((res: ZIMUserOfflinePushRuleUpdatedResult) => {
        // success
    })
    .catch((err: ZIMError) => {
        // error
    });

const offlinePushRule: ZIMUserOfflinePushRule = {
    // 当用户 Win、MacOS、Linux 平台登录时
    onlinePlatforms: [1, 4, 5],
    // 用户在 iPhoneOS、iPadOS、Android 上不收到离线推送
    notToReceiveOfflinePushPlatforms: [2, 3, 9],
    // 离线推送总开关，默认开启（自 3.3.0 版本起支持）
    offlinePushEnabled: true,
    // 消息离线推送开关，仅影响消息离线推送，默认开启（自 3.3.0 版本起支持）
    messageOfflinePushEnabled: true,
    // 呼叫离线推送开关，仅影响呼叫离线推送，默认开启（自 3.3.0 版本起支持）
    callOfflinePushEnabled: true,
};

zim.updateUserOfflinePushRule(offlinePushRule)
    .then((res: ZIMUserOfflinePushRuleUpdatedResult) => {
        // success
    })
    .catch((err: ZIMError) => {
        // error
    });

设置免打扰时间规则

自 3.3.0 版本起，ZIMUserOfflinePushRule 支持通过 doNotDisturbRule 字段设置免打扰时间规则。规则生效期间，消息和呼叫的离线推送均不下发。

说明

调用 updateUserOfflinePushRule 接口时，离线推送规则会按传入对象的成员属性全量更新。如需修改免打扰时间规则等单个配置项，请先调用 querySelfUserInfo 查询当前完整的离线推送规则，修改后再全量提交，避免覆盖其他已有配置。

ZIMUserOfflinePushDoNotDisturbRule 字段说明如下：

字段	说明
enabled	是否启用免打扰规则。
startHour / startMinute	免打扰时段的开始时间，小时取值范围 [0, 23]，分钟取值范围 [0, 59]。
endHour / endMinute	免打扰时段的结束时间，小时取值范围 [0, 23]，分钟取值范围 [0, 59]。结束时间早于开始时间时，表示时段跨过零点，例如 22:00 至次日 08:00。
repeatMode	重复模式： `None`（1）：不重复，规则仅在保存当天生效。 `Daily`（2）：每天重复。 `Custom`（3）：自定义重复日，配合 `customRepeatDays` 使用。默认为 `Unknown`（未设置），SDK 会向服务端上报 0，规则仅在保存当天生效（不重复）。
customRepeatDays	自定义重复日，位掩码格式，bit0 表示周一，bit6 表示周日。仅在 `repeatMode` 为 `Custom` 时生效。
onceEndTimestamp	当 `repeatMode` 为 `None` 时，仅生效一次的免打扰时段结束的 UNIX 时间戳（秒），由服务端在保存规则时记录。只读字段，更新规则时传入的值会被忽略，由服务端重新计算。
timeZoneID	免打扰时段的 IANA 时区 ID，例如 "Asia/Shanghai"。空字符串表示未指定，服务端按 UTC 计算时段；非空时由服务端校验（非法 ID 返回错误码），并按该时区计算时段（感知夏令时）。如需跟随设备时区，请显式获取并传入本机 IANA 时区 ID。

// 先查询当前完整的离线推送规则
zim.querySelfUserInfo()
    .then((res: ZIMSelfUserInfoQueriedResult) => {
        const offlinePushRule = res.selfUserInfo.userRule.offlinePushRule;

        // 修改免打扰时间规则（自 3.3.0 版本起支持）
        offlinePushRule.doNotDisturbRule = {
            enabled: true,
            // 免打扰时段：每天 22:00 至次日 08:00
            startHour: 22,
            startMinute: 0,
            endHour: 8,
            endMinute: 0,
            // 每天重复
            repeatMode: 2,
            customRepeatDays: 0,
            onceEndTimestamp: 0,
            // 时区，建议显式传入本机 IANA 时区 ID
            timeZoneID: 'Asia/Shanghai',
        };

        // 全量更新离线推送规则
        return zim.updateUserOfflinePushRule(offlinePushRule);
    })
    .then((res: ZIMUserOfflinePushRuleUpdatedResult) => {
        // success
    })
    .catch((err: ZIMError) => {
        // error
    });

// 先查询当前完整的离线推送规则
zim.querySelfUserInfo()
    .then((res: ZIMSelfUserInfoQueriedResult) => {
        const offlinePushRule = res.selfUserInfo.userRule.offlinePushRule;

        // 修改免打扰时间规则（自 3.3.0 版本起支持）
        offlinePushRule.doNotDisturbRule = {
            enabled: true,
            // 免打扰时段：每天 22:00 至次日 08:00
            startHour: 22,
            startMinute: 0,
            endHour: 8,
            endMinute: 0,
            // 每天重复
            repeatMode: 2,
            customRepeatDays: 0,
            onceEndTimestamp: 0,
            // 时区，建议显式传入本机 IANA 时区 ID
            timeZoneID: 'Asia/Shanghai',
        };

        // 全量更新离线推送规则
        return zim.updateUserOfflinePushRule(offlinePushRule);
    })
    .then((res: ZIMUserOfflinePushRuleUpdatedResult) => {
        // success
    })
    .catch((err: ZIMError) => {
        // error
    });

查询用户定义的推送规则

通过调用 querySelfUserInfo，即可在回调中的 selfUserInfo.userRule.offlinePushRule 获取当前用户自定义的离线推送规则。

zim.querySelfUserInfo()
    .then((res: ZIMSelfUserInfoQueriedResult) => {
    });

zim.querySelfUserInfo()
    .then((res: ZIMSelfUserInfoQueriedResult) => {
    });