Updates to the HID Approve SDK for Apple iOS/macOS
This page details the design changes made in the new HID® Approve™ SDK for Apple® iOS®
Please refer to the code examples provided below that illustrate the code changes, as well as Add Functions to your App.
What's New in Version 5.14 from 5.13
The new version is currently in development and will be available soon.
What's New in Version 5.13 from 5.12
NEW HIDDeviceFactory getDevice method replaces HIDDeviceFactory newInstance
UPDATE HIDDeviceFactory reset method reviewed to be more robust
Several deprecated APIs (from SDK 5.5 and SDK 5.7.1) have been removed
What's New in Version 5.12 from 5.11
None - this is release is to provide important security updates and third-party component updates.
What's New in Version 5.11 from 5.10
SDK Additions and New Features
UPDATE retrieveActionInfo method to add HIDInexplicitContainer exception
NEWretrieveActionInfo(char[] actionId, char[] userId) method with a different signature
What's New in Version 5.10 from 5.9
SDK Additions and New Features
NEW HID_PARAM_TX_MOBILE_CONTEXT constant
UPDATE setStatus method supports the HID_PARAM_TX_MOBILE_CONTEXT parameter
What's New in Version 5.9 from 5.7.1
SDK Updates
Sequential passwords are prohibited unless explicitly authorized with password policy parameters
SDK Additions and New Features
NEW HID_DEVICE_INFO_ISROOTED constant
NEW HID_PROPERTY_ORIGINAL_CREATION_DATE constant
NEW getOriginalCreationDate accessor method
-(NSDate*)getOriginalCreationDate:(NSError**)error;
NEW isSequenceAllowed property
NEW HIDBioAuthenticationStateInvalidKey enum value for HIDBioAuthenticationState
NEW getPayload accessor method
- (NSString*)getPayload:(NSError**)error;
Bitcode support will be removed from SDK in a future version.
For further information regarding bitcode deprecation, refer to item "86118779" in the Apple XCode 14 Release Notes.
What's New in Version 5.7.1 from 5.5
SDK Updates
Migration to 5.7.1 from versions 3.0 and 4.0 is no longer supported.
SDK Additions and New Features
REMOVED retrieveTransaction deprecated method
NEW retrieveActionInfo method
- (id<HIDServerActionInfo>)retrieveActionInfo:(NSString*)actionId error:(NSError**)error;
REMOVED createContainer deprecated method (use createContainer with sessionPassword)
REMOVED reset deprecated method (use HIDDeviceFactory reset)
REMOVED getDefaultInitializationPolicy deprecated method (use HIDProgressListener)
DEPRECATED updateDeviceInfo method (use HIDContainer updateDeviceInfo)
REMOVED initialPassword deprecated property (use HIDProgressListener)
NEW HIDUnsupportedVersion enumeration value (7)
NEWHIDInvalidContainer enumeration value (8)
UPDATE Class declaration inherits from HIDServerAction class
REMOVED setStatus deprecated method (use setStatus with password)
NEW updateDeviceInfo method (moved from HIDDevice)
(BOOL)updateDeviceInfo:(NSString*)propertyId withValue:(NSString*)propertyValue withPassword:(NSString*)sessionPassword withParams:(NSArray*)parameters error:(NSError**)error
DEPRECATED TransactionInfo class (use retrieveActionInfo)
NEW ServerAction class
NEW ServerActionInfo class
To support framework target integrations, the XCFramework package now includes a clang modulemap header.
To support Apple optimization technology aimed at reducing the application binary size, the SDK framework fully supports Bitcode. For further information, refer to the Apple documentation.
What's New in Version 5.5 from 5.4
SDK Updates
iOS versions 10.0 and 11.0 are no longer supported.
SDK Additions and New Features
NEW newInstance method
-(id<HIDDevice>)newInstance:(HIDConnectionConfiguration*)config error:(NSError**)error;
DEPRECATED newInstance method
-(id<HIDDevice>)newInstance:(HIDConnectionConfiguration*)config withSessionPassword:(NSString*)sessionPassword error:(NSError**)error;
NEW HID_PARAM_PASSWORD_PROGRESS_EVENT_TYPE; ///< password event type
NEW HID_PARAM_PASSWORD_PROGRESS_EVENT_KEY_LABEL; ///< password event key label
NEW HID_PARAM_PASSWORD_PROGRESS_EVENT_KEY_USAGE; ///< password event key usage
NEW HID_PARAM_PASSWORD_PROGRESS_EVENT_TYPE_CONTAINER; ///< password event type container
NEW HID_PARAM_PASSWORD_PROGRESS_EVENT_TYPE_KEY; ///< password event type key
Documentation has been updated to specify possible exceptions on some functions and methods.
What's New in Version 5.4 from 5.1
SDK Updates
NEW HIDInvalidArgument to replace thrown exception NSInvalidArgumentException in the SDK
SDK Additions and New Features
NEW HIDInvalidArgument enumeration value for HIDErrorCode
NEW HIDLockTypeSilent enumeration value for HIDLockType
NEW HID_KEY_PROPERTY_USAGE_OPPRO constant
What's New in Version 5.1 from 4.0
SDK Updates
HIDTransactionInfo
NEW getTransaction method
-(id<HIDTransaction>)getTransaction:(NSString*)sessionPassword withParams:(NSArray*)parameters error:(NSError**)error;
HIDTransaction
UPDATE protocol moved from HIDDevice.h header
HIDProgressListener
UPDATE protocol moved from HIDDevice.h header
UPDATE onEventReceived method
- (HIDEventResult*)onEventReceived:(id<HIDEvent>)event;
HIDProgressEvent
UPDATE protocol moved from HIDDevice.h header
NEW HIDEventResultCode enumeration
NEW HIDPasswordPromptResult interface
NEW HIDEvent protocol
HIDContainerInitialization
UPDATE interface moved from HIDDevice.h header
DEPRECATED initialPassword field (use ProgressListener)
HIDDevice
DEPRECATED retrieveTransaction method (use TransactionInfo.getTransaction)
-(id<HIDTransaction>)retrieveTransaction:(NSString*)transactionId withPassword:(NSString*)sessionPassword withParams:(NSArray*)parameters error:(NSError**)error;
DEPRECATED createContainer method (use new method)
-(id<HIDContainer>)createContainer:(HIDContainerInitialization*)config withListener:(NSObject<HIDProgressListener>*)listener error:(NSError**)error;
DEPRECATED reset method (use new method HIDDeviceFactory.reset)
- (BOOL)reset:(NSArray*)parameters error:(NSError**)error;
DEPRECATED getDefaultInitializationPolicy method (use ProgressListener)
- (id<HIDProtectionPolicy>)getDefaultInitializationPolicy:(NSError**)error;
NEW createContainer method
-(id<HIDContainer>)createContainer:(HIDContainerInitialization*)config withSessionPassword:(NSString*)sessionPassword withListener:(NSObject<HIDProgressListener>*)listener error:(NSError**)error;
HIDDeviceFactory
DEPRECATED newInstance method (use new method)
-(id<HIDDevice>)newInstance:(HIDConnectionConfiguration*)config error:(NSError**)error;
NEW newInstance method
-(id<HIDDevice>)newInstance:(HIDConnectionConfiguration*)config withSessionPassword:(NSString*)sessionPassword error:(NSError**)error;
NEW reset method
+(void)reset:error:(NSError**)error;
SDK Additions and New Features
NEW HIDContainerRenewal interface
HIDContainer
NEW getCreationDate method
-(NSDate*)getCreationDate:(NSError**)error;
NEW getExpiryDate method
-(NSDate*)getExpiryDate:(NSError**)error;
NEW getRenewalDate method
-(NSDate*)getRenewalDate:(NSError**)error;
NEW isRenewable method
-(Boolean)isRenewable:(NSString*)sessionPassword error:(NSError**)error;
NEW renew method
-(Boolean)renew:(HIDContainerRenewal*)config withSessionPassword:(NSString*) sessionPassword withListener:(NSObject<HIDProgressListener>*)listener error:(NSError**)error;
HIDErrorCode
NEW HIDPasswordCancelled enumeration value
NEW HIDServerUnsupportedOperation enumeration value
NEW HIDServerOperationFailed enumeration value
What's New in Version 4.0 from 3.0
SDK Addition
HIDContainer
NEW IsFIPSModeEnabled method – Reserved for Future Use.
Code Examples
Transaction Retrieval
NSError* error;
// get device
HIDConnectionConfiguration* connectionConfig = [[HIDConnectionConfiguration alloc] init];
id<HIDDevice> pDevice = [[HIDDeviceFactory alloc] newInstance:connectionConfig error:&error];
// get transaction
id<HIDTransactionInfo> pTransactionInfo = [pDevice retrieveTransactionInfo:transactionId error:&error];
id<HIDTransaction> pTransaction = [pDevice retrieveTransaction:myTransactionId withPassword:mySessionPwd withParams:nil error:&error];
NSError* error;
// get device
HIDConnectionConfiguration* connectionConfig = [[HIDConnectionConfiguration alloc] init];
id<HIDDevice> pDevice = [[HIDDeviceFactory alloc] newInstance:connectionConfig withSessionPassword:mySessionPwd error:&error];
// get transaction
id<HIDTransactionInfo> pTransactionInfo = [pDevice retrieveTransactionInfo:myTransactionId error:&error];
id<HIDTransaction> pTransaction = [pTransactionInfo getTransaction:mySessionPwd withParams:nil error:&error];
NSError* error;
// get device
HIDConnectionConfiguration* connectionConfig = [[HIDConnectionConfiguration alloc] init];
id<HIDDevice> pDevice = [[HIDDeviceFactory alloc] newInstance:connectionConfig error:&error];
// get transaction
id<HIDTransactionInfo> pTransactionInfo = [pDevice retrieveTransactionInfo:myTransactionId error:&error];
id<HIDTransaction> pTransaction = [pTransactionInfo getTransaction:mySessionPwd withParams:nil error:&error];
Provisioning / Container Creation
// progress listener
-(void)onEventReceived:(id<HIDProgressEvent>)event {
NSArray* params = [event parameters];
NSString* message; NSString* percent;
for (HIDParameter* p in params) {
if ( [[p key] caseInsensitiveCompare:HID_PARAM_PROGRESSEVENT_MESSAGE]==NSOrderedSame)
message = [p value];
if ( [[p key] caseInsensitiveCompare:HID_PARAM_PROGRESSEVENT_PERCENT]==NSOrderedSame)
percent = [p value];
}
NSString* text = [NSString stringWithFormat:@"%@ (%@)", message, percent];
NSLog(@"Event Received: %@", text);
}
// provisioning
-(void)doProvisioning {
NSError* error;
// get device
HIDConnectionConfiguration* connectionConfig = [[HIDConnectionConfiguration alloc] init];
id<HIDDevice> pDevice = [[HIDDeviceFactory alloc] newInstance:connectionConfig error:&error];
// new container
HIDContainerInitialization* config = [[HIDContainerInitialization alloc] init];
config.activationCode = [[NSString alloc] initWithData:myActivationCodeData encoding:NSUTF8StringEncoding];
config.initialPassword = myInitialPassword;
config.pushId = myPushID;
config.containerFriendlyName = myServiceName;
id<HIDContainer> pContainer = [pDevice createContainer:config withListener:self error:&error];
}
// progress listener
-( HIDEventResult*)onEventReceived:(NSObject<HIDEvent>*)event {
if ([event isKindOfClass:[HIDPasswordPromptEvent class]]) {
// password request
HIDPasswordPromptEvent* pPwdEvent = (HIDPasswordPromptEvent*)event;
return [[HIDPasswordPromptResult alloc] initWithCode:Continue andPassword:myInitialPassword];
}
else { // progress message
NSArray* params = [event parameters];
NSString* message; NSString* percent;
for (HIDParameter* p in params) {
if ( [[p key] caseInsensitiveCompare:HID_PARAM_PROGRESSEVENT_MESSAGE]==NSOrderedSame)
message = [p value];
if ( [[p key] caseInsensitiveCompare:HID_PARAM_PROGRESSEVENT_PERCENT]==NSOrderedSame)
percent = [p value];
}
NSString* text = [NSString stringWithFormat:@"%@ (%@)", message, percent];
NSLog(@"Event Received: %@", text);
}
return [[HIDEventResult alloc] initWithCode:(Continue)];
}
// provisioning
-(void)doProvisioning {
NSError* error;
// get device
HIDConnectionConfiguration* connectionConfig = [[HIDConnectionConfiguration alloc] init];
id<HIDDevice> pDevice = [[HIDDeviceFactory alloc] newInstance:connectionConfig withSessionPassword:mySessionPwd error:&error];
// new container
HIDContainerInitialization* config = [[HIDContainerInitialization alloc] init];
config.activationCode = [[NSString alloc] initWithData:myActivationCodeData encoding:NSUTF8StringEncoding];
// NOTE: “config.initialPassword” is not supported; use listener
config.pushId = myPushID;
config.containerFriendlyName = myServiceName;
id<HIDContainer> pContainer = [pDevice createContainer:config withSessionPassword:mySessionPwd withListener:self error:&error];
}
// progress listener
-( HIDEventResult*)onEventReceived:(NSObject<HIDEvent>*)event {
if ([event isKindOfClass:[HIDPasswordPromptEvent class]]) {
// password request
HIDPasswordPromptEvent* pPwdEvent = (HIDPasswordPromptEvent*)event;
return [[HIDPasswordPromptResult alloc] initWithCode:Continue andPassword:myInitialPassword];
}
else { // progress message
NSArray* params = [event parameters];
NSString* message; NSString* percent;
for (HIDParameter* p in params) {
if ( [[p key] caseInsensitiveCompare:HID_PARAM_PROGRESSEVENT_MESSAGE]==NSOrderedSame)
message = [p value];
if ( [[p key] caseInsensitiveCompare:HID_PARAM_PROGRESSEVENT_PERCENT]==NSOrderedSame)
percent = [p value];
}
NSString* text = [NSString stringWithFormat:@"%@ (%@)", message, percent];
NSLog(@"Event Received: %@", text);
}
return [[HIDEventResult alloc] initWithCode:(Continue)];
}
// provisioning
-(void)doProvisioning {
NSError* error;
// get device
HIDConnectionConfiguration* connectionConfig = [[HIDConnectionConfiguration alloc] init];
id<HIDDevice> pDevice = [[HIDDeviceFactory alloc] newInstance:connectionConfig error:&error];
// new container
HIDContainerInitialization* config = [[HIDContainerInitialization alloc] init];
config.activationCode = [[NSString alloc] initWithData:myActivationCodeData encoding:NSUTF8StringEncoding];
// NOTE: “config.initialPassword” is not supported; use listener
config.pushId = myPushID;
config.containerFriendlyName = myServiceName;
id<HIDContainer> pContainer = [pDevice createContainer:config withSessionPassword:mySessionPwd withListener:self error:&error];
}