README.md

Biid Logo

biidCoreSDK - Xamarin.Android Developers Guide

Xamarin android Version 3.2.232
SDK android Version 3.2.377

biidCoreSDK biidCoreSDK biidCoreSDK

Overview

  • Developer : biid
  • Support : info@biid.com
  • Language : C#
  • Deployable in : Xamarin.Android
  • Minimum Android Version Supported : 5.0 (API 21)

Introduction

The biidCoreSDK is the easiest way to use the biid Platform within an iOS app. The biid Core SDK library contains a biid Client which handles communication with the biid Platform, manages the biid digital certificates and provides functionality for securely signing and confirming document & authentication transactions respectively.

Table of Contents

Quick Start

Please read the following Quick Start guide to get up to speed with Xamarin.biidCoreSDK Installation and Initialisation.

Xamarin.Android biidCoreSDK QuickStart

Detailed Documentation

As the Xamarin biidCoreSDK Bindings are mostly directly bound and mapped to the underlying biidCoreSDK Native Android libraries, then usage of the libraries is currently best covered by referencing the native documentation for the biid platform at https://documentation.biid.com.

Android biidCoreSDK Documentation

Upgrading

From Version 3.1

The most detailed way to see the changes is by reading the related sections of the following PDF Document.

Android Change Summary

  • New status of Cancelled has been added to the Transaction model.
  • New Notification types of “AUTH_WEB” and “AUTH_IDV” and “DOC_MIXED” have been added to the Notification model.
  • The “revoked” user status has been removed and an “unaccredited” status added.
  • A new MessageTransaction Model has been added, along with 2 new API RequestMessageTransaction() & DismissMessage().
  • A number of the TransactionTypes have been renamed to make them more self explanatory.
  • CheckEntityUrl() has been renamed to CheckEntityExists().
  • Roles return from GetRoles() have changed.
  • RegisterUser() & UpdateUser() now return the updated User model.
  • TransactionInfo Model - the seperate Lat and Lng properties have been replaced by Location.

From Version 3.0

The most detailed way to see the changes is by reading the following PDF Document.

Android Change Summary

  • EntityName Model has been removed, please use Entity Model instead.
  • DownloadPublicDocument() API Added.
  • RequestExtendedPermissions() API Added.
  • GetRoles() API Added.
  • IsSingleEntityConfig() and IsMultiEntityConfig() APIs added.

From Version 0.10

The API of the underlying SDK from version 0.10 to 3.0 has changed considerably between the previously released bindings.

This has affected existing method signatures along with adding various new endpoints.

The most detailed way to see the changes from 0.10 to 3.0 is by reading the following PDF Document.

Development Notes

The following documentation will give ideas on how you could use the SDKs in your Xamarin code.

Using Async with Android

The Android SDK should be called on a Background Thread.

When using the SDK within an Android Application the developer has various choices on how to handle the threading within their application.

We have shown below an example of how the Authenticate SDK call can be made into an async method which at the same time ensures the call is made on a Background Thread:

public async Task Authenticate(string username, string accessToken, Com.Biid.Sdk.Core.Android.Entity.EntityName entityName)
{
    if (username == null)
    {
        throw new ArgumentNullException(nameof(username));
    }

    if (accessToken == null)
    {
        throw new ArgumentNullException(nameof(accessToken));
    }

    try
    {
        // Ensure we run android SDK code on a background thread
        await Task.Run(() =>
        {
            _client.Authenticate(username, accessToken, entityName);
        });
    }
    catch (Exception ex)
    {
        // Handle errors
    }
}

Registering Users

One of the more involved tasks with the SDK is registering a User with the SDK. We will detail the process involving various SDK methods and types below.

SetUp Entity Identity Profile

Firstly, we will assume you have setup the Identity Profile of your chosen Entity (lets say EntityA) in your backoffice with the User Fields you require.

We currently have 8 field Input Types to choose from when defining your Identity Profile.

  • Plain text
  • Email Address
  • Date
  • Phone Number
  • Numeric
  • Boolean
  • Selection
  • Country

Gather Entity Field Definitions

We then need to gather information of the fields from the EntityA which you intend to register the user with. This is so we can then build a user object to use in our register call.

Steps:

  • Authenticate with the SDK for EntityA.
  • Make a call to RequestEntityDetails() which will return you an EntityDetails object for EntityA.

You can then query the FieldDefinitions property on the EntityDetails to see what fields are required on behalf of the user being registered.

A FieldDefinition contains this information -

Property Description
Name Name of field for internal reference
Required Is the field required in order to register the user?
Label Field Text to show to user on User Interface
Hint Hint on how to complete field to show user on User Interface
Secure A Secure field that can be set, but not retrieved on the user object
Readonly Post-Certification this Property denotes that this field is no longer editable via further UpdateUser call as it is now part of users certificate
InputType Input type as detailed above

You now have all the information you need to generate a user object to use in the call to RegisterUser(User user).

Create User Object from Field Defintions

  • Firstly, create a user object:
var _user = new User();
  • We will loop through all the fields within the EntityDetails FieldDefinitions and Set the required properties on the User object as follows:
_user.Put("FieldName",  Native Type / Value from Table Below);

As the SDK wraps the native binding, you need to know what native types to send to the RegisterUser call for each Input Type.

As the entity definition is very flexible the system currently uses mainly string formats to pass the required data for the user.

Android Input Types and Values

Input Type Native Type & Value Format
Plain text Java.Lang.String("text")
Email Address Java.Lang.String(("email@email.com")
Date Java.Lang.String(new DateTime(1974, 6, 29).ToString("yy-MM-dd"))
Phone Number Java.Lang.String("+447767456783")
Numeric Java.Lang.String(10.ToString())
Boolean Java.Lang.String("true") or Java.Lang.String("false")
Selection You must supply one of the OptionValue objects returned in the FieldDefinition Options List
Country Java.Lang.String("GB") - country code

Make the Call to Request User

Finally, call the platform specific RegisterUser method supplying the User object you have just populated.

Any programming errors when setting up the User object will return as a Validation Error.