Get Started

Adding Sensibill SDK to a Project

The Sensibill SDK for iOS is distributed in two formats: a binary package format (XCFramework), and a universal archive (legacy format). Both formats can be installed using CocoaPods dependency manager (a preferred method), or by adding the dependency manually to your project.

This section explains how to install Sensibill SDK for iOS in XCFramework format using CocoaPods dependency manager. For other options, please see Installation Options page.

Steps

1. If your project isn’t using CocoaPods already, follow the Installation and Getting Started guides on the official CocoaPods website . Once your project is integrated with the CocoaPods, you should have a Podfile in the root directory of your project.

2. Add the Sensibill SDK for iOS as a dependency to your project’s Podfile in the following format:

   pod 'Sensibill', :git => 'git@github.com:getsensibill/sdk-ios.git', :tag => 'vX.Y.Z'

   where vX.Y.Z represents to version of the SDK you want to use.

   Note: once Sensibill SDK was added to Podfile, don’t forget to run pod install from the root directory of your application’s project in your terminal. This will add Sensibill SDK for iOS to your project’s Pods.

3. Validate the integration by importing the Sensibill module into one of your Swift classes:

   import Sensibill

   and try to build your project. If the project builds successfully, the Sensibill SDK for iOS was integrated correctly. Otherwise follow the Troubleshooting steps on Installation Options page.

Adding the Required Entitlements

• When a user navigates to the Capture Document screen of the Sensibill SDK, SDK will use device’s camera to capture documents. In order to allow camera usage, your application must prompt the user for consent to use their device’s camera, and thus requires a Privacy - Camera Usage Description entitlement.

• Sensibill SDK also allows the users to select existing document images from the device’s photo gallery, which requires a Privacy - Photo Library Usage Description entitlement. Alternatively you can disable gallery access by setting the Capture.FeatureFlags.enableImageGallery to false.

• If you would like to attach user’s device Location data to captured document, the Privacy - Location When In Use Usage Description entitlement is required. By default the location data is not collected, and you need to set Capture.FeatureFlags.attachLocationData to true to enable attaching the location data. Note that if user denies the access to the location, the location data will not be attached to a document, even if it was enabled for the app.

Steps

1. Open Info.plist of your application.
2. Locate or add each of the following entitlements, and provide a description of why the entitlement is required.

Required Entitlements

• For the camera usage: NSCameraUsageDescription (displayed as Privacy - Camera Usage Description)
• For the photo gallery access: NSPhotoLibraryUsageDescription (displayed as Privacy - Photo Library Usage Description).
• For attaching user’s location data: NSLocationWhenInUseUsageDescription (displayed as Privacy - Location When In Use Usage Description).

Integrator must implement a token provider by adhering to TokenProvider protocol. The protocol consists of a single function - provideTokenReplacement which will be called by Sensibill SDK any time it requires a new or updated token.

Parameters:

• A userIdentifier - this is the user identifier for which SDK would like to get a token refresh. It’s recommended to ensure that the provided user identifier is for currently authenticated user.

• A completion callback, which will either return a Credentials object with valid access token, or an error.

Please ensure that provideTokenReplacement calls completion in all cases, either with Credentials or Error.

Steps

1. (Recommended) Ensure the requested token is for currently authenticated user. The “current user identifier” can be stored wherever it makes sense for your app (for example in the class responsible for app authentication).

2. (Required) Obtain a new access token from your integration server.

3. (Required) Process the response from your authentication server. Although the exact operations you need to perform depend on your integration server implementation, the typical set of actions includes:

   • Check for errors. If error is returned, pass this error in callback to SDK
   • Parse the response to ensure the access token was obtained
   • Construct a Credentials object and return it in a callback to SDK

import Sensibill

class CustomTokenProvider: TokenProvider {

    /// TokenProvider implementation
    func provideTokenReplacement(userIdentifier: String, completion: @escaping (Credentials?, Error?) -> Void) {
        
        // Step 1: (Recommended) Ensure the requested token is for currently authenticated user
        guard userIdentifier == <current user identifier> else {
            completion(nil, Errors.userIdentifierMismatch)
            return
        }

        // Step 2: Obtain a token from your integration server
        var request = URLRequest(...)
        let task = URLSession.shared.dataTask(with: request) { (data, response, error) in

            // Step 3: Process the response from your authentication server

            // 3.1 Check for errors. If error is returned, pass this error in callback to SDK:
            if error != nil {
                completion(nil, error)
                return
            }

            // 3.2 Parse the response to ensure the access token was obtained
            guard let accessToken = // ... else {
                completion(nil, Errors.accessTokenWasNotProvided)
                return
            }

            // 3.3 Construct a Credentials object and return it in a callback to SDK:
            let credentials = Credentials(accessToken: accessToken)
            completion(credentials, nil)
        }
        task.resume()
    }
}

extension CustomTokenProvider {
    
    enum Errors: Error {
        case userIdentifierMismatch
        case accessTokenWasNotProvided
    }
}

An instance of the token provider must be passed to the SDK on SensibillSDK.start. See Launching the SDK section below for further information.

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 environment to which Sensibill API Client in the 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). For more configuration options, see Accessing Sensibill API section.
• (Optional) A custom branding configuration (Sensibill.Branding). If not provided, the default branding will be used. See Customize 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 2 forms:

• As an async method, which can be called with await, and does not require a callback parameter
• A method with the traditional completion callback.

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

Result

Both method return the result in format Result<Void, Error>. That is: nothing is returned in case, of success, and Error will be provided in case of the failure.

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. (Optional) Create instances of custom API configuration, branding, and Capture feature flags, if desired. Those options are not covered in the below example, but are discussed in dedicated sections, mentioned in the Configuration parameter definition above.

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

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

6. 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. (Optional) Create instances of custom API configuration, branding, and Capture feature flags, if desired
// (Not covered in this eexample)

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

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

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

The stop function will always clean the local state of the SDK, so it’s always safe to run start after stop has completed. Additionally, there are a few customizations an integrator can make in order to better accommodate the stop function for their needs:

• By default the stop function will first attempt to call Sensibill’s backend to invalidate the user token and clear the user session. The result of the remote call will be returned in Result<Void, Error> of the stop function.

  • This behavior can be disabled by using stop(invalidateToken: false).
  • Even in case the remote token invalidation fails, the local state will be cleared, so the returned Error should not be considered as failure to stop, rather a failure to invalidate the token.

• The stop function is provided in 2 forms:

  • As an async method, which can be called with await, and does not require a callback parameter
  • A method with the traditional completion callback.

Notes:

• The caller must wait for the stop callback to return before attempting to start the SDK again.
• For the stop function having a network connection is optimal, but the SDK will stop and reset its state locally regardless.
• Once the stop function is complete (and regardless of whether it retuns the Error), the SDK can be started again.
• If stop was called while the application is starting, stop may need to wait to be able to interrupt the start.
• The stop function cannot run if another stop function is already in progress.
• Calling stop on already stopped SDK is supported (clears local state only). This can be done in cases when it’s desired to ensure that the SDK is in clear stoppped state.

Steps

1. Call the stop function
2. Optionally, handle success and failure result of stop execution.

Example

import Sensibill

let _ = await SensibillSDK.stop()