ZIM Upgrade Guide

This document describes notes and considerations when upgrading the ZIM Web SDK version.

Upgrade Guide for 2.28.0

Changes to Event Callback Timing

Upgrade Guide for 2.21.0

Handling Room Reconnection

If the SDK reconnects WebSocket due to background switch or network issues, it will not automatically rejoin rooms that have already been joined. Developers need to listen to both connectionStateChanged and roomStateChanged events and actively call enterRoom or joinRoom to rejoin rooms.

For detailed handling, refer to: ZIM Room Disconnection Handling.

Upgrade Guide for 2.19.0

sendMediaMessage

Since version 2.19.0, you must use the sendMessage interface to send media messages. The sendMediaMessage interface is deprecated to unify message sending and facilitate future expansion.

In ZIMMessageSendNotification, the message parameter type of the onMediaUploadingProgress callback has changed from ZIMMessage to ZIMMediaMessage, ensuring only media messages trigger this callback. Typescript developers should fix their code according to IDE compilation errors. (Currently, only projects using Typescript and the replyMessage interface may be affected and need to resolve compilation errors.)

const imageMessage: ZIMMessage = {
    type: 11,
    fileLocalPath: File
}

const config: ZIMMessageSendConfig = {
    priority: 1
}

// !mark
const notification: ZIMMessageSendNotification = {
    onMessageAttached: (message: ZIMMessage) => {
        // Developers can listen to this callback for actions before the message is sent
    },
// !mark
    onMessageUploadingProgress: (message: ZIMMediaMessage, currentFileSize: number, totalFileSize: number) => {
        // Media upload progress
    }
}

// !mark
zim.sendMessage(imageMessage, "TO_CONVERSATION_ID", 0, config, notification)
    .then((res: ZIMMessageSentResult) => {
        // Message sent result
    })
    .catch((errorInfo) => {
        // Message send failed
    })

const imageMessage: ZIMMessage = {
    type: 11,
    fileLocalPath: File
}

const config: ZIMMessageSendConfig = {
    priority: 1
}

// !mark
const notification: ZIMMessageSendNotification = {
    onMessageAttached: (message: ZIMMessage) => {
        // Developers can listen to this callback for actions before the message is sent
    },
// !mark
    onMessageUploadingProgress: (message: ZIMMediaMessage, currentFileSize: number, totalFileSize: number) => {
        // Media upload progress
    }
}

// !mark
zim.sendMessage(imageMessage, "TO_CONVERSATION_ID", 0, config, notification)
    .then((res: ZIMMessageSentResult) => {
        // Message sent result
    })
    .catch((errorInfo) => {
        // Message send failed
    })

Upgrade Guide for 2.18.0

Peer-to-Peer Message Receiving Callback

The original peer message receiving callback receivePeerMessage is deprecated. Please use peerMessageReceived instead.

The new callback supports the following:

• When the user is online, you can receive online peer messages via this callback.
• After re-logging into the ZIM SDK, you can receive all peer messages sent during offline periods (up to 7 days).

// New Interface
peerMessageReceived: (zim: ZIM, data: ZIMEventOfConversationMessageReceivedResult) => void;

// Old Interface
receivePeerMessage: (zim: ZIM, data: ZIMEventOfReceiveConversationMessageResult) => void;

// New Interface
peerMessageReceived: (zim: ZIM, data: ZIMEventOfConversationMessageReceivedResult) => void;

// Old Interface
receivePeerMessage: (zim: ZIM, data: ZIMEventOfReceiveConversationMessageResult) => void;

Room Message Receiving Callback

The original room message receiving callback receiveRoomMessage is deprecated. Please use roomMessageReceived instead.

The new callback supports the following:

• When the user is online, you can receive room messages in real-time.
• When the user recovers from offline to online and is still in the room, lost room messages during the offline period will be received via this callback.

// New Interface
roomMessageReceived: (zim: ZIM, data: ZIMEventOfConversationMessageReceivedResult) => void;

// Old Interface
receiveRoomMessage: (zim: ZIM, data: ZIMEventOfReceiveConversationMessageResult) => void;

// New Interface
roomMessageReceived: (zim: ZIM, data: ZIMEventOfConversationMessageReceivedResult) => void;

// Old Interface
receiveRoomMessage: (zim: ZIM, data: ZIMEventOfReceiveConversationMessageResult) => void;

Group Message Receiving Callback

The original group message receiving callback receiveGroupMessage is deprecated. Please use groupMessageReceived instead.

The new callback supports the following:

• When the user is online, you can receive online group messages via this callback.
• After re-logging into the ZIM SDK, you can receive all group messages sent during offline periods (up to 7 days).

// New Interface
groupMessageReceived: (zim: ZIM, data: ZIMEventOfConversationMessageReceivedResult) => void;

// Old Interface
receiveGroupMessage: (zim: ZIM, data: ZIMEventOfReceiveConversationMessageResult) => void;

// New Interface
groupMessageReceived: (zim: ZIM, data: ZIMEventOfConversationMessageReceivedResult) => void;

// Old Interface
receiveGroupMessage: (zim: ZIM, data: ZIMEventOfReceiveConversationMessageResult) => void;

Upgrade Guide for 2.16.0

callCancel

In the new callCancel version, if the userIDs parameter contains one or more userIDs, the interface will only cancel invitations sent to these specific users. If the userIDs parameter is empty, all pending invitations will be cancelled.

In older versions, the callCancel interface cancels invitations for all invitees regardless of whether the userIDs parameter is given or empty.

Since the old ZIM SDK does not support single invitation cancellation, if you need to keep both the cancellation logic of older versions and the single cancellation capability of the new version, please isolate the call feature between old and new ZIM versions.

// Cancel invitations to userIdA and userIdB specifically
const callID = 'xxxx';
const invitees = ['userIdA','userIdB'];  // Invitee userID list
const config: ZIMCallCancelConfig = { extendedData: 'xxxx' }; 
zim.callCancel(invitees, callID, config)
    .then((res: ZIMCallCancelSentResult) => {
        // Operation successful
    })
    .catch((err: ZIMError) => {
        // Operation failed
    })

// Cancel the entire call invitation; succeeds only if all invitees have not accepted
const callID = 'xxxx';
const invitees = [];  // Invitee userID list
const config: ZIMCallCancelConfig = { extendedData: 'xxxx' }; 
zim.callCancel(invitees, callID, config)
    .then((res: ZIMCallCancelSentResult) => {
        // Operation successful
    })
    .catch((err: ZIMError) => {
        // Operation failed
    })

// Cancel invitations to userIdA and userIdB specifically
const callID = 'xxxx';
const invitees = ['userIdA','userIdB'];  // Invitee userID list
const config: ZIMCallCancelConfig = { extendedData: 'xxxx' }; 
zim.callCancel(invitees, callID, config)
    .then((res: ZIMCallCancelSentResult) => {
        // Operation successful
    })
    .catch((err: ZIMError) => {
        // Operation failed
    })

// Cancel the entire call invitation; succeeds only if all invitees have not accepted
const callID = 'xxxx';
const invitees = [];  // Invitee userID list
const config: ZIMCallCancelConfig = { extendedData: 'xxxx' }; 
zim.callCancel(invitees, callID, config)
    .then((res: ZIMCallCancelSentResult) => {
        // Operation successful
    })
    .catch((err: ZIMError) => {
        // Operation failed
    })