diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md new file mode 100644 index 00000000..3af91268 --- /dev/null +++ b/.github/ISSUE_TEMPLATE.md @@ -0,0 +1,19 @@ +## Current Behaviour + + + +## Expected Behaviour + + + +## Steps to Reproduce the Problem + +1. +1. +1. + +## Context + + + +- Version: diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..f0b89ac7 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,14 @@ +## Issue + + + + +#[issue-no] [issue title] + +## Changes + + + +1. +1. +1. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e7599ff4..219a904a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,11 +1,11 @@ -# Contributing to ID PASS SmartScanner +# Contributing to SmartScanner Core -Thank you for your interest to contribute to ID PASS SmartScanner! We want to make contributing to this project as easy as possible, whether it's: +Thank you for your interest to contribute to SmartScanner Core! We want to make contributing to this project as easy as possible, whether it's: - Reporting a bug - Discussing the current state of the code - Submitting a fix -- Propositing new features +- Proposing new features ## We develop with GitHub @@ -23,7 +23,7 @@ We use [Gitflow](https://www.atlassian.com/git/tutorials/comparing-workflows/git ## Reporting bugs -We use [GitHub issues](https://github.com/idpass/idpass-smart-scanner-core/issues) to track bugs. Report a bug by [opening a new issue](https://github.com/idpass/idpass-smart-scanner-core/issues/new). +We use [GitHub issues](https://github.com/idpass/smartscanner-core/issues) to track bugs. Report a bug by [opening a new issue](https://github.com/idpass/smartscanner-core/issues/new). Write bug reports with detail, background, and sample code. An issue template is provided when opening a new issue, make sure to provide all the requested information to make it easier to address the issue. diff --git a/README.md b/README.md index 1653684e..aa105ebd 100644 --- a/README.md +++ b/README.md @@ -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 - -### 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)