Swiftpack.co - armonlabs/mobilepass as Swift Package

Swiftpack.co is a collection of thousands of indexed Swift packages. Search packages.
See all packages published by armonlabs.
armonlabs/mobilepass v1.4.8
Mobile application SDK to pass from armon access points securely
⭐️ 0
🕓 Yesterday
iOS
.package(url: "https://github.com/armonlabs/mobilepass.git", from: "v1.4.8")

Armon MobilePass Library

This library has been developed to allow Android and iOS apps to be used for passing from compatible armon access points. Users can pass from these points securely by using application that installed on their phones

When the user arrives at the point, the flow will be as follows;

  • The user opens the application and starts flow according to the triggering method provided by the application, like tapping a button.

  • The application gives user's information to the library. This information will be used to validate user during communication

  • Library opens the phone camera to read the QR code of the access point

  • If the QR code is valid, according to pass method of access point, library starts communication with device or server. These methods can be;

    • Remote Access
      • Library communicates with server and server validates user. If user has access to pass, related device will be triggerred by server
    • Bluetooth
      • Library starts scanning of related device via Bluetooth Low Energy. If device is in range, library communicates with device in encrypted protocol. Device validates user and opens door, turnstile, barrier, etc.
    • Remote Access First, Then Bluetooth
      • Library tries remote access flow first. If this flow fails, bluetooth communication will be started
    • Bluetooth First, Then Remote Access
      • Library tries bluetooth flow first. If this flow fails, bluetooth communication will be started
  • Remote Access method can validates user's location also. If the method is defined with geolocation validation requirement, library checks if the user is at the specified location before remote access request

  • After flow completed, returns the result to the application.


Content


Android

Installation

  • Add the JitPack repository to your root build.gradle at the end of repositories
allprojects {
	repositories {
		...
		maven { url 'https://jitpack.io' }
	}
}
  • Add the depedency to app level build.gradle
dependencies {
	implementation 'com.github.armonlabs:mobilepass:1.4.8'
}
  • Change your application's min sdk version with 21 if required

  • Specify your Google Maps API Key. This will be required to show user's and access points' location on map if QR code definition has geolocation validation requirement. Add your API key to your manifest file (android/app/src/main/AndroidManifest.xml)

<application>
   <!-- Make sure it's a child of application -->
   <meta-data
     android:name="com.google.android.geo.API_KEY"
     android:value="[Your Google maps API Key Here]"/>
</application>

For more information about Google Maps API Key; https://developers.google.com/maps/documentation/android-api/signup


Permissions

  • Library needs some permissions; camera, fine location and bluetooth. To continue flow without interrupt, you should request permissions from user. Otherwise flow will be cancelled with related reason code.

  • Camera permission is required to read QR codes at the start of flow.

  • Location permission is required for geolocation validation and Bluetooth scanning

  • Also Bluetooth should be enabled on phone


Usage

  • First you should initialize MobilePass like below
import com.armongate.mobilepasssdk.MobilePass;
import com.armongate.mobilepasssdk.model.Configuration;

...

// Setup configuration, see API reference for more details
Configuration config = new Configuration();

// Initialize manager
MobilePass passManager = new MobilePass(getApplicationContext(), config);
  • To handle events of MobilePass, implement related Delegate class like below
import com.armongate.mobilepasssdk.delegate.MobilePassDelegate;

public class MainActivity extends AppCompatActivity implements MobilePassDelegate {

	...

	// ! Important
	// Call next line where you initialized manager or give delegate instance in configuration
	// passManager.setDelegate(this);


	@Override
	public void onPassCancelled(int reason) {
		// See API reference for CancelReason types
	}

	@Override
	public void onPassCompleted(boolean succeed) {
		// Returns when library-server or library-device communication ended
		// 'true' means user passed successfully
	}

	@Override
	public void onQRCodeListStateChanged(int state) {
		// Available QR code definitions will be fetched from server.
		// Change on state of definitions triggers this event
		// See API reference for QRCodeState types
	}

    @Override
    public void onLogReceived(LogItem log) {
      // To follow SDK logs according to given configuration about logging
    }

	...

}
  • If you have not provided user token before in configuration model or token value has changed after initializing, you can call updateToken method like below
passManager.updateToken("${newTokenValue}", "${language}");

// Langugage > "tr" | "en"
  • After initialization you can start flow like below. You need to provide token before this step.
passManager.triggerQRCodeRead();

iOS

