Initialization parameters

• Not all initialization parameters are listed here. Please refer to Initialize the SDK, and initialization parameters are given in other chapters.
  • Initialization parameters for connection
  • Initialization parameters for multi-device login
  • Initialization parameters for messages
  • Initialization parameters for team
  • Initialization parameters for user profile
  • Initialization parameters for friendship
  • Initialization parameters for user relationship
  • Initialization parameters for session
  • Initialization parameters for system notifications
  • Synchronization completed
  • Complete initialization codes

Sample codes

javascriptvar nim = NIM.getInstance({
    onofflinesysmsgs: onOfflineSysMsgs,
    onsysmsg: onSysMsg,
    onupdatesysmsg: onUpdateSysMsg,
    onsysmsgunread: onSysMsgUnread,
    onupdatesysmsgunread: onUpdateSysMsgUnread,
    onofflinecustomsysmsgs: onOfflineCustomSysMsgs,
    oncustomsysmsg: onCustomSysMsg,
    syncBroadcastMsgs: true, // is offline broadcast message synchronized, false by default
    onbroadcastmsg: onBroadcastMsg, // receive broadcast message callback
    onbroadcastmsgs: onBroadcastMsgs, // synchronize callback to offline broadcast messages after login
});
function onOfflineSysMsgs(sysMsgs) {
    console.log('receive offline system message’, sysMsgs);
    pushSysMsgs(sysMsgs);
}
function onSysMsg(sysMsg) {
    console.log('receive system notification', sysMsg)
    pushSysMsgs(sysMsg);
}
function onUpdateSysMsg(sysMsg) {
    pushSysMsgs(sysMsg);
}
function pushSysMsgs(sysMsgs) {
    data.sysMsgs = nim.mergeSysMsgs(data.sysMsgs, sysMsgs);
    refreshSysMsgsUI();
}
function onSysMsgUnread(obj) {
    console.log('receive system notification unread', obj);
    data.sysMsgUnread = obj;
    refreshSysMsgsUI();
}
function onUpdateSysMsgUnread(obj) {
    console.log('system notification unread is updated', obj);
    data.sysMsgUnread = obj;
    refreshSysMsgsUI();
}
function refreshSysMsgsUI() {
    // Refresh The API
}
function onOfflineCustomSysMsgs(sysMsgs) {
    console.log('receive offline custom system notification', sysMsgs);
}
function onCustomSysMsg(sysMsg) {
    console.log('receive custom system notification', sysMsg);
}
function onBroadcastMsg(msg) {
    console.log('receive broadcast message', msg);
}
function onBroadcastMsgs(msgs) {
    console.log('receive broadcast message', msgs);
}

Parameter description

• onofflinesysmsgs: It is a callback for synchronizing offline System notification, the array of system notification will be input.
• The simultaneous multi-tab login is enabled at the operation "Support database". If multiple tab pages are disconnected and then reconnected, only one tab page will store offline system notifications, i.e. only one tab page will receive the callback onofflinesysmsgs, while other tab pages need to invoke "Get local system notification" to get system notification from local cache after the operation "Complete synchronization".
• onsysmsg: It is a callback for receiving System notification, system notification will be input.
• After receiving system notification, you need to invoke Mark system notification as read to mark system notification as "read".
• onupdatesysmsg: It is a callback after updating system notification, {@link SystemMessage|system notification} will be input.
  • The callback will be returned in the following conditions:
    • Accept friend application
    • Reject friend application
    • Accept team invitation
    • Reject team invitation
    • Approve team application
    • Reject the application for joining
  • The operation initiator will receive the callback and updated system notifications. The system notifications will be updated to two status by operation type as below:
    • 'passed': Passed
    • 'rejected': Rejected
• onsysmsgunread: It is a callback for receiving unread count of system notifications.
  • SDK will manage unread count of built-in system notifications. The object that is received by the callback includes fields shown as below:
    • friend: Unread count of all system notifications related to friends.
    • addFriend: Unread count of messages for adding as friends.
    • applyFriend: Unread count of messages for applying for friends.
    • passFriendApply: Unread count of messages for accepting friend application.
    • rejectFriendApply: Unread count of messages for rejecting friend application.
    • deleteFriend: Unread count of messages for deleting friends.
    • team: Unread count of all system notifications related to team.
    • teamInvite: Unread count of messages for team invitation.
    • rejectTeamInvite: Unread count of messages for accepting team invitation.
    • applyTeam: Unread count of messages for applying for joining team.
    • rejectTeamApply: Unread count of messages for rejecting team application.
    • deleteMsg: Unread count of recalling messages.
• onupdatesysmsgunread: A callback for updating unread count of system notifications.
• onofflinecustomsysmsgs: It is a callback for synchronizing offline Custom system notification, the array of system notification will be input.
• oncustomsysmsg: It is a callback for receiving Custom system notification, the system notification will be input.
• onbroadcastmsg: A callback for receiving broadcast message (one).
• onbroadcastmsgs: A callback for receiving offline broadcast messages (multiple).

System notification includes:

• Built-in system notification
  • Now, all built-in system notifications are related to advanced team. After operation, members of a team will receive related system notification.
  • The difference between built-in system notification and Team notification message is that system notification is sent to an individual member, while team notification message is sent to all members.
• Custom system notification

System notification object

The system notification object includes fields shown as below:

• time: Timestamp
• type: Type of system notification. It is not available for Custom system notification.
• from: Source of system notification, account or team ID.
• to: Target of system notification, account or team ID.
• idServer: idServer of built-in system notification.
• read: It determines whether built-in system notification is read.
• category: Type of built-in system notification
• state: Status of built-in system notification
• error: If the status of built-in system notification is 'error', the field contains wrong information.
• localCustom: Local custom extension field of built-in system notification.
  • When Support database is available, The API Update local session can be invoked to update the field to local database only, instead of the server
• ps: Postscript of built-in system notification.
• attach: It is the attached information of built-in system notification. Please refer to Type of system notification to view the corresponding attached information of different types of system notifications.
• scene: It is the scene of custom system notification. Please refer to Message scenarios..
• content: Content of Custom system notification.
• isPushable: It determines whether a message is pushed
• apnsText: apns push text of Custom system notification. It is valid only for the receiver with iOS device.
• pushPayload: Push attribute of Custom system notification.
  • We recommend creating user profile in JSON format. If it is not JSON format, other clients may abandon the information, although Web client will receive it ordinaryly.
• needPushNick: It determines whether a nickname is pushed
• sendToOnlineUsersOnly: It determines whether Custom system notification will be sent to online users only.
  • If it is true, custom system notification will be sent to online users only and it is applicable to send immediate notification, for example, "inputting".
  • If it is false and the target user or team is offline, the custom system notification will be sent only when they are online.
  • The parameter is valid for point-to-point custom system notification only, instead of team custom system notification which will be sent to online team members only and not be stored offline.
• cc: It determines whether cc is required for custom system notification.

System notification types

The field type under System notification object is used to indicate type of system notification. It is not available for custom system notification. The detailed types are described as below:

• 'teamInvite' (Team invitation)
  • After team owner and adiministor of an advanced team invite a user to join their team (with Create a team or Invite a user to team), the invited user will receive a System notification of 'teamInvite' type. For such system notification, the field from is account of inviter; the field to is the corresponding team ID; and the field team under attach is the Team that is invited to join in. The invited user can accept or reject invitation.
    • If the invited user selects to "Accept invitation", all team members will receive a Team notification message of 'acceptTeamInvite' type. For such team notification message, the field from is account that accepts team invitation; the field to is the corresponding team ID; the field team under attach is the corresponding Team object; the field members under attach is the list of team members receiving team invitation.
    • If the invited user selects to "Reject invitation", the inviter will receive a System notification of 'rejectTeamInvite' type. For such system notification, the field from is account rejecting team invitation and the field to is the corresponding team ID.
• 'rejectTeamInvite' (Reject team invitation)
  • See 'teamInvite'.
• 'applyTeam' (Apply for joining a group)
  • A user can Apply for joining advanced team, owner and adiministor of the target team will receive a System notification of 'applyTeam' type. For such system notification, the field from is account of the applicant and field to is the corresponding team ID. After receiving the application for joining team, owner and adiministor of the advanced team can accept or reject the application.
    • If they "Accept team application", all team members will receive a Team notification message of 'passTeamApply' type. For such team notification message, the field from is account that accepts team application; the field to is the corresponding team ID; the field team under attach is the corresponding Team object; the field account under attach is account of the applicant; the field members under attach is the list of team members who are approved for team application.
    • If they "Reject a team application", the applicant will receive a System notification of 'rejectTeamApply' type. For such system notification, the field from is account that rejects team application; the field to is the corresponding team ID; the field team under attach is the corresponding Team.
• 'rejectTeamApply' (Reject a team application)
  • See 'applyTeam'.
• 'addFriend'
  • After being added friends, a certain user will be a friend of current login user without confirmation.
  • The user will receive a system notification of 'addFriend' type, of which from field is account of the applicant and to field is the account of the acceptor.
• 'applyFriend'
  • After being applied for friends, a certain user will receive a system notification of'applyFriend' type, of which from field is account of the applicant and to field is the account of the acceptor. After receiving friend application, the user can accept or reject the application.
    • If the current login user accepts friend application, the applicant will receive a system notification of 'passFriendApply' type, of which from field is account of the acceptor and to field is account of the applicant.
    • If the user selects to reject friend application, the applicant will receive a System notification of 'rejectFriendApply' type. For such system notification, the field from is account of rejecter and the field to is account of applicant.
• 'passFriendApply'
  • See 'applyFriend'.
• 'rejectFriendApply'
  • See 'applyFriend'.
• 'deleteFriend'
  • After the current login user deletes friends, the deleted friends will receive a system notification of 'deleteFriend' type, of which field from is account of the user who deletes friends and field to is account of the deleted user.
• 'deleteMsg'
  • After the operation "Revoke message", message receiver will receive a System notification of 'deleteMsg' type. For such system notification, msg is the field of deleted message. If it is a team message, all team members will receive the system notification. If a same account logins on multiple clients, other clients will receive the system notification.
• 'custom'
  • Custom system notification

Type of built-in system notifications

instead of 'custom' in above-mentioned Type of system notification, others are built-in system notification which are classified into two types.

• 'team'
• 'friend'

Status of built-in system notifications

• 'init': Unprocessed status
• 'passed': Passed
• 'rejected': Rejected
• 'error': Error

Process system notifications

It is involved in friends processing, so it shall be merged with Friendship management.

javascriptfunction handleSysMsgs(sysMsgs) {
    if (!Array.isArray(sysMsgs)) {sysMsgs=[sysMsgs];}
    sysMsgs.forEach(function(sysMsg) {
        var idServer = sysMsg.idServer;
        switch (sysMsg.type) {
        case 'addFriend':
            onAddFriend(sysMsg.friend);
            break;
        case 'applyFriend':
            break;
        case 'passFriendApply':
            onAddFriend(sysMsg.friend);
            break;
        case 'rejectFriendApply':
            break;
        case 'deleteFriend':
            onDeleteFriend(sysMsg.from);
            break;
        case 'applyTeam':
            break;
        case 'rejectTeamApply':
            break;
        case 'teamInvite':
            break;
        case 'rejectTeamInvite':
            break;
        default:
            break;
        }
    });
}

Mark system notifications as read

• After receiving system notification, SDK will update unread count of system notifications. Developers need to invoke The API to notify SDK to mark a system notification as read, which will trigger the callback onupdatesysmsgunread.
• sysMsgs is system notification or array of system notification that is received with onofflinesysmsgs or onsysmsg.

javascriptnim.markSysMsgRead({
    sysMsgs: someSysMsg, // or [someSysMsg]
    done: markSysMsgReadDone
});
function markSysMsgReadDone(error, obj) {
    console.log(error);
    console.log(obj);
    console.log('mark system notification as read' + (!error?'succeeded':'failed'));
}

Get local system notifications

• At the operation "Support database", SDK will store built-in system notifications in database.
• If developers find that the number of unread count of system notifications is larger than the number of system notifications, some unread system notifications may be stored in database and shall be acquired from a local database.
• All types of system notifications are acquired by default. The parameter category can be input to limit Type of system notifications.
• All types of system notifications are acquired by default. The parameter type can be input to limit Type of system notifications.
• All read and unread system notifications are acquired by default. The parameter read can be input to limit read status.
  • If no parameter is input, all read and unread system notifications are acquired by default.
  • If true is input, only read system notifications are acquired.
  • If false is input, only unread system notifications are acquired.
• lastIdServer Is idServer of the last system notification in last query. It is not required for the first query.
• limit Is the limit of queried message count. The max. count is 100 and default value is 100.
• By default, local system notifications are queried forward starting from the recent system notification. The parameter reverse=true can be input to query local system notification backward starting from the first notification.

javascriptnim.getLocalSysMsgs({
    lastIdServer: 'lastIdServer',
    limit: 100,
    done: getLocalSysMsgsDone
});
function getLocalSysMsgsDone(error, obj) {
    console.log(error);
    console.log(obj);
    console.log('get local system notification' + (!error?'succeeded':'failed'));
    if (!error) {
        console.log(obj.sysMsgs);
    }
}

Update local system notifications

• It is to update local system notification of idServer.
• If it does not support database, it is successful.
• If there is no related system message, it is successful and will return null.
• These fields will be updated to local database, instead of the server.

javascriptnim.updateLocalSysMsg({
    idServer: '1234',
    status: 'bingo',
    localCustom: '{"key","value"}',
    done: updateLocalSysMsgDone
});
function updateLocalSysMsgDone(error, obj) {
    console.log(error);
    console.log(obj);
    console.log('update local system notification' + (!error?'succeeded':'failed'));
}

Delete local system notifications

• It is to delete local system notification of idServer.
• If it does not support database, it is successful.
• If there is no related system message, it is successful.

javascriptnim.deleteLocalSysMsg({
    idServer: '1234',
    done: deleteLocalSysMsgDone
});
function deleteLocalSysMsgDone(error, obj) {
    console.log(error);
    console.log(obj);
    console.log('delete local system notification' + (!error?'succeeded':'failed'));
}

Delete all local system notifications

• If it does not support database, it is successful.
• It will clear unread count of system notifications, and developers will receive onupdatesysmsgunread.

javascriptnim.deleteAllLocalSysMsgs({
    done: deleteAllLocalSysMsgsDone
});
function deleteAllLocalSysMsgsDone(error, obj) {
    console.log(error);
    console.log(obj);
    console.log('delete all local system notifications' + (!error?’succeeded':'failed'));
}

Custom system notification

• Developers can send custom system notification to other online users or teams only. If they need to send notification to offline users, the parameter sendToOnlineUsersOnly=false shall be configured. Please refer to the following sample code.
• Difference between custom system notification and custom message:
  • A custom message is a Message, which will be stored in CommsEase database and shall be shown to users together with other messages.
  • A custom system notification is a System notification, which is used for notifying the third party itself and will not be stored in CommsEase database. SDK will not resolve such notification, but only transmit such notification.
• SDK will neither store custom system notification nor manage unread count of custom system notifications.

• Optional parameters include:
  • yidunEnable: It designates whether it is necessary to use custom anti-spam field, i.e. antiSpamContent. The default value is false which means that it is not required.
  • antiSpamContent: When yidunEnable is enabled, developers customize anti-spam field with json format {"type": 1, "data": "custom content"}. Notes: type: 1. Text; 2. Image, 3. Video; data content: text or image address or video address.

javascriptvar content = {
    type: 'type',
    value: 'value'
};
content = JSON.stringify(content);
var msgId = nim.sendCustomSysMsg({
    scene: 'p2p',
    to: 'account',
    content: content,
    sendToOnlineUsersOnly: false,
    apnsText: content,
    done: sendCustomSysMsgDone
});
console.log('sending p2p custom system notification, id=' + msgId);
function sendCustomSysMsgDone(error, msg) {
    console.log('send' + msg.scene + 'custom system notification' + (!error?'succeeded':'failed') + ', id=' + msg.idClient);
    console.log(error);
    console.log(msg);
}

Broadcast messages

• Users can send broadcast messages with app servers. All designated online users in the specific app will receive broadcast packages. In addition, broadcast messages supports offline storage. The validity period can be set. 7 days are the maximum period. A single app can store up to 100 recent broadcast messages when users are offline.
• Parameters of broadcast messages:
  • broadcastId: Broadcast message ID
  • body: Broadcast message body
  • fromAccid: Account of sending the broadcast messages
  • time: Timestamp for sending broadcast messages