Android

Updated July 24th 2018

Secure your Android app with PixelPin

PixelPin for Android

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

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

Create a new Android project using a Login Activity Template

Screenshots from Android Studio
  1. While in Android Studio, create a new project: File → New → New Project.... A Create New Project window will pop up. Give your Application a name, type in your company domain and choose your project location (if needed). Click Next.

  2. Phone and Tablet should be checked automatically. Choose the lowest API version your Android Application is going to support. Click Next.

    Note: This guide is based off API 23: Android 6.0 (Marshmallow)
  3. Select Login Activity. Click Next.

  4. Give your Activity, Layout, and Title a name (if needed). Click Finish to create your Android Project.

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. The first step in implementing PixelPin is to edit both of the build.gradle files in your app directory:

    1. Add the following code to the relevent build.gradle (Project: ProjectName) file. It should go in the allprojects → repositories object:

      maven {
        url  'https://developer.pixelpin.io/mobile-sdk/android'
      }
    2. Add the following code to the relevent build.gradle (Module: app) file in the dependencies object:

      implementation 'io.pixelpin:pixelpinsdk:2.4.7'
  3. Next, locate the activity_login.xml file following this path: app → res → layout → activity_login.xml. Copy and paste the following code below the email_sign_in_button:

    <Button
      android:id="@+id/button_login_pixelpin"
      android:layout_width="match_parent"
      android:layout_height="wrap_content"
      android:paddingBottom="16dp"
      android:paddingRight="40dp"
      android:paddingTop="16dp"
      android:text="Login with PixelPin"
      android:textColor="@color/pink"
      android:textSize="16sp"/>
    
  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. 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.

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

  6. 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.
  7. Next, locate the LoginActivity file following this path: app → java → your.domain.name → LoginActivity

    1. Add the following name spaces.

      import uk.co.pixelpin.pixelpinsdk.PixelPinResponse;
      import uk.co.pixelpin.pixelpinsdk.PixelPinSDK;
      import uk.co.pixelpin.pixelpinsdk.data.api.exceptions.PixelPinException;
      import android.content.Intent;
    2. Next, locate the onCreate method and add the following code to initialise the SDK. Pass the relevent developer account Client ID, Client Secret and Client Key to it:

      try {
        PixelPinSDK.initialise(this, CLIENT_ID, SECRET, CLIENT_KEY);
      } catch (PixelPinException e) {
        e.printStackTrace();
      }
    3. In the same onCreate method, add the following click handler to initiate the PixelPin Login Process:

      Button mPixelPinLoginButton = (Button) findViewById(R.id.button_login_pixelpin);
      mPixelPinLoginButton.setOnClickListener(new OnClickListener() {
          @Override
          public void onClick(View view) {
              String email = mEmailView.getText().toString();
              PixelPinSDK.loginWithEmail(LoginActivity.this, email);
          }
      });

      if you want extra security, force an online login:

      PixelPinSDK.loginWithEmail(LoginActivity.this, mEmail, true);
      Note: The user will not be able to change the email address that was inputed into the email address field after the login process starts, unless they go back to the login form to change the email.
  8. In the LoginActivity class copy and paste the following code to handle the PixelPin Response:

    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        if (requestCode == PixelPinSDK.ACTION_LOGIN) {
            if (resultCode == PixelPinResponse.SUCCESS.ordinal()) {
                Intent intentLoggedIn = new Intent(this, LoggedInActivity.class);
                intentLoggedIn.putExtra("email", data.getStringExtra("email"));
                startActivity(intentLoggedIn);
            }
        }
    }
  9. Next we're going to create a logged in activity called LoggedInActivity:

    1. To create a new pre-defined activity, right click on the folder containing the LoginActivity (The folder will be named after your domain name). Follow the following navigation path: New → Activity → Basic Activity. A New Android Activity window will pop up.

    2. Name the new activity: LoggedInActivity. Click Finish once you're ready.

  10. Next, we're going to populate the loggedInActivity's view with a logged in message and display the users email. Next locate the content_logged_in.xml file following this path: app → res → layout → content_logged_in.xml.

  11. In content_logged_in.xml, copy and paste the following code within the android.support.constraint.ConstraintLayout class:

    <ScrollView
        android:id="@+id/login_form"
        android:layout_width="match_parent"
        android:layout_height="match_parent">
        <LinearLayout
            android:id="@+id/email_login_form"
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:orientation="vertical">
            <TextView
                android:id="@+id/logged_in"
                android:layout_width="match_parent"
                android:layout_height="wrap_content"
                android:text="You're logged in!"/>
            <TextView
                android:id="@+id/pixelpin_email"
                android:layout_width="match_parent"
                android:layout_height="wrap_content"/>
        </LinearLayout>
    </ScrollView>
    
  12. Next, we're going to populate the TextView with the user's email after they finish logging in.

    1. locate the LoggedInActivity file following this path: app → java → your.domain.name → LoggedInActivity. Add the following name spaces:

      import android.widget.TextView;
    2. Copy and paste the following code into the onCreate class:

      TextView mPixelPinEmail = (TextView) findViewById(R.id.pixelpin_email);
      mPixelPinEmail.setText(getIntent().getStringExtra("email"));
  13. Note: The PixelPin App will need to be installed on the emulated or test device for the SDK to function.
  14. Run your app up in an emulator and give it a go! The email field will need to have a valid email address before you can log in using PixelPin.

How to handle UNKNOWN_USER PixelPinResponse

If a user without a PixelPin account attempts to log in using PixelPin, the PixelPin SDK will respond with a UNKNOWN_USER response. We recommend you give the user a choice to register an account with PixelPin or use another email:

  1. First, you need to locate the LoginActivity file following this path: app → java → your.domain.name → LoginActivity.

  2. Next, locate the onActivityResult method. Copy and paste the following code into the (requestCode == PixelPin.SDK.ACTION_LOGIN) if statement:

    if (resultCode == PixelPinResponse.UNKNOWN_USER.ordinal()) {
    
    }
    							

    So the full method looks like this:

    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        if (requestCode == PixelPinSDK.ACTION_LOGIN) {
            if (resultCode == PixelPinResponse.SUCCESS.ordinal()) {
                Intent intentLoggedIn = new Intent(this, LoggedInActivity.class);
                intentLoggedIn.putExtra("email", data.getStringExtra("email"));
                startActivity(intentLoggedIn);
            }
    
            if (resultCode == PixelPinResponse.UNKNOWN_USER.ordinal()) {
              //Handle the response in here
            }
        }
    }
  3. Now we can handle what happens when the user doesn't have a PixelPin account. We recommend that you display a message to the user, giving them an option to open the PixelPin app to register a new PixelPin account or use another email address. The following code opens the PixelPin app, if the user doesn't have the PixelPin app installed, it'll take them to the Play Store to download it:

    Intent intent = getPackageManager().getLaunchIntentForPackage("org.PixelPin.PixelPinMobile");
    if (intent != null) {
        intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
        startActivity(intent);
    } else {
        intent = new Intent(Intent.ACTION_VIEW);
        intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
        intent.setData(Uri.parse("market://details?id=" + "org.PixelPin.PixelPinMobile"));
        startActivity(intent);
    }

PixelPinResponse

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

  • NETWORK_ERROR: an error occurred 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: application using PixelPinSDK is severely outdated and will deny login attempts until updated.
  • USER_CANCELED: the login action was cancelled by the user
  • SUCCESS: the login was successful
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.