Android

Updated February 7th 2017

Secure your Android app with PixelPin

PixelPin for Android

You can download the free PixelPin Android app from the Play store and using a supplied interface, can very easily use your existing developer account information to allow people access to your Android 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 Android 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 rooted.

Note that you should keep your version of the Android 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 Play 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. Make sure that your project is up to date, builds and runs correctly before adding PixelPin. This is to avoid project conflicts which might not relate to the integration of PixelPin but might instead relate to a Gradle or Android version update.

  2. Add pixelpin_android_sdk_x_x.aar to yourproject/app/libs/ directory - copying into the libs directory will automatically synchronize it with the project.

  3. Edit build.gradle in your app directory:

    1. Add the following code if it’s not already present:

      repositories {
          jcenter()
          flatDir {
              dirs 'libs'
          }
      }
    2. Under dependencies add the following

      compile (name: 'pixelpinsdk', ext: 'aar')

  4. 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.

  5. Before you use PixelPin initialise it by passing the relevant constants to:

    PixelPinSDK.initialise(CLIENT_ID, SECRET, CLIENT_KEY);
  6. Note that you will need the namespace, if it is not added automatically, which is

    import uk.co.pixelpin.pixelpinsdk.PixelPinSDK;
  7. When you want the user to login, call the following. Note that the user will not be able to change the email address used to login from that which is passed here:

    PixelPinSDK.loginWithEmail(mActivity, mEmail);

    Or if you want extra security, force an online login:

    PixelPinSDK.loginWithEmail(mActivity, mEmail, true);
  8. In the calling activity implement onActivityResult method:

    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        if (requestCode == PixelPinSDK.ACTION_LOGIN) {
        // Make sure the request was successful or handle the errors
        if ( resultCode == PixelPinResponse.SUCCESS.ordinal())
        {
            startActivity(new Intent(this, LoggedInActivity.class));
        }
    }

To access the more descriptive value simply use PixelPinResponse.values()[resultCode].

Upon successful login the data parameter will contain a String extra with email. To get the email use the following:

data.getStringExtra("email")
which you can use to verify the email that was used to login. In the future, it might be possible for the user to change the email they are using to login so the app should check this value matches what was expected if it is important.

PixelPinResponse

Here is a list of responses that the SDK can return and their short description

  • NETWORK_ERROR: an error occured while trying to connect to the server.
  • LOGIN_NO_EMAIL: the email was invalid or not specified
  • UNKNOWN_USER: the user does not appear to have a PixelPin account.
  • SESSION_TIMEOUT: the session timed out while the user was logging in.
  • OUTDATED: aplication using PixelPinSDK is severly outdated and will deny login attempts until updated.
  • USER_CANCELED: the login action was canceled by the user
  • SUCCESS: the login was successful

Important Notes

If the user does not have a PixelPin account when they attempt to login to your application, they will be offered the chance to register. They will have to register the email address that your app has passed into the PixelPin app (they cannot decide to change it to another one). If they continue this process, they will have to verify the account before control is passed back to your app but the PixelPin interface will verify that the email that was registered matches the one you originally requested.

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.