README.md

Biid Logo

biidCoreSDK - Xamarin Developers Guide

Xamarin android Version 3.0.165
SDK android Version 3.0.253

biidCoreSDK biidCoreSDK biidCoreSDK biidCoreSDK

Overview

  • Developer : biid
  • Support : info@biid.com
  • Language : C#
  • Deployable in : Xamarin.iOS, Xamarin.Android
  • Minimum iOS Version Supported : 9.0 (using XCode 9.3 or above)
  • 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 guides to get up to speed with Xamarin.biidCoreSDK Installation and Initialisation.

Xamarin.iOS biidCoreSDK QuickStart
Xamarin.Android biidCoreSDK QuickStart

Detailed Documentation

As the Xamarin biidCoreSDK Bindings are mostly directly bound and mapped to the underlying biidCoreSDK Native iOS and 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.

iOS biidCoreSDK Documentation
Android biidCoreSDK Documentation

Upgrading 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 is by reading the following PDF Document

Brief notes concerning these changes are listed below -

iOS Upgrade Changes

  • UserStatus Enums have all changed to new format.
  • Various method names have changed along with callbacks where appropriate.
  • New methods have been added to the API.
  • ClientError enums have been updated to latest errors.
  • For consistency, certain calls which used to be properties on the Client object now use the (out NSError) pattern to report an error when trying to access. For example, _client.SelectedEntity becomes _client.GetSelectedEntity(out NSError error)
  • In general whereby a method previously returned a List then the latest binding is more tightly wrapped to the underlying code and will return an array[] of T. If you would like to return to using Lists then please use .ToList() accordingly.

Development Notes

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

Using Async with iOS

The iOS biidCoreSDK also has a requirement that its calls must be made on the Main UI Thread (otherwise it will throw an error at run-time).

Currently the majority of iOS SDK calls are returned using common callbacks such as -

onNoConnection
onInvalidToken
onValidationError
onClientError

Which you can create common method handlers for in your code to react the SDK responses.

If you do not wish to use a callback based programming style, then you can change the iOS calls into an async variant async and await with C#.

You can then combines this with ensuring the SDK call runs on the Main Thread as follows:

public Task AuthenticateWithUsername(string username, string accessToken, EntityName entityName = null)
{
    TaskCompletionSource<bool> tcs = new TaskCompletionSource<bool>();

    UIApplication.SharedApplication.InvokeOnMainThread(() =>
    {
        _client.AuthenticateWithUsername(
             username,
             accessToken,
             entityName,
             () =>
             {
                 tcs.SetResult(true);
             },
             onNoConnection: () =>
             {
                 // ... more complex error handling
                 tcs.SetResult(false);
             },
             onInvalidToken: obj =>
             {
                  // ... could use tcs.SetException
                  tcs.SetResult(false);                    
             },
             onClientError: obj =>
             {                    
                 tcs.SetResult(false);                                        
             }
         );
     });

    return tcs.Task;
}     

As noted in the comments, you will have to handle the SDK errors in a more thorough way than shown above; but this would allow you to then call this API method like so:

var authSuccess = await RequestUserDevicesAsync(username, token, entityName).

You may prefer to use the native style callback approach.

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

Clarify Exactly how to use EntityDetails, IFieldDefinition and what IOS / Android Types to supply to get thigns working easily,

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, as a User object is read-only, you cannot create one directly, you must retrieve the currently authenticated user with a call to RequestUser.
  • We will loop through all the fields within the EntityDetails FieldDefinitions and Set the required properties on the User object as follows:

iOS

_user.SetObject("FieldName", Native Type / Value from Table Below);

Android

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

iOS Input Types and Values

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

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.