## Unlock Method Management

Supported unlock methods include: fingerprint, card, face, finger vein, palm vein, and iris.

> Note: Whether face supports multiple faces is determined by the device. When only a single face is supported, a replacement operation should be performed on the device side when adding a face.

### Add Password

You can directly use the API [addPassword](/en/miniapp/develop/ray/api/doorlock/unlock-method/addPassword) to add.

### Add Other Unlock Methods

Adding other unlock methods requires the following process

```mermaid
sequenceDiagram
    participant Panel
    participant Device
    Panel->>Panel: Enter add page
    Note right of Panel: Call onAddUnlockMethod <br/>Register listener for steps and result events
    Panel->>Panel: Call startAddUnlockMethod
    Panel->>Device: Start recording
    Note right of Panel: Show adding
    Device->>Panel: Report recording step
    Note right of Panel: onAddUnlockMethod receives step report<br/>Display step
    Panel->>Panel: Exit page
    Note left of Panel: Exit during recording<br/>Call offAddUnlockMethod to unregister listener for steps and result events<br/>Call cancelAddUnlockMethod to cancel recording
    Device->>Panel: Report recording result
    Note right of Panel: onAddUnlockMethod receives result<br/>Display recording success or failure<br/>If successful, can call updateUnlockMethod to update name and special information
    Panel->>Panel: Exit page
    Note right of Panel: Call offAddUnlockMethod <br/>Unregister listener for steps and result events

```

Description

> - The `onAddUnlockMethod` and `startAddUnlockMethod` APIs can be called asynchronously, but if these two APIs are called separately in multiple pages, please ensure that when the user operates the recording steps on the lock, the panel has already called `onAddUnlockMethod` to listen to the recording status.
> - During recording, you need to pay attention to the situation where the user exits the recording. In this case, you need to call `cancelAddUnlockMethod`.
> - When recording has a result (success or failure), when exiting the add page, please call `offAddUnlockMethod` to ensure no duplicate listening and ensure normal program execution.
> - If the reason for recording failure is timeout (error code 1002), please call `cancelAddUnlockMethod` when exiting the page to ensure the situation where the panel times out but the lock is still in the adding state.

### Bind Unassociated Unlock Methods

Unassociated unlock methods have two situations:

- In the unlock records returned in the log list, there may be unassociated unlock methods that need to call `bindUnlockMethodFromLog` for association binding;
- The list data obtained through `getUnbindUnlockMethods` needs to call `bindUnlockMethod` for association binding.

Association binding process in logs

```mermaid
sequenceDiagram
participant Panel
participant Cloud
Panel->>Cloud: Get log list
Cloud->>Panel: Return log list
Panel->>Panel: Select unlock method to associate
Panel->>Cloud: Get family list
Cloud->>Panel: Return family list
Panel->>Panel: Select user to bind
Panel->>Cloud: Associate bind
Cloud->>Panel: Association binding successful
```

Associate through unassociated list

```mermaid
sequenceDiagram
participant Panel
participant Cloud
Panel->>Cloud: Get unassociated list
Cloud->>Panel: Return unassociated list
Panel->>Panel: Select unlock method to associate
Panel->>Cloud: Get family list
Cloud->>Panel: Return family list
Panel->>Panel: Select user to bind
Panel->>Cloud: Associate bind
Cloud->>Panel: Association binding successful
```

### Send Sync Unlock Method Command to Device

- When the SDK is initialized, it will try to send a sync unlock method command to the device;
- Developers can manually send a sync unlock method command to the device by calling `syncUnlockMethod`.

### API

#### Add Password

- Meaning: Add password unlock method for family members
- Details: [View Documentation](/en/miniapp/develop/ray/api/doorlock/unlock-method/addPassword)

#### Start Adding Unlock Method

- Meaning: Send start add command to device and wait for device to report status.
- Details: [View Documentation](/en/miniapp/develop/ray/api/doorlock/unlock-method/startAddUnlockMethod)

#### Cancel Adding Unlock Method

- Meaning: During the process of recording unlock method, you can call the API to cancel the unlock method
- Details: [View Documentation](/en/miniapp/develop/ray/api/doorlock/unlock-method/cancelAddUnlockMethod)

#### Register Unlock Method Step Listener

- Meaning: When the user records the unlock method on the lock side, the step data generated will push messages through the listener's callback function.
- Details: [View Documentation](/en/miniapp/develop/ray/api/doorlock/unlock-method/onAddUnlockMethod)

