Mobile Platform as a Service:Network

my.request

Makes a network request from a miniapp.

• The my.request API currently supports the GET, POST, and DELETE methods.

• The my.request API currently supports only HTTPS requests.

For more information, see my.request FAQ.

Usage notes:

• Enable the Permission control switch in Release Mini Program > Open Platform Mini Program Management. Then, configure the domain name whitelist in Server domain name whitelist. The miniapp can communicate only with domain names in the whitelist when calling APIs such as HTTP requests (my.request) and file uploads (my.uploadFile).

• After you add a domain name to the server domain name whitelist, you must repackage, upload, and generate a trial version for the change to take effect.

• When you debug in the IDE, use a real device for the preview.

Input parameters

data parameter description

Data sent to the server is ultimately converted to a string. If the data is not a string, it is converted based on the following rules:

• If the method is GET, the data is converted to a query string: encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)....

• If the method is POST and headers['content-type'] is application/json, the data is serialized to JSON.

• If the method is POST and headers['content-type'] is application/x-www-form-urlencoded, the data is converted to a query string: encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)....

referer description

• You cannot set the referer header of a network request.

• Its format is fixed as https://urlhost/{appid}/{version}/page-frame.html, where {appid} is the APPID of the miniapp and {version} is the version number of the miniapp.

success return value

Error codes

If a my.request call returns You are not authorized to call this interface, configure the domain name whitelist in Open Platform Mini Program Management > Server domain name whitelist.

Code example

This example is for reference only. You must use your own address for testing.

my.request({
  url: 'https://example.org/post',
  method: 'POST',
  data: {
    from: 'Alipay',
    production: 'AlipayJSAPI',
  },
  dataType: 'json',
  success: function(res) {
    my.alert({content: 'success'});
  },
  fail: function(res) {
    my.alert({content: 'fail'});
  },
  complete: function(res) {
    my.hideLoading();
    my.alert({content: 'complete'});
  }
});

// Returns a RequestTask, which lets you call the abort method to cancel the request.
const task = my.request({url: 'https://example.org/post'})
task.abort()

Return value

RequestTask

A network request task object.

Method

RequestTask.abort()

my.uploadFile

Uploads a local resource to the developer's server.

Usage notes:

• Configure the domain name whitelist in Open Platform Mini Program Management > Server Domain Name Whitelist. The miniapp can communicate only with domain names in the whitelist when calling APIs such as HTTP requests (my.request) and file uploads (my.uploadFile).

Input parameters

success return value

Error codes

Code example

This example is for reference only. You must use your own address for testing.

my.uploadFile({
  url: 'Use your own server address',
  fileType: 'image',
  fileName: 'file',
  filePath: '...',
  success: (res) => {
    my.alert({
      content: 'Upload successful'
    });
  },
});

UploadTask

An object that listens for upload progress changes and cancels upload tasks.

Methods

Code example

const task = my.uploadFile({
  url: 'Use your own server address',
  fileType: 'image',
  fileName: 'file',
  filePath: '...',
});
task.onProgressUpdate(({progress, totalBytesWritten, totalBytesExpectedToWrite}) => {
})
task.abort()

FAQ

• Q: Can a miniapp automatically convert an uploaded image to Base64, which is a method of representing binary data with printable characters?

  A: No, miniapps do not support converting images to Base64.

• Q: How can I use my.uploadFile to retrieve error messages returned from the server?

  A:

  • Retrieve it from the `data` parameter in the `success` callback.

  • Add a log retrieval API on the server side. If an upload fails, call the log retrieval API to obtain detailed failure logs.

• Q: What is the default timeout for my.uploadFile? Can the default timeout be extended?

  A: The default timeout for my.uploadFile is 30 s. No, you cannot extend the default timeout.

• Q: Why does my.uploadFile report error: 12 when uploading a file?

  A: The error code 12 indicates an upload failure. Possible reasons for the failure include the following:

  • The file is too large.

  • The upload took longer than 30 s.

  • No permission.

