How to integrate the web SDK into an H5 page to perform mobile number verification-Phone Number Verification Service(PNVS)-阿里云帮助中心

This topic describes how to integrate the web SDK into an H5 page to perform mobile number verification.

Integration steps

Download the SDK

Log on to the Phone Number Verification Service console. On the Overview page, find the API & SDK section on the right and click Download Now. Follow the on-screen instructions to download the required SDK.

Create an authentication scheme

For more information, see Create an authentication scheme and obtain a scheme code.

Import resources

Import an npm package

Install the npm package and add the aliyun_numberauthsdk_web package as a dependency to your package.json file:

npm i aliyun_numberauthsdk_web -S

Import the package into your script:

import { PhoneNumberServer } from 'aliyun_numberauthsdk_web';

Import static resources

You can upload the Web SDK to your static resource server, obtain the URL for the Web SDK, and import it using a script tag.

<script type="text/javascript" charset="utf-8" src="${your-sdk-asset-path}/numberAuth-web-sdk.js"></script>

Important

Do not overwrite the window.PhoneNumberServer variable in your business code.
One-click logon requires an active mobile data connection. Users without an active mobile data connection cannot be authenticated. Before authentication, ensure that the Wi-Fi connection is disabled on the device and the 4G mobile data network for the SIM card is enabled. 3G networks from China Unicom and China Mobile are also supported, but the API call may take longer.

How it works

The mobile number verification process consists of three main steps: initialization, getting authentication parameters, and number verification.

Note: The figure above shows the complete interaction flow.

Initialization.
1. When a user visits the H5 page, the page requests an authorization token from your server. Your server then calls the Get H5 Authentication Token API to obtain this token. This token includes a service access token (accessToken) and an API authentication token (jwtToken).
2. The H5 page calls the SDK's checkAuthAvailable method to initiate authentication.
Get authentication parameters.
1. After authentication succeeds, the H5 page calls the SDK's getVerifyToken method to obtain the spToken for number verification.
Number verification.
1. The user enters the phone number to be verified.
2. The H5 page sends a verification request to your server that includes the spToken and the user-entered phone number.
3. Your server calls the Mobile Number Verification (for H5) API to retrieve the verification result. This process checks if the user-entered phone number matches the one associated with the device's current data network.
4. Your server returns the verification result to the H5 page.

Method reference

Initialize an instance

var phoneNumberServer = new PhoneNumberServer();

checkAuthAvailable: Initiate authentication

Before calling this method, call the GetAuthToken API on your server to retrieve the required accessToken and jwtToken.

Method parameters

Parameter	Type	Required	Description
success	function	Yes	The success callback function. For details about the parameters in this callback function, see Callback parameters.
error	function	Yes	The error callback function. For details about the parameters in this callback function, see Callback parameters.
accessToken	string	Yes	The service access token for authentication. Generated by calling the server-side GetAuthToken API. Note The accessToken is valid for 10 minutes and can be reused within its validity period.
jwtToken	string	Yes	The API authentication token. Generated by calling the server-side GetAuthToken API. Note The jwtToken is valid for 1 hour and can be reused within its validity period.
timeout	number	No	The request timeout in seconds. Default: 10.

Callback parameters

Parameter	Description
code	The returned status code. `600000` indicates success. For other error codes, see Error codes.
requestId	The unique ID for the local call. You can use this ID to query related logs.
content	The result from the SDK server. Useful for troubleshooting.
msg	A description of the returned result.

Example

// Before you call this method, obtain the accessToken and jwtToken from your server.
phoneNumberServer.checkAuthAvailable({
  accessToken: "XXXXXXXXXX",
  jwtToken: "******",
  success: function (res) {
    console.log(res);
    if (res.code === 600000) {
      // Call the getVerifyToken method here.
    }
  },

  error: function (res) {
    // Prompt the user to disable Wi-Fi or try another logon method.
  },
});

getVerifyToken: Get verification token

Call this method within the success callback function of checkAuthAvailable.

Method parameters

Parameter	Type	Required	Description
success	function	Yes	The success callback function. For details about the parameters in this callback function, see Callback parameters.
error	function	Yes	The error callback function. For details about the parameters in this callback function, see Callback parameters.
timeout	number	No	The request timeout in seconds. Default: 25.

Callback parameters

Parameter	Description
code	The returned status code. `600000` indicates success. For other error codes, see Error codes.
spToken	The carrier token.
content	Content returned by the carrier on failure.
requestId	The unique ID for the local call. You can use this ID to query related logs.

Example

phoneNumberServer.getVerifyToken({
  success: function (res) {
    console.log(res);
    // Use the user-entered phone number and the spToken to verify the mobile number.
  },

  error: function (res) {},
});

getVersion (get SDK version number)

const sdkVersion = phoneNumberServer.getVersion();  // Returns the SDK version number, such as '1.0.0'

getConnection (network type check API)

This API checks the user's current network type and returns netType:

wifi: Wi-Fi network. We recommend that you prompt these users to disable Wi-Fi or provide other authentication methods.
cellular: Mobile data network.
unknown: Unknown network type.

This API is not part of the authentication flow, and its use is optional. We recommend that you call this API before authentication to block users on Wi-Fi networks. This helps save resources and improves the user authentication experience.

const netType = phoneNumberServer.getConnection(); // Returns netType: wifi, cellular, unknown

setLoggerEnable (enable logging)

phoneNumberServer.setLoggerEnable(true); // true enables logging, false disables it.