Migration_v4.x topic

This document aims to help users understand the APIs changes and feature improvements, and provide a migration guide for the upgrade process.


It is an incompatible change if marked with breaking changes. All remaining changes is compatible and uses the deprecated prompt. Of course, it will also be completely abandoned in the version after a certain period of time.


You can run this command in the root directory of your project to output warnings and partial error prompts to assist you in finding deprecated parameters/functions or errors after upgrading.

dart analyze | grep zego


Versions



4.8.0


Introduction

In this migration guide, we will explain how to upgrade from version 4.7.+ to the latest 4.8.0 version.

Major Interface Changes

  • ZegoCallAudioVideoViewConfig

    • add audioVideoViewCreator in ZegoCallAudioVideoContainerBuilder(type of containerBuilder)
    Migrate Guide

    Modify your code based on the following guidelines to make it compatible with version 4.8.0:

    4.7.+ Version Code:

    typedef ZegoCallAudioVideoContainerBuilder = Widget Function(
     BuildContext,
     List<ZegoUIKitUser> allUsers,
     List<ZegoUIKitUser> audioVideoUsers,
    );
    

    4.8.0 Version Code:

    typedef ZegoCallAudioVideoContainerBuilder = Widget? Function(
    BuildContext context,
    List<ZegoUIKitUser> allUsers,
    List<ZegoUIKitUser> audioVideoUsers,
    
    /// The default audio-video view creator, you can also use [ZegoAudioVideoView] as a child control to continue encapsulating
    ZegoAudioVideoView Function(ZegoUIKitUser) audioVideoViewCreator,
    );
    


4.4.0


Introduction

In this migration guide, we will explain how to upgrade from version 4.3.2 to the latest 4.4.0 version.

Major Interface Changes

  • ZegoUIKitPrebuiltCallConfig
    • move hangUpConfirmDialogInfo to hangUpConfirmDialog?.dialogInfo


4.2.0


Introduction

In this migration guide, we will explain how to upgrade from version 4.1.10 to the latest 4.2.0 version.

Major Interface Changes

  • ZegoCallInvitationUIConfig
    • move showDeclineButton to declineButton.visible
    • move showCancelInvitationButton to cancelButton.visible
  • ZegoCallRingtoneConfig
    • remove useless parameters packageName


4.1.10


Introduction

In this migration guide, we will explain how to upgrade from version 4.1.9 to the latest 4.1.10 version.

Major Interface Changes

  • rename ZegoUIKitCallEndReason to ZegoCallEndReason
  • rename ZegoUIKitCallHangUpConfirmationEvent to ZegoCallHangUpConfirmationEvent
  • rename ZegoUIKitCallEndEvent to ZegoCallEndEvent
  • rename ZegoUIKitPrebuiltCallRoomEvents to ZegoCallRoomEvents
  • rename ZegoUIKitPrebuiltCallAudioVideoEvents to ZegoCallAudioVideoEvents
  • rename ZegoUIKitPrebuiltCallUserEvents to ZegoCallUserEvents
  • rename CallEndCallback to ZegoCallEndCallback
  • rename CallHangUpConfirmationCallback to ZegoCallHangUpConfirmationCallback
  • rename ZegoMenuBarStyle to ZegoCallMenuBarStyle
  • rename ZegoAndroidNotificationConfig to ZegoCallAndroidNotificationConfig
  • rename ZegoIOSNotificationConfig to ZegoCallIOSNotificationConfig
  • rename ZegoRingtoneConfig to ZegoCallRingtoneConfig
  • rename PrebuiltConfigQuery to ZegoCallPrebuiltConfigQuery
  • rename ZegoInvitationType to ZegoCallType
  • rename ZegoMiniOverlayPage to ZegoUIKitPrebuiltCallMiniOverlayPage
  • move API in ZegoUIKitPrebuiltCallController().invitation to ZegoUIKitPrebuiltCallInvitationService()
Migrate Guide

Modify your code based on the following guidelines to make it compatible with version 4.1.10:

4.1.9 Version Code:

