Alipay International Mini Program Development PlatformAlipay International Mini Program Development PlatformDOCS

my.closeSocket

Use this API to close the WebSocket connection.

Prerequisites:

  • Supported SDK versions：
    • Android: 2.67.0
    • iOS: 2.80.0
  • Supported types of mini programs: DSL

Sample code

copy
// close connection normally 
my.closeSocket({
  success: (res) => {
    console.log('Succeed to close connection');
  },
  fail: (err) => {
    console.log('Failed to to close connection:', err.errorMessage);
  }
});

// Customize the status and reason of connection close
my.closeSocket({
  code: 1000,
  reason: 'the user exits actively'
});

Parameters

Property

Type

Required

Description

code

Number

No

The close status code of the WebSocket connection.

Valid value:

  • 1000：this is the default value. Indicates the connection is closed normally. Or
  • 3000 ~ 4999: customize the close status code.

reason

String

No

The close reason of the WebSocket connection.

success

Function

No

The callback function for a successful API call.

fail

Function

No

The callback function for a failed API call.

complete

Function

No

The callback function used when the API call is completed. This function is always executed no matter the call succeeds or fails.

success/fail/complete callback function

The following table provides the properties in the success/fail/complete callback function:

Property

Data type

Description

error

Number

The error code. 0 indicates success. For more information, see the following Error code section.

errorMessage

String

The error message.

Error codes

Error code

Error message

Further action

2

Code can only be 1000, or between 3000 and 4999

The close status code of the WebSocket connection can only be 1000 or between 3000 and 4999. Check the code parameter carefully.

FAQs

When is it necessary to manually close a WebSocket connection?

It is recommended to actively close the connection in the following scenarios:

  • When the page is destroyed or unloaded
  • When the user logs out
  • When the business process is complete
  • When switching pages

For more information, see the my.closeSocket JSAPI.

Sample code：

copy
Page({
  onUnload() {
    // close the connection when the page is unloaded
    my.closeSocket({
      code: 1000,
      reason: 'page unload'
    });
  }
});

How to define the close status code of the WebSocket connection (the code parameter of the my.closeSocket JSAPI)?

The close status code of the WebSocket connection can only be:

  • 1000：this is the default value. Indicates the connection is closed normally. Or
  • 3000 ~ 4999: customize the close status code.

For more information, check the code parameter of the my.closeSocket JSAPI.

Sample code：

copy
// the connection is closed normally when the business task is complete
my.closeSocket({
  code: 1000,
  reason: 'task completed'
});

// the connection is closed because the user leaves actively
my.closeSocket({
  code: 3000,
  reason: 'user leave'
});

What event is triggered after the WebSocket connection is closed?

The onSocketClose event is triggered after calling closeSocket. For more information, see the my.closeSocket and my.onSocketClose JSAPI.

Sample code：

copy
// close the connection normally
my.closeSocket({
  code: 1000,
  reason: 'normally close'
});

// listen to the Sockect close event 
my.onSocketClose(function(res) {
  console.log('Connection is closed');
  console.log('Close status code:', res.code);
  console.log('Close reason:', res.reason);
});

What occurs when my.closeSocket is invoked before the connection is established?

If no WebSocket connection is currently active, a prompt message will be returned.

Sample code：

copy
my.closeSocket({
  complete: (res) => {
    if (res.message === 'No websocket connection is established') {
      console.log('currently there is no connection to close');
    }
  }
});

How to make sure the WebSocket connection is fully closed?

It is recommended to use the onSocketClose event to confirm that the connection has been closed. For more information, see the my.onSocketClose JSAPI.

Sample code：

copy
function closeWebSocket() {
  return new Promise((resolve) => {
    my.onSocketClose(function(res) {
      console.log('confirmed that the connection has been closed');
      resolve(true);
    });
    
    my.closeSocket({
      code: 1000,
      reason: 'cleanup'
    });
    
    // timeout
    setTimeout(() => resolve(false), 5000);
  });
}