Transflo Mobile Scanning Framework: iOS

Minimum iOS version supported: 11.0

Type: Dynamic framework, Objective C++

Supported architectures: release and debug; 32-bit and 64-bit architectures: armv7, arm 64, i386, x86_64; interface: public header file with public methods.

The methods will use callback blocks to send results back to the host app; custom classes will be used to hold the needed input parameters and output results.

External dependencies: Cocoapods dependency management, C/C++ libraries

 

External Dependencies: Cocoapods pod

'UIView+TKGeometry' pod

'MBProgressHUD'

pod 'objective-zip', '0.8.0'

pod 'RestKit', :git => 'https://github.com/RestKit/RestKit'

pod 'APLKeyboardControls'

pod 'UIAlertView+Blocks' pod 'OpenCV', '2.4.9'

pod 'ZBarSDK' pod 'libpng' pod 'SignatureView'

pod ‘DPLocalization'

External Dependencies: C/C++ libraries

These are statically linked inside the framework libtiff

4.0.3

OpenCV 2.4.9

Description

The initialization method is called before proceeding to other API calls. This method can be called at any time. Calling this method does not predetermine the next step or steps.

The purpose of this call is to make sure all dependencies are in place and that the required environment checks also take place. Based upon the response returned, the caller or host app will know if subsequent calls to other APIs are expected to complete successfully.

Input Parameters

<String> LicenseKey: license key to use the framework

<String> App ID or SourceApp e.g. com.werner.mobileapp

<String> App Name: used to display the app name in a warning for the camera access

<String> Email address of the user / Alternatively, Unique ID for the user

<String> First name of the user (optional)

<String> Last name of the user (optional)

<String> Phone number of the user (optional)

<Array> Recipient registration; for each recipient:

<String> RecipientId

<Array> Registration fields, id and value for each registration field

Example:

[{"fields":[{"id":"driverid","value":"abc"},{"id":"pin","value":"123"},

{"id":"password","value" :"xcx"}],"recipientId":"TFLO05F1"},{"fields":

[{"id":"driverid","value":"w21"},{"id":"passwor d","value":"vcx1c"}],"recipientId":"TESTFLEET"}]

Results

Success block

Failure block

<Error> error: error code and description

Method Signature and Usage

The first step is to initialize the framework using the following method:

/** Initialization and registration */

(void) setupWithConfig:(nonnull PTCScanConfig*)scanConfig

success:(nonnull void(^)(void))success

failure:(nullable void(^)(NSError* _Nonnull error))failure;

This method is called on the framework singleton:

[PTCScan sharedScan];

The method handles the authentication with Pegasus TransTech cloud and prepares the scan framework for scanning.

The PTCScanConfig instance includes all the parameters needed for the initialization of the framework:

@interface PTCScanConfig : NSObject

@property (nonatomic,copy,nonnull) NSString* licenseKey;

@property (nonatomic,copy,nonnull) NSString* appID;

@property (nonatomic,copy,nonnull) NSString* appName;

@property (nonatomic,copy,nonnull) NSString* email;

@property (nonatomic,copy,nullable) NSString* firstName;

@property (nonatomic,copy,nullable) NSString* lastName;

@property (nonatomic,copy,nullable) NSString* phone;

@property (nonatomic,assign) BOOL hideConfimationPageOnScan;

@property (nonatomic,copy,nonnull) NSArray* recipientsRegistration;

// [PTCScanRecipient]

@end

The PTCScanRecipient instance includes the necessary information for each fleet:

@interface PTCScanRecipient : NSObject

@property (nonatomic,copy) NSString* recipientId;

@property (nonatomic,strong) NSArray* fields;

@end

Example

We want to initialize the framework with Fleets TFLO05F2 and TFLO05F5.

1. Configure the Fleets with the necessary information:

PTCScanRecipient *recipient1 = [[PTCScanRecipient alloc] init]; recipient1.recipientId = @"TFLO05F2";

recipient1.fields = @[ @{ kPTCScanFieldIdKey : @"EmployeeId", kPTCScanFieldValueKey : @"AB123445L" },

@{ kPTCScanFieldIdKey : @"DivisionId",

kPTCScanFieldValueKey : @"07896732" },

@{ kPTCScanFieldIdKey : @"Description",

kPTCScanFieldValueKey : @"Hazmat certified" } ];

PTCScanRecipient *recipient2 = [[PTCScanRecipient alloc] init]; recipient2.recipientId = @"TFLO05F5";

recipient2.fields = @[ @{ kPTCScanFieldIdKey : @"DivisionId", kPTCScanFieldValueKey : @"567421" } ];

2. Configure the user information:

PTCScanConfig *config = [[PTCScanConfig alloc] init];

config.licenseKey = @"1239BD3FB17ABA8B20D8A7556F207CB50BB4A572"; config.appID = @"com.werner.mobileapp";

config.appName = [[NSBundle mainBundle] objectForInfoDictionaryKey:@"CFBundleName"];

config.email = @"john.doe@example.com"; config.firstName = nil; config.lastName = nil;