#### Unregister Unlock Method Step Listener

- Meaning: Cancel listening to the unlock method process
- Details: [View Documentation](/en/miniapp/develop/ray/api/doorlock/unlock-method/offAddUnlockMethod)

#### Send Phone Verification Code

- Meaning: When updating the unlock method to a special unlock method, if you need to add SMS notification, you need to get the verification code
- Details: [View Documentation](/en/miniapp/develop/ray/api/doorlock/unlock-method/sendVerifyCode)

#### Check if SMS Notification is Supported

- Meaning: For special unlock methods, detect whether SMS notification service is supported
- Details: [View Documentation](/en/miniapp/develop/ray/api/doorlock/unlock-method/checkSpecialSupportPhone)

#### Update Unlock Method

- Meaning: Update existing unlock method information, only supports updating unlock method name and special unlock method notification information
- Details: [View Documentation](/en/miniapp/develop/ray/api/doorlock/unlock-method/updateUnlockMethod)

#### Delete Unlock Method

- Meaning: Delete unlock methods owned by users added through the universal panel
- Details: [View Documentation](/en/miniapp/develop/ray/api/doorlock/unlock-method/deleteUnlockMethod)

#### Get Unlock Method Detailed Information

- Meaning: Get detailed information of an unlock method, can be used to display information when editing unlock method
- Details: [View Documentation](/en/miniapp/develop/ray/api/doorlock/unlock-method/getUnlockMethodDetail)

#### Check if There Are Unbound Unlock Methods

- Meaning: Check whether all unlock methods on the current lock side have unassociated users
- Details: [View Documentation](/en/miniapp/develop/ray/api/doorlock/unlock-method/checkUnBindUnlockMethods)

#### Get Unassociated Unlock Method List

- Meaning: Get unlock methods on the lock locally that are not associated with users
- Details: [View Documentation](/en/miniapp/develop/ray/api/doorlock/unlock-method/getUnbindUnlockMethods)

#### Sync Unlock Method

- Meaning: Send sync unlock method data command to device to cloud
- Details: [View Documentation](/en/miniapp/develop/ray/api/doorlock/unlock-method/syncUnlockMethod)

#### Unbind Unlock Method

- Meaning: Unbind unlock methods bound to users through association operations. After unbinding, the unlock method is still valid on the lock side
- Details: [View Documentation](/en/miniapp/develop/ray/api/doorlock/unlock-method/unbindUnlockMethod)

#### Bind Unlock Method

- Meaning: Bind unassociated unlock method to user
- Details: [View Documentation](/en/miniapp/develop/ray/api/doorlock/unlock-method/bindUnlockMethod)

## FAQ

### Q1: How to display progress when adding unlock method?

**A:** By listening to the `onAddUnlockMethod` event, when `stage` is `'step'`, you can get the current step and total steps:

```typescript
onAddUnlockMethod((event) => {
  if (event.stage === 'step') {
    console.log(`Step ${event.step}/${event.total}`);
  }
});
```

### Q2: How to cancel an unlock method being added?

**A:** Call the `cancelAddUnlockMethod` API:

```typescript
await cancelAddUnlockMethod({ type: 'finger', userId: 'userId' });
```

### Q3: What is a special unlock method?

**A:** Special unlock methods refer to unlock methods configured with notification functionality. When using this unlock method to unlock, App notifications or SMS notifications will be sent. Only some unlock methods such as fingerprints and passwords support special configuration.

### Q4: How to enable SMS notification?

**A:** Requires:

1. Check if device supports: `checkSpecialSupportPhone()`
2. Send verification code: `sendVerifyCode({ account: '86-13800138000' })`
3. Pass verification code and phone number when adding

### Q5: What do the error codes for add failure mean?

**A:** Common error codes:

- `1015-1025`: Various reasons for add failure (such as fingerprint full, recording timeout, etc.)
- `1026`: Add was cancelled
- `1014`: Device does not support this unlock method

### Q6: Can all unlock methods owned by users be deleted?

**A:** No, unlock methods bound to users through association cannot be deleted, but you can call `unbindUnlockMethod` to cancel the binding.

### Q7: How to determine if an unlock method is bound through association?

**A:** Get details through `getUnlockMethodDetail`, the `isBound` field indicates whether it is bound.

### Q8: How to handle unbound unlock methods?

**A:** You can get the list through `getUnbindUnlockMethods`, then use `bindUnlockMethod` to bind to users.