• Q: The backend receives a binary image when my.uploadFile is used. If the backend sends this binary image back to the miniapp, how does the miniapp parse it?

  A: The backend receives the image as a binary stream. The backend only needs to provide the URL of the image's location on the server.

• Q: Why does calling my.uploadFile report error: 4, no permission to call this API?

  A: The requested URL is not in the whitelist. Add the URL's domain name to the whitelist.

• Q: Do miniapps support uploading Excel files?

  A: No. Currently, my.uploadFile supports uploading files of the type image, video, or audio. Other file types are not supported.

• Q: Does my.uploadFile support uploading multiple images at the same time?

  A: No, my.uploadFile does not support uploading multiple images at the same time. You can upload only one image at a time.

my.downloadFile

Downloads a file resource to the local device.

Input parameters

success return value

Error codes

Code example

This example is for reference only. You must use your own address for testing.

// API-DEMO page/API/download-file/download-file.json
{
    "defaultTitle": "Download File"
}

<!-- API-DEMO page/API/download-file/download-file.axml-->
<view class="container">
  <button onTap="download">Download and display image</button>
</view>

// API-DEMO page/API/download-file/download-file.js
Page({
  download() {
    my.downloadFile({
      url: 'https://img.alicdn.com/tfs/TB1x669SXXXXXbdaFXXXXXXXXXX-520-280.jpg',
      success({ apFilePath }) {
        my.previewImage({
          urls: [apFilePath],
        });
      },
      fail(res) {
        my.alert({
          content: res.errorMessage || res.error,
        });
      },
    });
  },
})

my.connectSocket

Creates a WebSocket connection.

A miniapp can have only one WebSocket connection at a time. If a WebSocket connection already exists, it is automatically closed, and a new one is created.

Input parameters

Error codes

Code example

This example is for reference only. You must use your own address for testing.

my.connectSocket({
  url: 'test.php',
  data: {},
  header:{
    'content-type': 'application/json'
  },
});

my.onSocketOpen

Listens for the WebSocket connection open event.

Input parameters

Object type with the following properties:

Code example

This example is for reference only. You must use your own address for testing.

my.connectSocket({
  url: 'test.php',
});

my.onSocketOpen(function(res) {
  console.log('WebSocket connection is open!');
});

my.offSocketOpen

Stops listening for the WebSocket connection open event.

Code example

This example is for reference only. You must use your own address for testing.

Page({
  onLoad() {
    this.callback = this.callback.bind(this);
    my.onSocketOpen(this.callback);
  },
  onUnload() {
    my.offSocketOpen(this.callback);
  },
  callback(res) {
  },
})

Whether to pass a callback value

• If you do not pass a callback value, all event callbacks for this listener are removed. The following code provides an example:

  my.offSocketOpen();

• If you pass a callback value, only the corresponding callback event is removed. The following code provides an example:

  my.offSocketOpen(this.callback);

my.onSocketError

Listens for WebSocket errors.

Input parameters

Object type with the following properties:

Code example

This example is for reference only. You must use your own address for testing.

my.connectSocket({
  url: 'Your server address'
});

my.onSocketOpen(function(res){
  console.log('WebSocket connection is open!');
});

my.onSocketError(function(res){
  console.log('WebSocket connection failed. Please check!');
});

my.offSocketError

Stops listening for WebSocket errors.

Code example

This example is for reference only. You must use your own address for testing.

Page({
  onLoad() {
    this.callback = this.callback.bind(this);
    my.onSocketError(this.callback);
  },
  onUnload() {
    my.offSocketError(this.callback);
  },
  callback(res) {
  },
})

Whether to pass a callback value

• If you do not pass a callback value, all event callbacks for this listener are removed. The following code provides an example:

  my.offSocketError();

• If you pass a callback value, only the corresponding callback event is removed. The following code provides an example:

  my.offSocketError(this.callback);

my.sendSocketMessage