/// Example code in version 4.1.9
/// ...
ZegoUIKitPrebuiltCallController().invitation.send(...);
ZegoUIKitPrebuiltCallController().invitation.cancel(...);
ZegoUIKitPrebuiltCallController().invitation.reject(...);
ZegoUIKitPrebuiltCallController().invitation.accept(...);

4.1.10 Version Code:

/// Example code in version 4.1.10
/// ...
ZegoUIKitPrebuiltCallInvitationService().send(...);
ZegoUIKitPrebuiltCallInvitationService().cancel(...);
ZegoUIKitPrebuiltCallInvitationService().reject(...);
ZegoUIKitPrebuiltCallInvitationService().accept(...);


4.1.9


Introduction

In this migration guide, we will explain how to upgrade from version 4.1.8 to the latest 4.1.9 version.

Major Interface Changes

  • rename PrebuiltCallMiniOverlayPageState to ZegoCallMiniOverlayPageState
  • ZegoUIKitPrebuiltCallConfig
    • class name
      • rename ZegoMenuBarButtonName to ZegoCallMenuBarButtonName
      • rename ZegoPrebuiltAudioVideoViewConfig to ZegoCallAudioVideoViewConfig
      • rename ZegoTopMenuBarConfig to ZegoCallTopMenuBarConfig
      • rename ZegoBottomMenuBarConfig to ZegoCallBottomMenuBarConfig
      • rename ZegoMemberListConfig to ZegoCallMemberListConfig
      • rename ZegoInRoomChatViewConfig to ZegoCallInRoomChatViewConfig
      • rename ZegoHangUpConfirmDialogInfo to ZegoCallHangUpConfirmDialogInfo
    • variable name
      • rename videoConfig to video
      • rename audioVideoViewConfig to audioVideoView
      • rename topMenuBarConfig to topMenuBar
      • rename bottomMenuBarConfig to bottomMenuBar
      • rename memberListConfig to memberList
      • rename beautyConfig to beauty
      • rename chatViewConfig to chatView
      • move audioVideoContainerBuilder to audioVideoView.containerBuilder


4.1.4


Introduction

In this migration guide, we will explain how to upgrade from version 4.1.3 to the latest 4.1.4 version.

Major Interface Changes

onHangUpConfirmation

  • add defaultAction in onHangUpConfirmation (💥 breaking changes)
Migrate Guide

Modify your code based on the following guidelines to make it compatible with version 4.1.4:

4.1.3 Version Code:

/// Example code in version 4.1.3
/// ...
events: ZegoUIKitPrebuiltCallEvents(
  onHangUpConfirmation: (
    BuildContext context,
  ) {
    debugPrint('onHangUpConfirmation, do whatever you want');

    ...show you confirm dialog 

    return dialog result;
  },
),

4.1.4 Version Code:

/// Example code in version 4.1.4
/// ...
events: ZegoUIKitPrebuiltCallEvents(
  onHangUpConfirmation: (
    ZegoUIKitCallHangUpConfirmationEvent event,
    Future<bool> Function() defaultAction,
  ) {
    debugPrint('onHangUpConfirmation, do whatever you want');

    /// you can call this defaultAction to return to the previous page,
    return defaultAction.call();
  },
),
  • parameter prototype:
class ZegoUIKitCallHangUpConfirmationEvent {
  BuildContext context;
}





4.0.0

The 4.0 version has standardized and optimized the API and Event, simplifying the usage of most APIs.

Most of the changes involve modifications to the calling path, such as:

  • Changing from ZegoUIKitPrebuiltCallController().isMinimizing() to ZegoUIKitPrebuiltCallController().minimize.isMinimizing.
  • Move the event callback in the ZegoUIKitPrebuiltCallConfig to the Event.

After upgrading the call kit, you can refer to the directory index to see how specific APIs from the old version can be migrated to the new version.



Introduction

In this migration guide, we will explain how to upgrade from version 3.x to the latest 4.0 version. This document aims to help users understand the interface changes and feature improvements, and provide a migration guide for the upgrade process.

Major Interface Changes

ZegoUIKitPrebuiltCall

  • remove controller, ZegoUIKitPrebuiltCallController is now accessed through a singleton and does not require any parameters to be passed. (💥 breaking changes)
Migrate Guide

Modify your code based on the following guidelines to make it compatible with version 4.0:

3.x Version Code:

class CallPage extends StatefulWidget {
 const CallPage({Key? key}) : super(key: key);

 @override
 State<StatefulWidget> createState() => CallPageState();
}

class CallPageState extends State<CallPage> {
 ZegoUIKitPrebuiltCallController? callController;

 @override
 void initState() {
   super.initState();
   callController = ZegoUIKitPrebuiltCallController();
 }

 @override
 void dispose() {
   super.dispose();

   callController = null;
 }

 void doSomething() {
   callController?.xxx();
 }

 @override
 Widget build(BuildContext context) {
   return ZegoUIKitPrebuiltCall(
       ...
       callController: callController,
   );
 }
}

4.0 Version Code:

class CallPage extends StatefulWidget {
 const CallPage({Key? key}) : super(key: key);

 @override
 State<StatefulWidget> createState() => CallPageState();
}

class CallPageState extends State<CallPage> {
 void doSomething() {
   ZegoUIKitPrebuiltCallController().xxx();
 }

 @override
 Widget build(BuildContext context) {
   return ZegoUIKitPrebuiltCall(
     ...
   );
 }
}

ZegoUIKitPrebuiltCallInvitationService

init (💥 breaking changes)

For the purpose of clarity and future extensibility, the parameters have been categorized.

  • adding events, which is used to listen for events within a call. please note that this is not related to invitation events.
  • invitation-related events, rename events to invitationEvents
  • move showDeclineButton and showCancelInvitationButton to uiConfig
  • move appName, certificateIndex and isIOSSandboxEnvironment to notificationConfig.iOSNotificationConfig
  • remove controller, ZegoUIKitPrebuiltCallController is now accessed through a singleton and does not require any parameters to be passed.
  • remove notifyWhenAppRunningInBackgroundOrQuit
  • move androidNotificationConfig and iOSNotificationConfig to notificationConfig
Migrate Guide

Modify your code based on the following guidelines to make it compatible with version 4.0:

3.x Version Code:

ZegoUIKitPrebuiltCallInvitationService().init(
   ...
   showDeclineButton: true,
   showCancelInvitationButton: true,
   notifyWhenAppRunningInBackgroundOrQuit: true,
   androidNotificationConfig: ZegoAndroidNotificationConfig(
   
   ),
   iOSNotificationConfig: ZegoIOSNotificationConfig(
   
   ),
   certificateIndex: ZegoSignalingPluginMultiCertificate.firstCertificate,
   appName: '',
   isIOSSandboxEnvironment: false,
   
   events: ZegoUIKitPrebuiltCallInvitationEvents(
       onError:(_) {
       
       }
   ),
);

4.0 Version Code:

ZegoUIKitPrebuiltCallInvitationService().init(
   ...
   uiConfig: ZegoCallInvitationUIConfig(
   showDeclineButton: true,
   showCancelInvitationButton: true,
   ),
   notificationConfig: ZegoCallInvitationNotificationConfig(
       androidNotificationConfig: ZegoAndroidNotificationConfig(
       
       ),
       iOSNotificationConfig: ZegoIOSNotificationConfig(
           appName: '',
           certificateIndex: ZegoSignalingPluginMultiCertificate.firstCertificate,
           isIOSSandboxEnvironment: false,
       ),
   ),
   
   invitationEvents: ZegoUIKitPrebuiltCallInvitationEvents(
       onError:(_) {
       
       }
   ),
);

ZegoUIKitPrebuiltCallMiniOverlayMachine(ZegoMiniOverlayMachine) (💥 breaking changes)

The related APIs are no longer exported externally, the original APIs have been transferred to ZegoUIKitPrebuiltCallController.minimize .

  • move switchToIdle from ZegoUIKitPrebuiltCallMiniOverlayMachineto ZegoUIKitPrebuiltCallController.minimize.hide
  • to prevent internal logic errors caused by state switching outside, deprecated the changeState function
  • add ZegoUIKitPrebuiltCallController.minimize.state
  • add ZegoUIKitPrebuiltCallController.minimize.isMinimizing
Migrate Guide

Modify your code based on the following guidelines to make it compatible with version 4.0:

3.x Version Code:

