README.md

Biid Logo

biidCoreSDK - Xamarin.iOS Developers Guide

Xamarin ios Version 3.2.276
SDK ios Version 3.2.247

biidCoreSDK biidCoreSDK biidCoreSDK

Overview

  • Developer : biid
  • Support : info@biid.com
  • Language : C#
  • Deployable in : Xamarin.iOS, Xamarin.Android
  • Minimum iOS Version Supported : 10.0 (using XCode 10 or above)

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

Upgrading

From Version 3.1

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

iOS Change Summary

  • New status of Cancelled has been added to the Transaction model.
  • New Notification types of “authWEB” and “authIDV” and “docMIXED” have been added to the Notification model.
  • The “revoked” user status has been removed and an “unaccredited” status added.
  • A number of the TransactionTypes have been renamed to make them more self explanatory.
  • A new TransactionSubType option has been added to the Transaction model.
  • A new MessageTransaction Model has been added, along with 2 new API RequestMessageTransaction() & DismissMessage().
  • CheckEntityUrl() has been renamed to CheckEntityExists().
  • Roles returned 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 and now require use of Location property for get / set (see TransactionInfo example below).

From Version 3.0

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

iOS Upgrade Changes

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

Brief notes concerning these changes are listed below -

iOS Upgrade Changes

  • UserStatus Enums have all changed to a new format.
  • Various method names have changed along with their 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.

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.SetObject("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

Make the Call to Register 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.

The RegisterUser method now returns the registered User object, so a call to RequestUser is no longer mandatory in order to check these User details.

TransactionInfo

A TransactionInfo object is supplied and returned with various AuthenticationTransaction calls.

You can instantiate and query a TransactionInfo object using the following code -

// Create Info object for use in Authentication Transaction
TransactionInfo transactionInfo = new TransactionInfo();

// Set constant based 'built-in' properties
transactionInfo.SetObject(new NSString("title"), TransactionInfo.KTitle);
transactionInfo.SetObject(new NSString("desc"), TransactionInfo.KDescription);

// Set Additional Custom properties of your own
transactionInfo.SetObject(new NSString("prop1value"), "prop1");
transactionInfo.SetObject(new NSString("prop2value"), "prop2");

// Set Location using Location property
var locationNSNumber = new NSNumber[] { lat, lng };
transactionInfo.Location = locationNSNumber;

// ... do something with your transaction info within an AuthenticationTransaction

// Get 'built-in' properties
var title = transactionInfo.Title;
var transactionDescription = transactionInfo.TransactionDescription;

// Get Location (see LOCATION NOTE below)
NSNumber[] location = transactionInfo.Location;

// Get your Additional Properties
var prop1value = (NSString) transactionInfo.ObjectForKeyedSubscript("prop1");            
var prop2value = (NSString) transactionInfo.ObjectForKeyedSubscript("prop2");            

LOACTION NOTE: Although the iOS SDK exposes a KLocation constant which looks like it can be used as a key in SetObject and ObjectForKeyedSubscript (as per the other KTitle and KDescription constants), this is not available in the Xamarin Bindiing. Please use the above example to set / get the Location.