capawesome-team / capacitor-mlkit

⚡️ ML Kit plugins for Capacitor. Supports Android and iOS.
https://capawesome.io/plugins/mlkit/
Apache License 2.0
147 stars 46 forks source link

Suggested documentation improvement #162

Closed viking2917 closed 5 months ago

viking2917 commented 5 months ago

Plugin(s)

Version

6.1.0

Platform(s)

Current behavior

I encountered the issue where older Android devices will fail on a call to the scan() menu, because the Google Barcode Scanner is not pre-installed. Even though I am somewhat experienced with this plugin, I spent the better part of two days investigating and implementing my own solution to this, before I noticed the documentation notes under scan() regarding installGoogleBarcodeScannerModule() and isGoogleBarcodeScannerModuleAvailable(). This is after multiple reads of the installation instructions for Android. I did not think to look under scan() per se.

I suggest adding documentation to the Android installation section covering this issue. I will create a PR with a suggested documentation update.

Expected behavior

Android installation documentation should cover the optional use of installGoogleBarcodeScannerModule().

Reproduction

https://github.com/viking2917/capacitor-mlkit

Steps to reproduce

Review the current Android installation documentation.

Other information

No response

Capacitor doctor

💊 Capacitor Doctor 💊

Latest Dependencies:

@capacitor/cli: 6.1.0 @capacitor/core: 6.1.0 @capacitor/android: 6.1.0 @capacitor/ios: 6.1.0

Installed Dependencies:

@capacitor/cli: 6.1.0 @capacitor/core: 6.1.0 @capacitor/android: 6.1.0 @capacitor/ios: 6.1.0

[success] iOS looking great! 👌 [success] Android looking great! 👌

Before submitting

viking2917 commented 5 months ago

My suggested edit is as follows, at the end of the Android installation instructions

Older Android Devices/Versions

Some Android devices, especially older ones, may not have the Google Barcode Scanner available, and the scan() method will fail. This can be addressed using the isGoogleBarcodeScannerModuleAvailable() and installGoogleBarcodeScannerModule() methods. Also see the notes below regarding isGoogleBarcodeScannerModuleAvailable().

BarcodeScanner.isGoogleBarcodeScannerModuleAvailable().then((res: IsGoogleBarcodeScannerModuleAvailableResult) => {
  if (!res.available) {
    BarcodeScanner.addListener('googleBarcodeScannerModuleInstallProgress',
      (event: GoogleBarcodeScannerModuleInstallProgressEvent) => {
        if (event.state === GoogleBarcodeScannerModuleInstallState.COMPLETED) {
          // module is installed and ready to go.
        }
      });
    BarcodeScanner.installGoogleBarcodeScannerModule();
 }
});

If that is felt desirable, please assign the issue to me and I will submit a PR.

robingenz commented 5 months ago

The Installation section should only contain documentation that is required to install the plugin itself. However, these are implementation details. Therefore, I will adapt the error message instead, so that the developer is explicitly referred to the method (see #163).

viking2917 commented 5 months ago

awesome that sounds great. thank you!