/// Example code in version 3.x
/// 1.
ZegoUIKitPrebuiltCallMiniOverlayMachine().changeState(
 PrebuiltCallMiniOverlayPageState.idle,
);
/// 2.
ZegoUIKitPrebuiltCallMiniOverlayMachine().switchToIdle();
/// 3.
ZegoUIKitPrebuiltCallMiniOverlayInternalMachine().isMinimizing;
/// 4.
ZegoUIKitPrebuiltCallMiniOverlayInternalMachine().state();

4.0 Version Code:

/// 1.
ZegoUIKitPrebuiltCallController().minimize.hide();
/// 2.
ZegoUIKitPrebuiltCallController().minimize.hide();
/// 3.
ZegoUIKitPrebuiltCallController().minimize.isMinimizing;
/// 4.
ZegoUIKitPrebuiltCallController().minimize.state;

Controller

In version 3.x, the ZegoUIKitPrebuiltCallController required declaring the variable and passing either a ZegoUIKitPrebuiltCall instance or initializing it within the ZegoUIKitPrebuiltCallInvitationService().init method.

However, in version 4.0, the ZegoUIKitPrebuiltCallController has been changed to a singleton pattern.

This means that you no longer need to declare a separate variable and pass parameters.

Instead, you can directly access the singleton instance and make calls to it.

Migrate Guide

Modify your code based on the following guidelines to make it compatible with version 4.0:

3.x Version Code:

/// Example code in version 3.x
/// ...
ZegoUIKitPrebuiltCallController controller;

/// assign controller to ZegoUIKitPrebuiltCallInvitationService().init
ZegoUIKitPrebuiltCallInvitationService().init(
   ...
   controller:controller,
   ...
);
/// or, assign controller to ZegoUIKitPrebuiltCall
ZegoUIKitPrebuiltCall(
   ...
   controller:controller,
   ...
)

controller.xxx(...);

4.0 Version Code:

/// Example code in version 4.0
/// ...
ZegoUIKitPrebuiltCallController().xxx(...);

screenSharingViewController

  • move screenSharingViewController from ZegoUIKitPrebuiltCallControllerto ZegoUIKitPrebuiltCallController.screenSharing and rename to viewController
Migrate Guide

Modify your code based on the following guidelines to make it compatible with version 4.0:

3.x Version Code:

/// Example code in version 3.x
/// ...
ZegoUIKitPrebuiltCallController controller;

...assign controller to ZegoUIKitPrebuiltCallInvitationService().init/ZegoUIKitPrebuiltCall

controller.screenSharingViewController.xxx(...);

4.0 Version Code:

/// Example code in version 4.0
/// ...
ZegoUIKitPrebuiltCallController().screenSharing.viewController.xxx(...);

showScreenSharingViewInFullscreenMode

  • move showScreenSharingViewInFullscreenMode from ZegoUIKitPrebuiltCallControllerto ZegoUIKitPrebuiltCallController.screenSharing
Migrate Guide

Modify your code based on the following guidelines to make it compatible with version 4.0:

3.x Version Code:

/// Example code in version 3.x
/// ...
ZegoUIKitPrebuiltCallController controller;

...assign controller to ZegoUIKitPrebuiltCallInvitationService().init/ZegoUIKitPrebuiltCall

controller.showScreenSharingViewInFullscreenMode(...);

4.0 Version Code:

/// Example code in version 4.0
/// ...
ZegoUIKitPrebuiltCallController().screenSharing.showScreenSharingViewInFullscreenMode(...);

sendCallInvitation

  • move sendCallInvitation from ZegoUIKitPrebuiltCallControllerto ZegoUIKitPrebuiltCallController.invitation and rename to send
Migrate Guide

Modify your code based on the following guidelines to make it compatible with version 4.0:

3.x Version Code:

/// Example code in version 3.x
/// ...
ZegoUIKitPrebuiltCallController controller;

...assign controller to ZegoUIKitPrebuiltCallInvitationService().init/ZegoUIKitPrebuiltCall

controller.sendCallInvitation(...);

4.0 Version Code:

/// Example code in version 4.0
/// ...
ZegoUIKitPrebuiltCallController().invitation.send(...);