config.phone = nil;

config.hideConfimationPageOnScan = YES;

config.recipientsRegistration = @[ recipient1, recipient2 ];

3. Initialize the framework:

[[PTCScan sharedScan] setupWithConfig:config success:^{

// handle the success scenario

} failure:^(NSError *error) {

// handle the error scenario, information of the error is available in the error object

}];

The Confirmation Screen method of the framework is called to get more data about any prior document scanning session, indicated by the confirmation number provided as the input parameter.

Input Parameters

<String> Confirmation number

Results

Success block

Failure block

<Error> error: error code and description

Method Signature and Usage

This is the signature of the method.

/** Confirmation Screen */

(void) displayConfirmationNumber:(nonnull NSString*)confirmationNumber;

This method is called on the framework singleton:

[PTCScan sharedScan];

The method returns after the user dismisses the confirmation number screen or if any error occurs (e.g., the confirmation number was not found).

The Confirmation Viewer URL method of the framework is called to get the URL of the confirmation viewer web page for a given confirmation number. The web page allows the user to browse all the information of the uploaded documents.

An optional custom theme to match the host application can be sent to the SDK. If not added, the default values are kept for the customizable UI elements.

Customizable elements:

• Navigation bar color

• Screens background color

• Buttons background color (Add existing and Take photo buttons)

• Scanning border color

• Adjustments menu background color

• Adjustments menu selection color

This optional method is called to obtain the registration fields for a specific fleet. This method can be called at any time. Calling this method does not predetermine the next step or steps.

The purpose of this method is to provide an integrated host app with the necessary information about the registration fields of a fleet. This information might be useful to build a customized UI presented to enable the user to enter the values for the registration fields.

Input Parameters

<String> LicenseKey: license key to use the framework

<String> RecipientId:

Results

Success block with registration fields

<String>RecipientId

<String>Name: fleet name

<Array>Registration Field Descriptors, for each field:

<String>Id

<String>DataType: Alpha, Numeric or All

<String>Prompt

<Boolean>Required

<Integer>MaxLength: maximum number of characters/digits allowed

<Integer>MinLength: minimum number of characters/digits allowed

Failure block

<Error> error: error code and description

Method Signature and Usage

This is the signature of the method:

/** Get Fleet Registration Fields */

(void) FleetRegistrationFieldsForRecipient:(nonnull NSString*)recipientID

licenseKey: (nonnull NSString*)licenseKey

success:(nonnull void(^)(PTCRecipientDescriptor* _Nonnull recipientDescriptor))success failure:(nullable void(^)(NSError* _Nonnull error))failure;

This method is called on the framework singleton:

[PTCScan sharedScan];

The method returns the specification of the registration fields for the specified fleet.

The result is returned in the PTCRecipientDescriptor instance.

@interface PTCRecipientDescriptor : NSObject

@property (nonatomic,readonly,nonnull) NSString *recipientId;

@property (nonatomic,readonly,nonnull) NSString *name;

@property (nonatomic,readonly,nonnull) NSArray *fieldDescriptors;

// [PTCFieldDescriptor]

@end

The specification for each of the registration fields is described by the PTCFieldDescriptor instance:

@interface PTCFieldDescriptor : NSObject

@property (nonatomic,copy,nonnull) NSString *fieldId;

@property (nonatomic,copy,nonnull) NSString *dataType;

@property (nonatomic,copy,nonnull) NSString *prompt;

@property (nonatomic) bool required;

@property (nonatomic) NSInteger minLength;

@property (nonatomic) NSInteger maxLength;

@end

Example

We want to initialize the registration fields for Fleet TFLO05F2.

[[PTCScan sharedScan] fleetRegistrationFieldsForRecipient: @"TFLO05F2"

licenseKey: @"1239BD3FB17ABA8B20D8A7556F207CB50BB4A572" success:^(PTCRecipientDescriptor *recipientDescriptor) {

// handle success scenario

// requested information in recipientDescriptor

}

failure:^(NSError *error) {

// handle failure scenario

// check the error object for more info

}];

This method is called to obtain the email or user ID of the registered user. If there is no user registered, the method returns nil.

Input Parameters

None

Results

String: Registered user email

Method Signature and Usage

This is the signature of the method.

/** Get the registered user */

-(nullable NSString *)registeredUserEmail;

This method is called on the framework singleton:

[PTCScan sharedScan];

The Scan method of the library is called to capture and send documents to the Pegasus cloud. The purpose of this call is to start and complete the document sending steps. This is the primary method for the framework and is expected to get the most use.

This method includes processes for capturing the document as an image and accepting images that were already taken. Like the TRANSFLO® Mobile+ application, this method will also handle cropping, processing, compressing, and enhancing those images prior to sending them to the Pegasus TransTech cloud.

The user will also have the option to review and retake each document image. After each image is scanned and before scanning the next image, the user receives a selection prompt for a document type populated with the provided document type description list.

The user must select a document type for the current image and before proceeding to the next image. This is how a driver provides the suggested document type, even though Pegasus Transtech may later override this document type as part of their system processes.