iOS

Updated March 7th 2018

Secure your iOS app with PixelPin

PixelPin for iOS

Important: Currently, iOS integrations are only available to integrators who have a PixelPin point-of-contact. If you're interested in integrating PixelPin into your iOS application, please contact our sales team.

You can download the free PixelPin iOS app from the App Store and using a supplied interface, can very easily use your PixelPin developer account information to allow people access to your iOS application by authenticating with PixelPin.

This process is secure and implements various types of cryptography in order to ensure the security of the data that passes between your app, the PixelPin app and the PixelPin web server.

The iOS application can work online-only or can cache the data offline. It is recommended that if your app is online only, that you pass 'true' to the login call and ensure that the app is online. This will avoid storing data locally but will have a performance impact over offline mode.

If you do not pass 'true' to the login call, the login data will be cached offline on the device. It is encrypted using a device-specific key but the data is vulnerable on devices that do not have a hardware security module and/or are jailbroken.

Note that you should keep your version of the iOS integration library up-to-date in your own application otherwise there is a risk that logins will be blocked or the user will be encouraged to download the PixelPin management app

Using the Interface

The PixelPin app on the App Store can be downloaded and used stand-alone but you can only interact with it by using the mobile interface archive available from here.

  1. Build and run your app to ensure it works before integrating PixelPin. This is to avoid confusion of compiler errors that might be caused by a conflict in libraries targets.

  2. Download and unzip PixelPin iOS SDK v2.5.5 to your PC. Drag the PixelPinSDK.Framework folder into your project navigator

  3. Go to your project -> Build Phases, Click + and then New Copy Files Phase

  4. Change destination to Frameworks and then click + and select the PixelPinSDK.framework

  5. The final result should look like this

  6. In Build Phases, click + and add a New Run Script Phase

  7. Use the following code in the script box

  8. Login to PixelPin and from the dashboard, choose Add/Edit Developer Accounts from the dashboard. Add a new account here, if you are not using this account for web, put in anything for the Redirect URI. If you haven't created a PixelPin developer account before, a guide can be found here to guide you through the steps to create a PixelPin developer account.

  9. Make a note of the 3 keys from the developer account.

  10. To enable the developer account for mobile use, you'll need to contact your PixelPin point-of-contact. If you don't have a PixelPin point-of-contact, please contact our sales team.

  11. Note: If you have attempted to use the developer account before contacting your PixelPin point-of-contact, it'll take up to 30 minutes for the developer account to be enabled after PixelPin grant the developer account access for mobile use.

PixelPin with Swift

  1. Import PixelPinSDK into your AppDelegate

  2. Call the following in your application startup method

    PixelPin.initialise(clientId:secret:clientKey:urlScheme:)

  3. When trying to login with PixelPin call

    PixelPin.loginWithEmail(viewController:email:callback:forceOnline:)

  4. You can pass true to forceOnline, which will ignore any offline cached login data and login online only. This is preferred for security reasons since it will not store offline data but will be slower than logging in offline.

  5. Callback is a typealias of

    (response: AnyObject?, error: PixelPinSDK.PixelPinError?) -> Void

  6. Upon successful login, the response will contain the email you tried to log in with, otherwise, nil is returned for failed login

  7. If an error occurred, the error parameter will contain a non-nil value. Read PixelPinError for further detail.

PixelPin with Objective-C

  1. Add the following to your AppDelegate

    #import <PixelPinSDK/PixelPinSDK.h>

  2. Call the following with your PixelPin keys in your application start method

    [PixelPinSDK initialise:secret:clientKey:urlScheme:]

  3. When trying to login call

    [PixelPinSDK loginWithEmail:viewController email:theEmail onSuccess:successClosure onError:errorClosure forceOnline:online]

  4. You can pass YES to forceOnline, which will ignore any offline cached login data and login online only. This is preferred for security reasons since it will not store offline data but will be slower than logging in offline.

  5. onSuccess is a closure receiving NSString and returning void, upon successful login the email will be returned, it will not be called if login fails

  6. onError is a closure receiving enum PixelPinError as a parameter, describing the error. Read PixelPinError for further detail.

Interacting with the PixelPin app

In order to handle out-of-date PixelPin SDKs, the iOS app must also interact with the PixelPin app (if it is installed). Carry out the following steps to set this up.

  1. Add LSApplicationQueriesSchemes to Info.plist

  2. Under your project info add URL Type

  3. Either add the following URL handlers, or if you already handle URLs in your app, add the bold text to the existing handlers

    • Swift:
      func application(app: UIApplication, openURL url: NSURL, options: [String: AnyObject]) -> Bool {
          PixelPinSDK.validateResponse(url.absoluteString)
          return true
      }
    • Objective-C:
      - (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary *)options {
          [PixelPinSDK validateResponse:[url absoluteString]];
          return YES;
      }

How to handle UnknownUser response

If a user without a PixelPin account attempts to log in using PixelPin, the PixelPin SDK will respond with a UnknownUser response. When this happens, we recommend you give the user a choice to register an account with PixelPin or ask them to enter another email address that is associated with an existing PixelPin account. You can do this by displaying a message to them, giving them both options.

PixelPinError

The following list shows the error codes that might be returned to your app if login fails

  1. NotInitialised: the initialisation function was not called

  2. ValidationError: PixelPin failed to validate your login information

  3. NetworkError: an error occurred while connecting to the server

  4. UnknownUser: PixelPin does not have an account with the provided email

  5. NotValidated: the account you tried to login with was not validated

  6. SdkOutdatedWarning: the login may proceed, but it is suggested that the user either updates the app, or installs the official PixelPin app

  7. SdkOutdated: the sdk is out of date, login will not be possible until updating to a newer version

  8. UserCanceled: user cancelled the login

IMPORTANT: Due to the nature of the security and the fact that our keys need to be updated, both the PixelPin application and the library are subject to updates. It is important that you are aware of these (people with developer accounts will be contacted ahead of time) and that you are able and willing to make updates to your application when these changes occur, otherwise when a public key is eventually retired, your application will stop working.

Due to these reasons and others, you should make sure that the email address on the developer accounts is up to date and checked regularly.