cancelCallInvitation

  • move cancelCallInvitation from ZegoUIKitPrebuiltCallControllerto ZegoUIKitPrebuiltCallController.invitation and rename to cancel
Migrate Guide

Modify your code based on the following guidelines to make it compatible with version 4.0:

3.x Version Code:

/// Example code in version 3.x
/// ...
ZegoUIKitPrebuiltCallController controller;

...assign controller to ZegoUIKitPrebuiltCallInvitationService().init/ZegoUIKitPrebuiltCall

controller.cancelCallInvitation(...);

4.0 Version Code:

/// Example code in version 4.0
/// ...
ZegoUIKitPrebuiltCallController().invitation.cancel(...);

rejectCallInvitation

  • move rejectCallInvitation from ZegoUIKitPrebuiltCallControllerto ZegoUIKitPrebuiltCallController.invitation and rename to reject
Migrate Guide

Modify your code based on the following guidelines to make it compatible with version 4.0:

3.x Version Code:

/// Example code in version 3.x
/// ...
ZegoUIKitPrebuiltCallController controller;

...assign controller to ZegoUIKitPrebuiltCallInvitationService().init/ZegoUIKitPrebuiltCall

controller.rejectCallInvitation(...);

4.0 Version Code:

/// Example code in version 4.0
/// ...
ZegoUIKitPrebuiltCallController().invitation.reject(...);

acceptCallInvitation

  • move acceptCallInvitation from ZegoUIKitPrebuiltCallControllerto ZegoUIKitPrebuiltCallController.invitation and rename to accept
Migrate Guide

Modify your code based on the following guidelines to make it compatible with version 4.0:

3.x Version Code:

/// Example code in version 3.x
/// ...
ZegoUIKitPrebuiltCallController controller;

...assign controller to ZegoUIKitPrebuiltCallInvitationService().init/ZegoUIKitPrebuiltCall

controller.acceptCallInvitation(...);

4.0 Version Code:

/// Example code in version 4.0
/// ...
ZegoUIKitPrebuiltCallController().invitation.accept(...);

isMinimizing => minimize.isMinimizing

  • move isMinimizing from ZegoUIKitPrebuiltCallControllerto ZegoUIKitPrebuiltCallController.minimize
Migrate Guide

Modify your code based on the following guidelines to make it compatible with version 4.0:

3.x Version Code:

/// Example code in version 3.x
/// ...
ZegoUIKitPrebuiltCallController controller;

...assign controller to ZegoUIKitPrebuiltCallInvitationService().init/ZegoUIKitPrebuiltCall

if(controller.isMinimizing) {

}

4.0 Version Code:

/// Example code in version 4.0
/// ...
if(ZegoUIKitPrebuiltCallController().minimize.isMinimizing) {

}

Events

ZegoUIKitPrebuiltCallConfig

onError (💥 breaking changes)

  • move onError from ZegoUIKitPrebuiltCallConfigto ZegoUIKitPrebuiltCallEvents.onError
Migrate Guide

Modify your code based on the following guidelines to make it compatible with version 4.0:

3.x Version Code:

/// Example code in version 3.x
/// ...
ZegoUIKitPrebuiltCallInvitationService().init(
   ...
   config: ZegoUIKitPrebuiltCallConfig(
       onError: (error){
       
       }
   ),
)

4.0 Version Code:

/// Example code in version 4.0
/// ...
ZegoUIKitPrebuiltCallInvitationService().init(
   ...
   events: ZegoUIKitPrebuiltCallEvents(
       onError: (error){
       
       }
   ),
)

onHangUpConfirmation (💥 breaking changes)

  • move onHangUpConfirmation from ZegoUIKitPrebuiltCallConfigto ZegoUIKitPrebuiltCallEvents.onHangUpConfirmation
Migrate Guide

Modify your code based on the following guidelines to make it compatible with version 4.0:

3.x Version Code:

/// Example code in version 3.x
/// ...
ZegoUIKitPrebuiltCallInvitationService().init(
   ...
   config: ZegoUIKitPrebuiltCallConfig(
       onHangUpConfirmation: (context){
       
       }
   ),
)

4.0 Version Code:

/// Example code in version 4.0
/// ...
ZegoUIKitPrebuiltCallInvitationService().init(
   ...
   events: ZegoUIKitPrebuiltCallEvents(
       onHangUpConfirmation: (context){
       
       }
   ),
)

onHangUp/onOnlySelfInRoom/onMeRemovedFromRoom (💥 breaking changes)

Due to the fact that all three events indicate the end of a call, they will be consolidated into ZegoUIKitPrebuiltCallEvents.onCallEnd and differentiated by the ZegoUIKitCallEndEvent.reason.

And you can use defaultAction.call() to perform the internal default action, which returns to the previous page.

  • move onHangUp from ZegoUIKitPrebuiltCallConfig to ZegoUIKitPrebuiltCallEvents.onCallEnd(ZegoUIKitCallEndEvent(reason:ZegoUIKitCallEndReason.localHangUp), defaultAction)
  • move onOnlySelfInRoom from ZegoUIKitPrebuiltCallConfigto ZegoUIKitPrebuiltCallEvents.onCallEnd(ZegoUIKitCallEndEvent(reason:ZegoUIKitCallEndReason.remoteHangUp), defaultAction)
  • move onMeRemovedFromRoom from ZegoUIKitPrebuiltCallConfigto ZegoUIKitPrebuiltCallEvents.onCallEnd(ZegoUIKitCallEndEvent(reason:ZegoUIKitCallEndReason.kickOut), defaultAction)
Defines
typedef CallEndCallback = void Function(
   ZegoUIKitCallEndEvent event,

   /// defaultAction to return to the previous page
   VoidCallback defaultAction,
);
class ZegoUIKitCallEndEvent {
 /// the user ID of who kick you out
 String? kickerUserID;

 /// end reason
 ZegoUIKitCallEndReason reason;

 ZegoUIKitCallEndEvent({
   required this.reason,
   this.kickerUserID,
 });
}

/// The default behavior is to return to the previous page.
///
/// If you override this callback, you must perform the page navigation
/// yourself to return to the previous page!!!
/// otherwise the user will remain on the current call page !!!!!
enum ZegoUIKitCallEndReason {
 /// the call ended due to a local hang-up
 localHangUp,

 /// the call ended when the remote user hung up, leaving only one local user in the call
 remoteHangUp,

 /// the call ended due to being kicked out
 kickOut,
}
Migrate Guide

Modify your code based on the following guidelines to make it compatible with version 4.0:

3.x Version Code:

/// Example code in version 3.x
/// ...
ZegoUIKitPrebuiltCallInvitationService().init(
   ...
   config: ZegoUIKitPrebuiltCallConfig(
       onHangUp: (){
       
       },
       onOnlySelfInRoom: (context){
       
       },
       onMeRemovedFromRoom: (fromUserID){
       
       },
   ),
)

4.0 Version Code:

/// Example code in version 4.0
/// ...
ZegoUIKitPrebuiltCallInvitationService().init(
   ...
   events: ZegoUIKitPrebuiltCallEvents(
       onCallEnd: (event, defaultAction){
           debugPrint('onCallEnd by ${event.reason}, do whatever you want');
           
           switch(event.reason) {
               case ZegoUIKitCallEndReason.localHangUp:
                 // TODO: Handle this case.
               break;
               case ZegoUIKitCallEndReason.remoteHangUp:
                 // TODO: Handle this case.
               break;
               case ZegoUIKitCallEndReason.kickOut:
                 final fromUserID = event.kickerUserID ?? '';
               break;
           }
           
           /// you can call this defaultAction to return to the previous page
           defaultAction.call();
       },
   ),
)

ZegoUIKitPrebuiltCallInvitationEvents

onOutgoingCallRejectedCauseBusy/onOutgoingCallDeclined (💥 breaking changes)

  • adding customData, which is from ZegoUIKitPrebuiltCallController.invitation.reject.

Feedback Channels

If you encounter any issues or have any questions during the migration process, please provide feedback through the following channels:

We appreciate your feedback and are here to help you successfully complete the migration process.

Classes

ZegoUIKitPrebuiltCall APIs Events Configs Migration_v4.x
Call Widget. You can embed this widget into any page of your project to integrate the functionality of a call. You can refer to our documentation, or our sample code.