-
Notifications
You must be signed in to change notification settings - Fork 21
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #29 from idpass/feature/documentation-improvements
Documentation improvements
- Loading branch information
Showing
4 changed files
with
111 additions
and
63 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| ## Current Behaviour | ||
|
|
||
| <!-- Provide a detailed description of how it behaves currently. --> | ||
|
|
||
| ## Expected Behaviour | ||
|
|
||
| <!-- Provide a detailed description of how you expected it to behave. --> | ||
|
|
||
| ## Steps to Reproduce the Problem | ||
|
|
||
| 1. | ||
| 1. | ||
| 1. | ||
|
|
||
| ## Context | ||
|
|
||
| <!-- Provide a description of your environment where you encountered this behaviour. --> | ||
|
|
||
| - Version: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,14 @@ | ||
| ## Issue | ||
|
|
||
| <!-- Provide a reference to the issue that this change is going to address --> | ||
| <!-- E.g. #12 Issue title here --> | ||
|
|
||
| #[issue-no] [issue title] | ||
|
|
||
| ## Changes | ||
|
|
||
| <!-- Provide a detailed description of the changes proposed in this PR --> | ||
|
|
||
| 1. | ||
| 1. | ||
| 1. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,86 +1,101 @@ | ||
| # ID PASS SmartScanner | ||
| This is the core repository of the ID PASS SmartScanner that provides developers with an API that enables them to scan MRZ, Barcode, and ID PASS Lite cards. | ||
| # SmartScanner Core | ||
|
|
||
| It provides 2 projects: | ||
| - Android library that can be integrated into other projects | ||
| - Android App | ||
| An Android library for scanning MRZ, Barcode, and [ID PASS Lite](https://github.com/idpass/idpass-lite) cards. | ||
|
|
||
| ## Setting Up | ||
| --------------- | ||
| ```bash | ||
| # 1. Clone this repository. | ||
| git clone https://github.com/idpass/idpass-smart-scanner-core.git | ||
| ## Features | ||
|
|
||
| # 2. Enter your newly-cloned folder. | ||
| cd idpass-smart-scanner-core | ||
| - Scan MRZ | ||
| - Scan Barcode | ||
| - Scan [ID PASS Lite](https://github.com/idpass/idpass-lite) | ||
| - Supports Intent Call Out (ODK & Non-ODK) | ||
|
|
||
| ``` | ||
| This repository also includes an Android [demo app](app) to test what the library can do. | ||
|
|
||
| ## Building | ||
| ```bash | ||
| ./gradlew build | ||
| ``` | ||
| ## Related projects | ||
|
|
||
| ## Features | ||
| - Scan MRZ | ||
| - Scan Barcode | ||
| - Scan ID PASS Lite | ||
| - Intent Call Out support (ODK/Non-ODK) | ||
| - Plugin Integration for [Capacitor](https://github.com/idpass/idpass-smart-scanner-capacitor)/[Cordova](https://github.com/idpass/idpass-smart-scanner-cordova) | ||
| - [smartscanner-android](https://github.com/idpass/smartscanner-android) - Provides convenience methods to simplify the SmartScanner intent call out process | ||
| - [smartscanner-capacitor](https://github.com/idpass/smartscanner-capacitor) - SmartScanner [Capacitor](https://capacitorjs.com/) plugin | ||
| - [smartscanner-cordova](https://github.com/idpass/smartscanner-cordova) - SmartScanner [Cordova](https://cordova.apache.org/) plugin | ||
|
|
||
| ## Quickstart | ||
| This library is used to scan MRZ, Barcode, and ID PASS Lite cards. This also has an embedded standalone `app` for testing purposes | ||
| ## Installation | ||
|
|
||
| <!-- | ||
| ### 1. Install | ||
| Declare Maven Central repository in the dependency configuration. For example, in `build.gradle`: | ||
| Declare Maven Central repository in the dependency configuration, then add this library in the dependencies. An example using `build.gradle`: | ||
|
|
||
| ```groovy | ||
| repositories { | ||
| mavenCentral() | ||
| mavenCentral() | ||
| } | ||
| dependencies { | ||
| implementation "org.idpass:idpass-smartscanner:0.0.1-SNAPSHOT" | ||
| implementation "org.idpass:idpass-smartscanner:0.0.1-SNAPSHOT" | ||
| } | ||
| ``` | ||
| --> | ||
| ### 2. Usage | ||
| --------------- | ||
| App Intent Call out | ||
|
|
||
| Call scanner using the ff intent actions: | ||
| - `"org.idpass.smartscanner.MRZ_SCAN"` | ||
| - `"org.idpass.smartscanner.BARCODE_SCAN"` | ||
| - `"org.idpass.smartscanner.IDPASS_LITE_SCAN"` | ||
| If you want to build this library from source, instructions to do so can be found in the [Building from source](https://github.com/idpass/smartscanner-core/wiki/Building-from-source) wiki page. | ||
|
|
||
| ## Usage | ||
|
|
||
| The following table shows the intent actions available for each operation available in the library, both in ODK and Non-ODK: | ||
|
|
||
| | Scan Operation | ODK | Non-ODK | | ||
| | -------------- | ---------------------------------------------- | ------------------------------------------ | | ||
| | MRZ | `org.idpass.smartscanner.odk.MRZ_SCAN` | `org.idpass.smartscanner.MRZ_SCAN` | | ||
| | Barcode | `org.idpass.smartscanner.odk.BARCODE_SCAN` | `org.idpass.smartscanner.BARCODE_SCAN` | | ||
| | ID PASS Lite | `org.idpass.smartscanner.odk.IDPASS_LITE_SCAN` | `org.idpass.smartscanner.IDPASS_LITE_SCAN` | | ||
|
|
||
| ODK Support can be called using the ff intent actions: | ||
| - `"org.idpass.smartscanner.odk.MRZ_SCAN"` | ||
| - `"org.idpass.smartscanner.odk.BARCODE_SCAN"` | ||
| - `"org.idpass.smartscanner.odk.IDPASS_LITE_SCAN"` | ||
| To perform an operation, create an intent for the desired operation. This example shows how to call an intent to scan an MRZ (ODK): | ||
|
|
||
| ```kotlin | ||
| // Sample SmartScanner MRZ intent call out | ||
| val OP_SCANNER = 1001 // Activity request code | ||
| import android.app.Activity | ||
| import android.content.ActivityNotFoundException | ||
| import android.content.Intent | ||
| import androidx.appcompat.app.AppCompatActivity | ||
|
|
||
| class MainActivity : AppCompatActivity() { | ||
|
|
||
| private const val OP_SCANNER = 1001 // Activity request code | ||
|
|
||
| override fun onStart() { | ||
| super.onStart() | ||
|
|
||
| try { | ||
| val action = "org.idpass.smartscanner.MRZ_SCAN" | ||
| val intent = Intent(action) | ||
| startActivityForResult(intent, OP_SCANNER) | ||
| val action = "org.idpass.smartscanner.odk.MRZ_SCAN" | ||
| val intent = Intent(action) | ||
| startActivityForResult(intent, OP_SCANNER) | ||
| } catch (ex: ActivityNotFoundException) { | ||
| ex.printStackTrace() | ||
| Log.e(TAG, "smart scanner is not installed!") | ||
| ex.printStackTrace() | ||
| } | ||
| } | ||
|
|
||
| public override fun onActivityResult(requestCode: Int, resultCode: Int, intent: Intent?) { | ||
| super.onActivityResult(requestCode, resultCode, intent) | ||
|
|
||
| // Get Result from the ActivityResult via Bundle | ||
| public override fun onActivityResult(requestCode: Int, resultCode: Int, intent: Intent?) { | ||
| super.onActivityResult(requestCode, resultCode, intent) | ||
| if (requestCode == OP_SCANNER) { | ||
| Log.d(TAG, "Plugin post SmartScanner Activity resultCode $resultCode") | ||
| if (resultCode == RESULT_OK) { | ||
| val bundle =intent?.getBundleExtra("result") | ||
| } | ||
| } | ||
| if (requestCode == OP_SCANNER) { | ||
| if (resultCode == Activity.RESULT_OK) { | ||
| val bundle = intent?.getBundleExtra("result") | ||
| } | ||
| } | ||
| } | ||
|
|
||
| } | ||
| ``` | ||
|
|
||
| The `bundle` variable is a [`Bundle`](https://developer.android.com/reference/kotlin/android/os/Bundle) object containing the scan results. For example, the scanned surname can be obtained through: | ||
|
|
||
| ```kotlin | ||
| val surname = bundle.getString("surname") | ||
| ``` | ||
|
|
||
| For convenience, you may use the [smartscanner-android-api](https://github.com/idpass/smartscanner-android-api) which will simplify the app intent call out process. | ||
| Refer to the [Result fields reference](https://github.com/idpass/smartscanner-core/wiki/Result-fields-reference) for the different fields available from the scan results. | ||
|
|
||
| Refer to the [API Reference](https://github.com/idpass/smartscanner-core/wiki/API-Reference) for complete information about each scan operation and the different options available. | ||
|
|
||
| Finally, for convenience we recommend using the [smartscanner-android](https://github.com/idpass/smartscanner-android) library which simplifies the app intent call out process. | ||
|
|
||
| ## Running the demo app | ||
|
|
||
| The Android demo app is available in this repository's `app` directory. Open this directory in Android Studio (version 4.1 and above) and the app can be built and run from there. | ||
|
|
||
| ## License | ||
|
|
||
| [Apache-2.0 License](LICENSE) |