====== 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}}