Installation

  • Add swift packagege dependency by using File > Swift Packages > Add Package Dependency
https://github.com/armonlabs/mobilepass.git
  • Make sure that your target is selected and General tab is open and package is added to Frameworks, Libraries, and Embedded Content section

  • Navigate to the Build Phases tab and make sure your framework is included in the Link Binary With Libraries list. It should already be included by default after following the steps above, however in case it’s not; click on the + button and add it.


Permissions

  • Library needs some permissions; camera, location and bluetooth. To continue flow without interrupt, you should request permissions from user. Otherwise flow will be cancelled with related reason code. You must update Info.plist with a usage description for these requirements;
...

<key>NSCameraUsageDescription</key>
<string>Your own description of the purpose</string>

<key>NSLocationWhenInUseUsageDescription</key>
<string>Your own description of the purpose</string>

<key>NSBluetoothAlwaysUsageDescription</key>
<string>Your own description of the purpose</string>

...
  • Camera permission is required to read QR codes at the start of flow.

  • Location permission is required for geolocation validation

  • Also Bluetooth should be enabled on phone


Usage

  • Examples are given in SwiftUI sample

  • Create MobilePass manager class to bridge with your UI

struct MobilePassManager : UIViewControllerRepresentable {
    typealias UIViewControllerType = UIViewController

    func makeCoordinator() -> MobilePassManager.Coordinator {
        Coordinator(self)
    }

    func makeUIViewController(context: UIViewControllerRepresentableContext<MobilePassManager>) -> UIViewController {
		// Setup configuration, see API reference for more details
		let config: Configuration = Configuration(...)

		// Initialize manager
        let passManager: MobilePass = MobilePass(config: config)

		// Call trigger method that returns ViewController
        return passManager.triggerQRCodeRead()
    }

    func updateUIViewController(_ uiViewController: UIViewController, context: UIViewControllerRepresentableContext<MobilePassManager>) {

    }

    class Coordinator : NSObject {
        var parent : MobilePassManager
        init(_ viewController : MobilePassManager){
            self.parent = viewController
        }
    }
}
  • To handle events of MobilePass, implement related Delegate class like below
struct MobilePassManager : UIViewControllerRepresentable, MobilePassDelegate {

	// ! Important
	// Call next line where you initialized manager or give delegate instance in configuration
	// passManager.delegate = self

	...

    func onPassCancelled(reason: Int) {
        // See API reference for CancelReason types
    }

    func onPassCompleted(succeed: Bool) {
        // Returns when library-server or library-device communication ended
		// 'true' means user passed successfully
    }

    func onQRCodeListStateChanged(state: Int) {
        // Available QR code definitions will be fetched from server.
		// Change on state of definitions triggers this event
		// See API reference for QRCodeState types
    }

    func onLogReceived(log: LogItem) {
        // To follow SDK logs according to given configuration about logging
    }

	...

}
  • If you have not provided user token before in configuration model or token value has changed after initializing, you can call updateToken method like below. Token must be given before trigger the QR code reading.

// Langugage > "tr" | "en"
passManager.updateToken(token: "${newTokenValue}", language: "${language}");




API Reference

Methods

updateToken(token, language)

Update or set OAuth token of user and current language code for localization

Parameter Description
token OAuth token value that will be used by server to validate user with memberId
language Language code to localize messages in library [tr/en]

triggerQRCodeRead()

Triggers QR Code reading and related pass flow.



Objects


Configuration

Library is configurable while initialization. Available props are listed below

Parameter Description Type Required
memberId Member id that will be used for validation to pass String Yes
serverUrl URL of server that communicate between SDK, devices and validation server String Yes
qrCodeMessage Information message for QR Code reader that will be shown at top of screen String No
token OAuth token value of current user's session to validate String No
language Language code to localize texts String No
allowMockLocation Allow unreliable locations or not String No
connectionTimeout Bluetooth connection timeout in seconds. Default: 5 seconds Integer No
autoCloseTimeout Auto close timeout for screen after pass completed, null means stay opened Integer No
waitBLEEnabled Flag to decide action for disabled Bluetooth state. "true" means wait user to enable Bluetooth, "false" means continue to next step if exists. Default: false Bool No
logLevel Minimum log level to follow. Default: Info LogLevel No
delegate Listener instance to get information about SDK events. Giving this instance in configuration allows to get logs with start of SDK initialization MobilePassDelegate No

LogItem

Details of received log item

