Parameters
| Property | Type | Required | Description |
|---|---|---|---|
| promptText | String | Yes | The text displayed on the biometric prompt. Use short, clear text to state the authentication purpose to avoid truncation. |
| fallbackType | Number | No | The alternative authentication method when biometric authentication fails: 0 - No fallback (default). 1 - Fallback to device credentials. |
| success | Function | No | Callback on success |
| fail | Function | No | Callback on failure |
| complete | Function | No | Callback that always executes |
Success Callback Parameters
| Property | Type | Description |
|---|---|---|
| success | Boolean | Whether the biometric authentication succeeded. Returned by the success or complete callback. |
| error | Number | The error code. Returned by the fail callback, or by the complete callback when success is false. See Error Codes below. |
| errorMessage | String | The error message corresponding to the error code. |
Code Example
Basic Authentication
my.startLocalBioAuth({
promptText: 'Authenticate to unlock',
success(res) {
if (res.success) {
console.log('Biometric verified');
}
},
fail(res) {
console.error('Authentication failed:', res.error);
}
});
Fallback to Device Credentials
my.startLocalBioAuth({
promptText: 'Verify your identity',
fallbackType: 1,
success(res) {
if (res.success) {
console.log('Authenticated');
}
},
fail(res) {
if (res.error === 11) {
// The user cancelled the authentication
}
}
});
Secure Payment Flow
Page({
async confirmPayment() {
// First verify user identity
my.startLocalBioAuth({
promptText: 'Confirm payment',
fallbackType: 1,
success: (res) => {
if (res.success) {
this.processPayment();
} else {
my.showToast({
content: 'Verification failed',
type: 'fail'
});
}
},
fail: (res) => {
// Biometric not available or cancelled, fall back to PIN
this.showPinEntry();
}
});
},
processPayment() {
// Proceed with payment
},
showPinEntry() {
// Show PIN input as fallback
}
});
Check Biometric Availability First
Page({
async authenticateUser() {
// Check if biometric is available
my.checkLocalBioAuthSupported({
success: (res) => {
if (res.success) {
my.startLocalBioAuth({
promptText: 'Verify your identity',
success: (verifyRes) => {
if (verifyRes.success) {
this.onAuthSuccess();
}
}
});
} else {
// Biometric not available
this.useFallbackAuth();
}
}
});
},
onAuthSuccess() {
my.showToast({ content: 'Authenticated' });
},
useFallbackAuth() {
// Use password or PIN
}
});
Error Codes
| Code | Description |
|---|---|
| 11 | The authentication process was canceled by the user. |
| 12 | Either the device lacks biometric support or the super app cannot access the biometric feature. |
| 13 | Biometric credentials are not enabled on the user’s device. |
| 99 | An undefined error has occurred. Please contact technical support for assistance. |
Biometric authentication may not be available on all devices. Always provide a fallback authentication method.
Related APIs
my.checkLocalBioAuthSupported
Check availability