Logging in

After the client is initialized, a user can be authenticated by calling the authenticate() function with a username and an access token returned from the security provider.

Swift4

    SDK.getClient.authenticate(withUsername: username, securityProviderAccessToken: token, entity: entity,
         onSuccess: {
            // Handle successful authentication
        }, onNoConnection: {
            // Handle no connection
        }, onInvalidToken: { (error) in
            // Handle invalid token
        }, onClientError:  { (error) in
            // Handle client error
    })

ObjC

    [biidCoreSDK.getClient authenticateWithUsername:userName securityProviderAccessToken:token entity:entity
        onSuccess:^{
            // Handle Success
        }
        onNoConnection:^void() {
            // Handle no connection Error
        }
        onInvalidToken:^void(NSError * _Nonnull error) {
            // Handle invalid token error
        }
        onClientError:^void(NSError * _Nonnull error) {
            // Handle client error
        }
     ];

Documentation

Once a user has been authenticated, the default entity associated with the app is selected. Details of the selected entity can be returned as follows:

Swift4

     do {
         let entity = try SDK.getClient.getSelectedEntity()
     }
     catch (let exception) {
         // Handle exception
     }

ObjC

     NSError *error;
     Entity *entity = [biidCoreSDK.getClient getSelectedEntity:&error];

Documentation

Multiple Entities

If configured to do so, an app can allow a user to be associated with multiple entities (see the AllowsMultipleEntities key in the manifest file).

NB If the app is configured not to allow multiple entities calling the following APIs will return a multipleEntitiesNotSupported client exception.

To check if the SDK/App suppprts multi entity configuration, use the isMultiEntityConfig() API call:

Swift4

     do {
         let isMultiEntity = try SDK.getClient.isMultiEntityConfig()
     }
     catch (let exception) {
         // Handle exception
     }

ObjC

     NSError *error;
     Bool isMultiEntity = [biidCoreSDK.getClient isMultiEntityConfig:&error];

Documentation

NB There is also an API for checking whether the configuration is setup for a single entity.

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

Swift4

    SDK.getClient.requestEntitiesForUser(
        onSuccess: { (entities) in
            // Handle returned entities
        }, onNoConnection: {
            // Handle no connection
        }, onInvalidUserStateError: { (error) in
            // Handle incorrect user state
        }, onInvalidToken: { (error) in
            // Handle invalid token
        }, onClientError:  { (error) in
            // Handle client error
    })

ObjC

     [biidCoreSDK.getClient requestEntitiesForUserOnSuccess:^(NSArray <Entity *>* _Nonnull entities) {
             // Handle returned entities
         }
         onNoConnection:^void() {
             // Handle no connection Error
         }
         onInvalidUserStateError:^void(NSError * _Nonnull error) {
             // Handle incorrect user state
         }
         onInvalidToken:^void(NSError * _Nonnull error) {
             // Handle invalid token error
         }
         onClientError:^void(NSError * _Nonnull error) {
             // Handle client error
         }
     ];

Documentation

If the user wants to be able to access another entity, the entity must first be requested by it’s url name. Before doing so it is recommended to check whether the entity url itself is valid by calling checkEntityExists:

Swift

    SDK.getClient. checkEntityExists(withURLName: urlName,
        onSuccess: { (entity) in
            // Handle Success
        }, onNoConnection: {
            // Handle no connection Error
        }, onClientError: { (error) in
            // Handle client error
    })

ObjC


    [biidCoreSDK.getClient checkEntityExistsWithURLName:urlName
       onSuccess:^(Entity * _Nullable entity) {
            // Handle Success
        }
        onNoConnection:^void() {
            // Handle no connection Error
        }
        onClientError:^void(NSError * _Nonnull error) {
            // Handle client error
        }
    ];

Notes

In an entity with a URL of the-entity.biid.com, the URL name is the-entity.

If a disabled Entity is requested, null will be returned.

Documentation

Once the url is validated, an entity can be requested as follows:

Swift4

     SDK.getClient.requestEntity(withURLName: urlName,
         onSuccess: { (entity) in
             // Handle success
         }, onNoConnection: {
             // Handle no connection Error
         }, onInvalidUserStateError: { (error) in
             // Handle incorrect user state
         }, onInvalidToken: { (error) in
             // Handle invalid token Error
         }, onValidationError: { (error) in
             // Handle field validation Error
         }, onClientError: { (error) in
             // Handle client error
     })

ObjC

     [biidCoreSDK.getClient requestEntityWithURLName:urlName
         onSuccess:^(Entity * _Nonnull entity) {
             // Handle success
         }
         onNoConnection:^void() {
             // Handle no connection Error
         }
         onInvalidUserStateError:^void(NSError * _Nonnull error) {
             // Handle incorrect user state
         }
         onInvalidToken:^void(NSError * _Nonnull error) {
             // Handle invalid token error
         }
         onValidationError:^void(NSError * _Nonnull error) {
             // Handle invalid token error
         }
         onClientError:^void(NSError * _Nonnull error) {
             // Handle client error
         }
     ];

Notes

Requesting a disabled entity will return a client exception.

On a successful response, the entity becomes available to the user.

Documentation

To select or switch between an available entity, use selectEntity:

Swift4

    SDK.getClient.selectEntity(entity: entity,
        onSuccess: {
            // Handle success
        }, onNoConnection: {
            // Handle no connection Error
        }, onInvalidToken: { (error) in
            // Handle invalid token Error
        }, onClientError: { (error) in
            // Handle client error
        }
    )

ObjC

    [biidCoreSDK.getClient selectEntity:entity
        onSuccess:^{
            // Handle success
        }
        onNoConnection:^void() {
            // Handle no connection Error
        }
        onInvalidToken:^void(NSError * _Nonnull error) {
            // Handle invalid token error
        }
        onClientError:^void(NSError * _Nonnull error) {
            // Handle client error
        }
    ];

Documentation

In certain integrations, for example when only one entity is available and the entity details are known to the SDK integrator, it makes sense to create the entity model to pass into selectEntity()rather than retrieving it via a checkEntityExists() call. This can be done by creating an Entity object with it’s ID:

Swift4

    let entity = Entity(withID: "2995046156774445007121104")

    // call selectEntity…

ObjC

    Entity *entity = [[Entity alloc] initWithId:@"2995046156774445007121104"];

    // call selectEntity…

Documentation

In addtion there is also a helper API that creates and selects the Entity in one call:

Swift4

     SDK.getClient.selectEntity(withID: id,
         onSuccess: {
             // Handle success
         }, onNoConnection: {
             // Handle no connection Error
         }, onInvalidToken: { (error) in
             // Handle invalid token Error
         }, onClientError: { (error) in
             // Handle client error
     })

ObjC

     [biidCoreSDK.getClient selectEntityWithID:id
         onSuccess:^{
             // Handle success
         }
         onNoConnection:^void() {
             // Handle no connection Error
         }
         onInvalidToken:^void(NSError * _Nonnull error) 
             // Handle invalid token error
         }
         onClientError:^void(NSError * _Nonnull error) {
             // Handle client error
         }
     ];

NB

• Selects an entity. If the entity was not linked to the device before, the link to the device will be established after successfully calling this method.

• Selects an entity by attempting to authenticate with this entity.

• Returns multipleEntitiesNotSupported client exception if the app is not configured to support multiple entities

• On successful authentication the user will be associated with this entity.

• Selecting an invalid entity will result in a BiidInvalidTokenException with a ‘LOGIN’ resolution.

• If authentication fails, the existing entity remains selected.

Documentation

NB When any other call is made to the client, the currently selected entity will always be inferred.