Starting iOS SDK

Overview

The SDK is launched using the SensibillSDK.start function. On startup, SDK will ensure a valid authentication can be obtained. It may contact the TokenProvider to obtain a token if no valid token is available. Once authenticated, the start function will acquire the information required for interaction with SDK. This information is cached on device , but is verified and updated from Sensibill’s backend every time the SDK is started.

Notes:

• The start function will not work in offline mode, it requires a network connection to succeed.
• Caller must wait for the start callback to succeed before attempting any further interaction with the Sensibill SDK.

Parameters

User Identifier

The user identifier parameter of the SensibillSDK.start function allows the SDK to ensure that both, integrating app, and SDK are working in context of the same user, and support multiple user identities (for example personal and business accounts) used on the same device. A hosting application can provide user identifier in any convenient format, as long as it satisfies the following conditions:

• The user identifier should be unique for each user identity.
• A user identifier for the same user should not change from session to session.

For example a user identifier could be a user email (e.g. john.smith@example.com), user email with additional info, (e.g. type of account: john.smith@example.com-business), a hashed user email, or a UUID, linked to a particular user account number.

Once SDK has started, you can access current user identity, used by SDK via the SensibillSDK.shared.identityService.userIdentity property.

Token Provider

An instance of custom TokenProvider created in previous Authentication section. On successful start, the SDK will retain the instance of token provider, accessible via the SensibillSDK.shared.identityService.tokenProvider property. The property will be set to nil when SensibillSDK.stop is called.

Configuration

An instance of SensibillSDK.Configuration, which encompasses:

• (Required) A definition of the Sensibill API environment to which SDK should connect. In simplest form the environment can be provided as a constant - .beta (beta.getsensibill.com), .sandbox (receipts-sandbox.sensibill.io), or .production (receipts.getsensibill.com).
• (Optional) A custom branding configuration (Sensibill.Branding). If not provided, the default branding will be used. See Branding page for more information on branding customization.
• (Optional) A custom settings for Capture’s feature flag (Sensibill.Capture.FeatureFlags). If not provided, default seettings will be used. See Feature Switching for more details on Capture features configuration.

Methods

The SensibillSDK.start is provided in 3 forms:

• An async method, called with await: start(userIdentifier:tokenProvider:configuration:) . It returns Result<Void, Error>

• A method with callback: start(userIdentifier:tokenProvider:configuration:completion:) , where callback also provides a Result object - @escaping (Result<Void, Error>) -> Void.

• And a method compatible with Objective-C: start(userIdentifier:tokenProvider:configuration:completion:) . Its callback uses Objective-C compatible types: @escaping (Error?) -> Void

All methods follow the same logic, and are provided for convenience.

Steps

1. Follow the login process for your Integration Server to authenticate the user. This process should also provide a userIdentifier value for start

2. Create an instance of your TokenProvider, and perform any steps neccessary to make sure the provideTokenReplacement function is ready to be called.

3. Create an instance of SensibillSDK.Configuration

   • with predefined or custom Sensibill.SensibillAPIClient.Environment, or a custom Sensibill.SensibillAPIClient.Configuration
   • and optional Sensibill.Branding
   • and optional Sensibill.Capture.FeatureFlags

4. Call the SensibillSDK.start function in a form convenient for your app.

5. Handle success and failure result of start execution.

import Sensibill

// 1. Follow the *login* process for your Integration Server to authenticate the user. 
// ...
let userIdentifier = // ... provided after successful login

// 2. Create an instance of your `TokenProvider`
let tokenProvider = CustomTokenProvider()

// 3. Create an instance of SensibillSDK.Configuration (minimal)
let configuration = SensibillSDK.Configuration(environment: .beta)

// ... or with Branding
let myBranding = Branding()

// ... ... customize branding as needed, e.g.
myBranding.colors = MyColors()

let configurationWithBranding = SensibillSDK.Configuration(
    environment: .beta,
    branding: myBranding
)

// ... Capture feature flags can be passed as well

// 4. Call the SensibillSDK.start
let result = await SensibillSDK.start(
    userIdentifier: userIdentifier,
    tokenProvider: tokenProvider,
    configuration: configuration
)

// 5. Handle success and failure result
switch result {
case .success:
    // Start interacting with SDK
case .failure(let error):
    // Handle error, for example:
    print(error.localizedDescription)
}