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.
<String> Confirmation number
<String> URL of the web page
This is the signature of the method.
/** Get URL for the confirmation viewer */
-(nonnull NSString *)confirmationViewerURLForConfirmationNumber:(nonnull NSString *)confirmationNumber;
This method is called on the framework singleton:
[PTCScan sharedScan];
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
/** Setup new custom theme */
(void)setupTheme:(nonnull PTCTheme *)theme;
This method is called on the framework singleton:
[PTCScan sharedScan];
@interface PTCTheme : NSObject
@property (nonatomic, copy, nonnull) UIColor *navigationBarColor;
@property (nonatomic, copy, nonnull) UIColor *cellColor; //scan doc table view
@property (nonatomic, copy, nonnull) UIColor *backgroundColor; // scanning flow: scanning, cropping, adjustments
//Scan Documents screen
@property (nonatomic, copy, nonnull) UIColor *scanDocumentsAddExistingColor;
@property (nonatomic, copy, nonnull) UIColor *scanDocumentsTakePhotoColor;
@property (nonatomic, copy, nonnull) UIColor *scanDocumentsCollectSignatureColor;
//Scanning screen
@property (nonatomic, copy, nonnull) UIColor *scanningBorderColor;
//Adjustments screen
@property (nonatomic, copy, nonnull) UIColor *adjustmentsMenuColor;
@property (nonatomic, copy, nonnull) UIColor *adjustmentsMenuItemSelectionColor;
@end
Example
PTCTheme *customTheme = [PTCTheme new];
customTheme.navigationBarColor = [UIColor redColor];
customTheme.scanningBorderColor = [UIColor redColor];
[[PTCScan sharedScan] setupTheme:customTheme];
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.
<String> RecipientId
<String> Doctype (CSV list, optional)
<Array> Index fields, id and value for each registration field to prepopulate (optional):
Example:
[{ “id” : “DriverID”, “value” : “AB1561”}, { “id” : “BOL#”, “value” : “1X235723”}]
<String> Confirmation number
<String> Confirmation viewer URL
Session details
<Long Integer> transmission size in bytes
<Double> duration of the scan process in seconds
<Integer> number of images sent
<DateTime> time stamp
<Array> image data, for each image
<String> UUID for the image
<String> Type of encoding (jpg, png, tiff G4, etc.)
<Long Integer> Size in bytes
<Double> Quality grade (score)
There are three different methods; the first one is used for convenience when there are no doctypes and no prepopulated fields:
/** Scan */
(void) scanForRecipient:(nonnull NSString*)recipientID
success:(nonnull void(^)(PTCScanResults * _Nonnull results))success failure:(nullable void(^)(NSError *_Nonnull error))failure;
(void) scanForRecipient:(nonnull NSString*)recipientID
doctypes:(nullable NSArray*)doctypes
prepopulatedFields:(nullable NSDictionary*)fields
success:(nonnull void(^)(PTCScanResults* _Nonnull results))success failure:(nullable void(^)(NSError* _Nonnull error))failure;
(void) scanForRecipient:(nonnull NSString*)recipientID
doctypes:(nullable NSArray*)doctypes
prepopulatedFields:(nullable NSDictionary*)fields
prepopulatedDocuments:(nullable NSArray<PTCDocumentInfo *> *)documents success:(nonnull void(^)(PTCScanResults* _Nonnull results))success failure:(nullable void(^)(NSError* _Nonnull error))failure;
These methods are called on the framework singleton:
[PTCScan sharedScan];
The methods return the results of the scan process in the PTCScanResults instance.
typedef enum : NSInteger {
PTCScanQualityQuestionable = 1,
PTCScanQualityGood = 2
} PTCScanQuality;
@interface PTCScanResults : NSObject
@property (nonatomic,readonly,nonnull) NSString *confirmationNumber;
@property (nonatomic,readonly,nonnull) NSString *confirmationViewerURL;
@property (nonatomic,readonly) NSUInteger size;
@property (nonatomic,readonly) NSTimeInterval duration;
@property (nonatomic,readonly) NSUInteger numberOfImages;
@property (nonatomic,readonly,nonnull) NSDate *timestamp;
@property (nonatomic,readonly,nonnull) NSArray *imageData; // [PTCImageData]
@end
@interface PTCImageData : NSObject
@property (nonatomic,readonly,nonnull) NSString *uniqueId;
@property (nonatomic,readonly,nonnull) NSString *encoding;
@property (nonatomic,readonly) NSUInteger size;
@property (nonatomic,readonly) PTCScanQuality quality;
@end