Parameter Description Type Required
level Type of log item LogLevel Yes
code Code value of log item for warnings and error LogCode No
message Information message about log action String Yes
time Create time of log item Date Yes

PassResult

Details of received pass result event

Parameter Description Type Required
success Result of pass Bool Yes
direction Pass direction Direction No
clubId Id of matched club String No
clubName Name of matched club String No
failCode Fail reason PassFailCode No

Events

Name Description Type
onPassCompleted Passing operation completed PassResult
onPassCancelled Operation has been cancelled with given reason code CancelReason
onQRCodeListStateChanged  QR code definition list updated QRCodeState
onLogReceived Receive log items LogItem
onInvalidQRCode QR code content when invalid format found String


Constants


CancelReason

Name Value
User Closed 1
Using Mock Location 2
Error 3

QRCodeState

Name Value
Empty
Using Stored Data 2
Using Synced Data 3

LogLevel

Name Value
Debug
Info 2
Warn 3
Error

Direction

Name Value
All
Entrance 1
Exit 2

LogCode

Name Value
Invalid configuration instance to start SDK 1101
Error on synchronization of member info with server 1201
Error on synchronization of access points list 1202
Error on generating key pair for member 1301
Storage problem occurred 1401
Unexpected interrupt on Bluetooth scanning flow 2101
Error on getting Adapter instance from service [Android] 2201
Failure on starting Bluetooth scanner 2202
Unexpected interrupt on Bluetooth connection flow 2301
Device not found during Bluetooth connection flow 2302
Failure on Bluetooth connection 2303
New connection request received while another one is active 2304
Unexpected interrupt on Bluetooth communication flow 2401
Informing about permission requirement of Camera 3101
Informing about permission requirement of Location 3102
Informing about permission requirement of Bluetooth 3103
Informing about need enable Bluetooth 3104
Informing about need enable Location Services 3105
Pass flow interrupted with empty action list after qr code 4101
Found qr code has empty content definition 4102
Error on showing map for location validation 4103
Invalid id on qr code content validation 4201
Invalid content data on qr code validation 4202
Invalid access point id on qr code validation 4203
Invalid location data on qr code validation 4204
Invalid terminal data on qr code validation 4205
Invalid configuration on qr code validation 4206
Invalid trigger type on qr code validation 4207
Invalid door details on qr code validation 4208
Invalid trigger type found during processing qr code 4301
Empty action data found during processing qr code 4302
QR reader found invalid format 4401
QR reader found data but it has invalid content 4402
QR reader could not find matching of valid qr code in list 4403
Empty config found during action of qr code 4501
Invalid type found during action of qr code 4502
Empty qr code content found during action of qr code 4503
Empty qr code id found during action of qr code 4504
Empty direction value found during action of qr code 4505
Empty hardware id found during action of qr code 4506
Empty relay number value found during action of qr code 4507
Checking next action has been cancelled due to invalid value 4508
Switch camera for qr code scanner is failed 5101

PassFailCode

Value Name
1001 REMOTE_ACCESS_FAILED
1002 REMOTE_ACCESS_UNAUTHORIZED
1003 REMOTE_ACCESS_NOT_CONNECTED
1004 REMOTE_ACCESS_TIMEOUT
1005 REMOTE_ACCESS_COULD_NOT_BE_SENT
1006 REMOTE_ACCESS_REQUEST_ERROR
1007 REMOTE_ACCESS_INVALID_QR_CONTENT
1008 REMOTE_ACCESS_INVALID_QR_CODE_ID
2001 BLUETOOTH_CONNECTION_FAILED
2002 BLUETOOTH_CONNECTION_TIMEOUT
2003 BLUETOOTH_EMPTY_CONFIG
2004 BLUETOOTH_INVALID_QR_CONTENT
2005 BLUETOOTH_INVALID_DIRECTION
2006 BLUETOOTH_INVALID_HARDWARE_ID
2007 BLUETOOTH_INVALID_RELAY_NUMBER
2008 BLUETOOTH_DISABLED
2009 BLUETOOTH_INVALID_NEXT_ACTION

GitHub

link
Stars: 0
Last commit: Yesterday
jonrohan Something's broken? Yell at me @ptrpavlik. Praise and feedback (and money) is also welcome.

Release Notes

v1.4.8
Yesterday

new error messages for qr code screen show stored qr code count for invalid states additional code display for some errors ios - optional close button color changed qr code scanner library

Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics