Introduction

The biid Core SDK is the easiest way to use the biid Platform in an Android app. The biid Core SDK library contains a biid Client. This client handles communication with the biid Platform and manages the biid digital certificates.

core sdk integration

The developers guide describes how to integrate the biid Core SDK library and use the biid Client. For further details please check the javadoc.

Integration

Android Studio

Include the biid Core SDK library as a dependency in your gradle project:

repositories {

    ...

    maven {
        url "http://nexus.stage-biid.com/content/repositories/client-releases"
    }

    ...
}

dependencies {

    ...

    compile ('com.biid:sdk-core-android:3.1.277'){transitive=true}

    ...
}

Supported Android API levels

The biid Core SDK library supports Android API level 21 and higher.

Manifest

biid will provide you with a manifest file. Place this file in the assets directory of your Android project.

Initialization

Get a reference to the biid Client like this:

Client client = Sdk.getClient();

The first call to the client must be

client.initialize(context);

Logging in

After the client is initialized, you must authenticate the user with a username and access token from the security provider.

This selects the entity that is passed in, or if no entity is passed in, the entity linked to the app.

client.authenticate(username, accessToken, entity);

If any call fails with an InvalidTokenException, check the resolution in the exception:

if (exception.getResolution() == InvalidTokenException.Resolution.LOGIN) {
    // get a new access token and authenticate again
} else if (exception.getResolution() == InvalidTokenException.Resolution.CHECK_DEVICE_TIME_AND_LOGIN) {
    // prompt the user to check the device time, get a new access token and authenticate again
} else { // InvalidTokenException.Resolution.RETRY
    // try the call that failed again
}

Check which entity is selected with:

client.getSelectedEntity()

Multiple entities

The following is only relevant for apps that support multiple entities.

To get a list of entities the user is linked to, use:

List<Entity> entities = client.requestEntitiesForUser();

Or, if the user wants to add another entity, get an entity by url name with:

Entity entity = client.requestEntity(urlName);

Use this call to select another entity:

client.selectEntity(entity);

When you make any other call to the client, the selected entity will be implied.

Certification

For a user to be able to authenticate or sign documents they need to have a digital certificate on the device. This requires three steps.

Verification

The device the app runs on needs to be verified before the user can be certified. Even if the app supports multiple entities, the device only needs to be verified once.

Before the device is verified, the user has status UNVERIFIED.

First the user requests an verification code:

client.requestUserDeviceVerification();

An SMS with the verification code will be send to the phone number the user registered with. When the user receives the code, they can verify the device:

client.verifyUserDevice(code);

Registration

After verification the user will have status UNREGISTERED:

client.requestUser().getStatus() == User.Status.UNREGISTERED

The user needs to fill in a registration form.

List<FieldDefinition> fields = client.requestEntityDetails().getUserFieldDefinitions();

// user enters a value for each field

Which will be send off like this:

User user = new User();
for (FieldDefinition field : fields) {
   user.put(field.getName(), value)
}

client.registerUser(user);

Note that if field.isReadOnly() is true, changes in the value of the field will be ignored.

Certification

A registered user on a verified device will have status UNCERTIFIED.

Accreditation Level L1

If an entity is configured to support level L1, a registered user automatically becomes accredited at level L1.

user.getAccreditationLevel() == User.AccreditationLevel.L1

The app can request a certificate without user interaction:

client.certifyUserAtLevelL1(context);

Accreditation Level L2

Accreditation levels above L1 require a formal accreditation process, which culminates in an operator accrediting the user.

If the user already has an certificate, that certificate will be revoked.

A Digital Identity Access Code (DIAC) will be send to the user by SMS or email. After the user enters the DIAC, the app requests a certificate with:

client.certifyUser(context, diac);

Accreditation Level L3

Accreditation level L3 requires that the user visits a checkpoint to get accredited.

List<Checkpoint> checkpoints = client.requestCheckpoints(max, offset, location, order);

The DIAC will be send by post. After the user enters the DIAC, the app requests a certifcate with:

client.certifyUser(context, diac);

Requesting a digital certificate

Both certify requests create a digital certificate on the device. A signing request for this certificate is sent off to a Certificate Authority (CA). The user is now in status CERTIFICATE_PENDING.

After the certificate has been signed by the CA the user will be in status CERTIFIED and can authenticate and sign documents.

Authenticating and signing

A certified user can handle two kinds of transactions: authentication requests and document signing requests. To get a paged and filtered list of transactions, use:

List<Transaction> transactions = client.requestTransactions(offset, max, statuses, type, documentType);

Authentication requests

A user may confirm an authentication request like this:

AuthenticationTransaction transaction = requestAuthenticationTransaction(id);

client.confirmAuthentication(transaction);

Or reject the request like so:

client.rejectAuthentication(id);

Document signing requests

To get the document to be signed, use:

ParcelFileDescriptor documentFile = client.requestDocumentContent(document);

A user may sign the documents in a transaction like this:

DocumentsTransaction transaction = requestDocumentsTransaction(id);

client.signDocuments(transaction);

Or reject the request like so:

client.rejectDocuments(id);

Push messages

The biid Platform can send a push message through the Firebase Cloud Messaging service when the user’s certificate has been signed or when a transaction is created.

To enable this, integrate Firebase Cloud Messaging in your app and enter the (long) server key in the biid back-office.

Extend the FirebaseInstanceIdService to pass the token to the biid Client:

public class MyFirebaseInstanceIdService extends FirebaseInstanceIdService {

    @Override
    public void onTokenRefresh() {

        ...

        String token = FirebaseInstanceId.getInstance().getToken();
        client.onFcmTokenRefreshed(token);

        ...
    }
}

And extend the FirebaseMessagingService to handle the messages:

public class MyFirebaseMessagingService extends FirebaseMessagingService {

    @Override
    public void onMessageReceived(RemoteMessage message) {

        ...

        BiidNotification notification =
            client.onFcmMessageReceived(message.getFrom(), message.getData());

        if (notification == null) {
            // the push message is not from the biid Platform
        } else {
            // notify the user
        }

        ...
    }
}

SMS messages

The biid Platform can also send an SMS message with a link when the user’s certificate has been signed or when a transaction is created.

To enable this, enter an app identifier in the biid back-office.

Add the following intent-filter to the activity in which you want to handle the transaction notification:

<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="http" android:host="[your app identifier]" />
</intent-filter>

And handle the intent like this:

BiidNotification notification = client.onSmsReceived(intent);

if (notification == null) {
    // the SMS is not from the biid Platform
} else {
    // notify the user
}