Differences

This shows you the differences between two versions of the page.

Link to this comparison view

mobile-integration:ios [2019/08/01 10:04] (current)
tjotov created
Line 1: Line 1:
 +====== iOS implementation of PEIG API ======
 +
 +===== Description =====
 +
 +Integration of PEIG API for iOS platform is implemented by using framework in targeted application. Framework, named as //​PeigApiLib.framework//,​ is part of the package. This framework is archived as ZIP file. Must be extracted on OSX system, because contains **symlinks** (symlinks doesn'​t work on Windows system).
 +
 +It is recommended to use Xcode 6.4 for using PeigApiLib framework.
 +
 +===== How integrate PEIG API framework =====
 +
 +Framework //​PeigApiLib.framework//​ must be included into Xcode project, in project settings, choose Build Phases, section Link Binary With Libraries, see below image.
 +
 +{{  :​developers:​peig-api:​peig-api-ios.png?​nolink&​700x317 ​ }}
 +
 +Framework contains next important classes (public headers):
 +
 +  * PeigApiLib.h - Contains main method for call ADUCID authentication and for another ADUCID operations
 +  * LibServiceDelegate.h - Allow send message to another object, that ADUCID authentication (or another operation) is completed, Success or Failed
 +  * ApiResult.h - Class manages ADUCID authentication result
 +
 +In the source code, use the following import
 +
 +<code objc>
 +#​import<​PeigApiLib/​LibServiceDelegate.h>​
 +
 +#​import<​PeigApiLib/​ApiResult.h>​
 +</​code>​
 +
 +Class LibServiceDelegate has two methods:
 +
 +<code objc>
 +-(void) onSuccess:​(ApiResult*) result;
 +
 +-(void) onFailed:​(NSString*) error;
 +</​code>​
 +
 +===== How authenticate with PEIG =====
 +
 +First, import class:
 +
 +<code objc>
 +#​import<​PeigApiLib/​PeigApiLib.h>​
 +</​code>​
 +
 +Thereafter call method:
 +
 +<code objc>
 +[[PeigApiLib sharedInstance] aducidAuthenticate:​url withDelegate:​delegate withDataSourceCompletionHandler:​^(ApiResult* result) {
 +
 +    } withDataSourceErrorHandler:​^(NSString *error) {
 +
 +}];
 +</​code>​
 +
 +where:
 +
 +  * url - is NSString, in format <​nowiki>​[protocol]://​[domain]/​[path]/</​nowiki>,​ in DemoBank application is <​nowiki>​https://​demobank.aducid.com/​demobank/</​nowiki>​
 +  * delegate - is <​nowiki>​id<​LibServiceDelegate></​nowiki>,​ typically reference to ViewController,​ see DemoBank, class LoginViewController.h
 +
 +LoginViewController implements LibServiceDelegate and methods:
 +
 +<code objc>
 +-(void) onSuccess:​(ApiResult *) result {
 +  ...
 +}
 +
 +-(void) onFailed:​(NSString *) error {
 +  ...
 +}
 +</​code>​
 +
 +See DemoBank application,​ class LoginViewController and other, eg. CHService. To the evaluate ApiResult - see [[:​developers:​peig-api|PEIG API documentation]].
 +
 +===== Response ApiResult =====
 +
 +Your code should evaluate these possible outcomes:
 +
 +<code objc>
 +if [result isOK]
 +</​code>​
 +
 +Session is authenticated.
 +
 +<code objc>
 +else if [result peigNotInstalled]
 +</​code>​
 +
 +PEIG is not installed, code
 +
 +<code objc>
 +      [[PeigApiLib sharedInstance] openAppStoreDetail]
 +</​code>​
 +
 +opens ITUNES detail page.
 +
 +<code objc>
 +else
 +</​code>​
 +
 +other exception / redirect / state.
 +
 +Custom application errors, authentication failed!
 +
 +  * <code objc>​result.exception</​code>​ contains ADUCID exception, there are possible states:
 +      * <code objc>​[result notAcceptedByUser]</​code>​ user rejected
 +      * <code objc>​[result isFactorAbsent]</​code>​ user doesn’t have personal factor (and server requires it)
 +  * <code objc>​result.data</​code>​ contains error message / reason
 +  * <code objc>​[result doRedirect],​ result.redirect</​code>​ contains page that could be opened using browser / contains additional content to download / display to the user.
 +
 +See ApiResult class for all details.
 +
 +===== Handle result from PEIG =====
 +
 +PeigApiLib works with URI scheme. It is important to forward URi request from PEIG to PeigApiLib. Please, see class THAppDelegate in DemoBank application.
 +
 +<code objc>
 +- (BOOL)application:​(UIApplication*)application handleOpenURL:​(NSURL*)url
 +
 +{
 +
 +[[PeigApiLibsharedInstance]handleOpenURL:​url];​
 +
 +returnYES;
 +
 +}
 +</​code>​
 +
 +Method handleOpenURL is defined in protocol class **UIApplicationDelegate**.
 +
 +===== Retrieving data when it is authenticated =====
 +
 +In case ApiResult is “OK” and mobile application is authenticated,​ use this session to contact your application server by using PeigApiLib library.
 +
 +You can use GET or POST operations. See PeigApiLib class.
 +
 +<code objc>
 +- (void) getAducidOperation:​(NSString*)url withParameters:​(id)params withDelegate:​(id<​LibServiceDelegate>​)delegate withDataSourceCompletionHandler:​(void (^) (ApiResult*))successDataHandler withDataSourceErrorHandler:​(void (^)(NSString*))failureDataHandler;​
 +
 +- (void) postAducidOperation:​(NSString*)url withParameters:​(id)params withDelegate:​(id<​LibServiceDelegate>​)delegate withDataSourceCompletionHandler:​(void (^) (ApiResult*))successDataHandler withDataSourceErrorHandler:​(void (^)(NSString*))failureDataHandler;​
 +</​code>​
 +
 +**url** ​ - target page or method URL, e.g. [[https://​demobank.aducid.com/​demobank/​payment|https://​demobank.aducid.com/​demobank/​payment]]
 +
 +**params** ​ - reference to object with parameters, e.g. NSDictionary object in DemoBank application,​ class CHService
 +
 +**delegate** ​ - reference to delegate for callback when data is loaded
 +
 +Please, have a look at class PaymentViewController in DemoBank application. There is the example how to use POST request.
 +
 +==== Try to get data if it is not authenticated ====
 +
 +Check your setup, test if you get error response from the server.
 +
 +===== How PEIG starts mobile application =====
 +
 +PEIG sends response back to mobile application via URI scheme. Please, define URI scheme for your mobile application in //​info.plist// ​ file. For DemoBank application is defined as //​aducid-demobank//​. See image below:
 +
 +{{:​developers:​peig-api:​peig-api-ios-calls.png?​nolink&​599x149}}
 +
  
  • mobile-integration/ios.txt
  • Last modified: 2019/08/01 10:04
  • by tjotov