Set custom push rules
If a user is logged in on multiple platforms, the user can configure custom push rules to specify the platforms that can or cannot receive offline push notifications.
Prerequisites
Before you implement the custom push rule feature, make sure that the following conditions are met:
- Multi-device login is implemented. For more information, see Multi-device login.
Implementation steps
Notification for offline push rule update
To receive notifications when users customize rules, please listen for the onUserRuleUpdated callback.
// Listen for user-defined rules
@Override
public void onUserRuleUpdated(ZIM zim, ZIMUserRule rule) {
// Offline push rules
userRule.offlinePushRule;
}Set offline push rules
To support custom push rules, developers need to construct ZIMUserOfflinePushRule to specify the platforms that do not receive offline push notifications (notToReceiveOfflinePushPlatforms) when the user is online on specified platforms (onlinePlatforms).
Starting from version 3.3.0, ZIMUserOfflinePushRule adds the following fields:
| Field | Description |
|---|---|
offlinePushEnabled | Master switch for offline push, enabled by default. When it is disabled, neither message nor call offline push notifications are delivered. |
messageOfflinePushEnabled | Switch for message offline push, enabled by default. It only affects message offline push and does not affect call offline push. |
callOfflinePushEnabled | Switch for call offline push, enabled by default. It only affects call offline push and does not affect message offline push. |
doNotDisturbRule | Do-not-disturb time rule. While the rule is in effect, neither message nor call offline push notifications are delivered. For details, see Set the do-not-disturb time rule. |
To set the above rules, call the updateUserOfflinePushRule interface.
// Construct ZIMUserOfflinePushRule
ArrayList<Integer> onlinePlatforms = new ArrayList<>();
// When the user logs in on Windows, macOS, and Linux platforms.
ArrayList<Integer> onlinePlatforms = new ArrayList<>();
onlinePlatforms.add(ZIMPlatformType.WIN.value());
onlinePlatforms.add(ZIMPlatformType.MAC_OS.value());
onlinePlatforms.add(ZIMPlatformType.LINUX.value());
offlineRule.setOnlinePlatforms(onlinePlatforms);
// The user does not receive offline push on the iPhoneOS, iPadOS, and Android platforms.
ArrayList<Integer> notToReceiveOfflinePushPlatforms = new ArrayList<>();
notToReceiveOfflinePushPlatforms.add(ZIMPlatformType.IPHONE_OS.value());
notToReceiveOfflinePushPlatforms.add(ZIMPlatformType.IPAD_OS.value());
notToReceiveOfflinePushPlatforms.add(ZIMPlatformType.ANDROID.value());
offlineRule.setNotToReceiveOfflinePushPlatforms(notToReceiveOfflinePushPlatforms);
// Master switch for offline push, enabled by default (supported from version 3.3.0)
offlineRule.setOfflinePushEnabled(true);
// Switch for message offline push, only affects message offline push, enabled by default (supported from version 3.3.0)
offlineRule.setMessageOfflinePushEnabled(true);
// Switch for call offline push, only affects call offline push, enabled by default (supported from version 3.3.0)
offlineRule.setCallOfflinePushEnabled(true);
// Call the updateUserOfflinePushRule method
ZIM.getInstance().updateUserOfflinePushRule(offlineRule, new ZIMUserOfflinePushRuleUpdatedCallback() {
@Override
public void onUserOfflinePushRuleUpdated(ZIMUserOfflinePushRule updatedOfflinePushRule, ZIMError errorInfo) {
}
});Set the do-not-disturb time rule
Starting from version 3.3.0, ZIMUserOfflinePushRule supports setting the do-not-disturb time rule through the doNotDisturbRule field. While the rule is in effect, neither message nor call offline push notifications are delivered.
When calling the updateUserOfflinePushRule interface, the offline push rule is fully updated according to the member attributes of the passed object. To modify a single configuration item such as the do-not-disturb time rule, first call querySelfUserInfo to query the current complete offline push rule, then modify it and submit it in full, so as to avoid overwriting other existing configurations.
The fields of ZIMUserOfflinePushDoNotDisturbRule are described as follows:
| Field | Description |
|---|---|
| enabled | Whether to enable the do-not-disturb rule. |
| startHour / startMinute | Start time of the do-not-disturb period. The hour ranges from [0, 23] and the minute ranges from [0, 59]. |
| endHour / endMinute | End time of the do-not-disturb period. The hour ranges from [0, 23] and the minute ranges from [0, 59]. When the end time is earlier than the start time, the period crosses midnight, for example, from 22:00 to 08:00 the next day. |
| repeatMode | Repeat mode:
Unknown (not set), in which case the SDK reports 0 to the server and the rule only takes effect on the day it is saved (no repeat). |
| customRepeatDays | Custom repeat days in bitmask format, where bit0 represents Monday and bit6 represents Sunday. It only takes effect when repeatMode is Custom. |
| onceEndTimestamp | When repeatMode is None, the UNIX timestamp (in seconds) of the end of the do-not-disturb period that takes effect only once, recorded by the server when the rule is saved. Read-only field: the value passed in when updating the rule is ignored and recalculated by the server. |
| timeZoneID | The IANA time zone ID of the do-not-disturb period, for example, "Asia/Shanghai". An empty string means it is not specified, and the server calculates the period in UTC. When it is not empty, the server validates it (an invalid ID returns an error code) and calculates the period in that time zone (daylight saving time aware). To follow the device time zone, explicitly obtain and pass in the local IANA time zone ID. |
// First query the current complete offline push rule
ZIM.getInstance().querySelfUserInfo(new ZIMSelfUserInfoQueriedCallback() {
@Override
public void onSelfUserInfoQueried(ZIMSelfUserInfo selfUserInfo, ZIMError errorInfo) {
if (errorInfo.code == ZIMErrorCode.SUCCESS) {
ZIMUserOfflinePushRule offlineRule = selfUserInfo.userRule.offlinePushRule;
// Modify the do-not-disturb time rule (supported from version 3.3.0)
ZIMUserOfflinePushDoNotDisturbRule doNotDisturbRule = new ZIMUserOfflinePushDoNotDisturbRule();
doNotDisturbRule.setEnabled(true);
// Do-not-disturb period: 22:00 every day to 08:00 the next day
doNotDisturbRule.setStartHour(22);
doNotDisturbRule.setStartMinute(0);
doNotDisturbRule.setEndHour(8);
doNotDisturbRule.setEndMinute(0);
// Repeat every day
doNotDisturbRule.setRepeatMode(ZIMUserOfflinePushDoNotDisturbRepeatMode.DAILY);
// Time zone. It is recommended to explicitly pass in the local IANA time zone ID
doNotDisturbRule.setTimeZoneID("Asia/Shanghai");
offlineRule.setDoNotDisturbRule(doNotDisturbRule);
// Fully update the offline push rule
ZIM.getInstance().updateUserOfflinePushRule(offlineRule, new ZIMUserOfflinePushRuleUpdatedCallback() {
@Override
public void onUserOfflinePushRuleUpdated(ZIMUserOfflinePushRule updatedOfflinePushRule, ZIMError errorInfo) {
}
});
}
}
});Query user-defined push rules
By calling querySelfUserInfo, you can get the current user-defined offline push rules in the selfUserInfo.userRule.offlinePushRule field in the callback.
ZIM.getInstance().querySelfUserInfo(new ZIMSelfUserInfoQueriedCallback() {
@Override
public void onSelfUserInfoQueried(ZIMSelfUserInfo selfUserInfo, ZIMError errorInfo) {
selfUserInfo.userRule.offlinePushRule; // Current user-defined offline push rules
}
});