Sends data over a WebSocket connection. You must first use my.connectSocket to initiate a connection and then send data after the my.onSocketOpen callback.

Input parameters

Code example

This example is for reference only. You must use your own address for testing.

my.sendSocketMessage({
    data: this.data.toSendMessage, // The content to send
    success: (res) => {
        my.alert({content: 'Data sent! ' + this.data.toSendMessage});
    },
});

my.onSocketMessage

Listens for messages received from the server over a WebSocket connection.

Callback return value

Code example

This example is for reference only. You must use your own address for testing.

my.connectSocket({
  url: 'Server address'
})

my.onSocketMessage(function(res) {
  console.log('Received server content: ' + res.data)
})

my.offSocketMessage

Stops listening for messages received from the server over a WebSocket connection.

Code example

This example is for reference only. You must use your own address for testing.

my.connectSocket({
  url: 'Server address'
})
my.onSocketMessage(function(res) {
  console.log('Received server content: ' + res.data)
})
my.offSocketMessage();

Whether to pass a callback value

• If you do not pass a callback value, all event callbacks for this listener are removed. The following code provides an example:

  my.offSocketMessage();

• If you pass a callback value, only the corresponding callback event is removed. The following code provides an example:

  my.offSocketMessage(this.callback);

my.closeSocket

Closes a WebSocket connection.

Input parameters

Code example

This example is for reference only. You must use your own address for testing.

my.onSocketOpen(function() {
  my.closeSocket()
})

my.onSocketClose(function(res) {
  console.log('WebSocket connection is closed!')
})

my.onSocketClose

Listens for the WebSocket close event.

Input parameters

Object type with the following properties:

Code example

This example is for reference only. You must use your own address for testing.

onLoad() {
    // Note: Register the callback method only once during the miniapp startup phase.
    // If you call it multiple times, the callback will be triggered multiple times.
    my.onSocketClose((res) => {
      my.alert({content: 'Connection closed!'});
      this.setData({
        sendMessageAbility: false,
        closeLinkAbility: false,
      });
    });
    // Note: Register the callback method only once during the miniapp startup phase.
    // If you call it multiple times, the callback will be triggered multiple times.
    my.onSocketOpen((res) => {
      my.alert({content: 'Connection opened!'});
      this.setData({
        sendMessageAbility: true,
        closeLinkAbility: true,
      });
    });

    my.onSocketError(function(res){
      my.alert('WebSocket connection failed. Please check! ' + res);
    });

    // Note: Register the callback method only once during the miniapp startup phase.
    // If you call it multiple times, the callback will be triggered multiple times.
    my.onSocketMessage((res) => {
      my.alert({content: 'Data received! ' + JSON.stringify(res)});
    });
  }

connect_start() {
    my.connectSocket({
      url: 'Server address', // The developer's server API address. It must use the wss protocol, and the domain name must be a legitimate domain name configured in the backend.
      success: (res) => {
        my.showToast({
          content: 'success', // Text content
        });
      },
      fail:()=>{
        my.showToast({
          content: 'fail', // Text content
        });
      }
    });
  },

my.offSocketClose

Stops listening for the WebSocket close event.

Code example

This example is for reference only. You must use your own address for testing.

Page({
  onLoad() {
  my.onSocketClose(this.callback);
  },
  onUnload() {
    my.offSocketClose(this.callback);
    //    my.offSocketClose();
  },
  callback(res) {
  my.alert({content: 'Connection closed!'});
      this.setData({
        sendMessageAbility: false,
        closeLinkAbility: false,
      });
  },
})

Whether to pass a callback value

• If you do not pass a callback value, all event callbacks for this listener are removed. The following code provides an example:

  my.offSocketClose();

• If you pass a callback value, only the corresponding callback event is removed. The following code provides an example:

  my.offSocketClose(this.callback);

my.rpc({
      operationType: 'com.xx.xx',
      requestData: [{
        "param1":"",
        "param2":0
      }],
      success: res => {
      },
      fail: res => {
      }
});