Sample Sensibill Integration

Last updated for v1.15.1

CompileSdkVersion => 27

BuildToolsVersion => 27.0.3

TargetSdkVersion => 26

MinSdkVersion => 18

supportLibraryVersion => 27.1.1

GooglePlayServices => 11.8.0

This project is an application demonstrating how to integrate with the Sensibill Android SDK. Sample initialization of SDK is done in the SensibillManager class. Launching of Sensibill Functionality is done in the SensibillActionsActivity.

Environment Setup

Install Gradle

• Go to Gradle Install to see steps to install gradle

  Install Git / Github

• Install Git, following official documentation: Git Installation Page
• For Github interface, install the Github Desktop Github Installation Page

  Bitbucket SSH Setup

• Make sure SSH key is correctly setup with BitBucket. If not, view Bitbucket Website

Installing Demo Repo via GitHub Desktop

• Ask for an invite to the Sensibill Android SIA project on Github
• Visit Repository site: https://github.com/sensibill/sensibill-android-sia
• Click clone or download and select Open in Desktop
• If Github Desktop is installed, Github App should launch and prompt to begin cloning process. If not, attempt to clone via command line

Installing Demo Repo via Git command line

• If it’s your first time installing the SDK, checkout the code from the repository by entering the following in your terminal:

  $ git@github.com:sensibill/sensibill-android-sia.git
  

• If the repo has already been installed, pull and update repo to make sure latest changes are available locally

  $ git pull
  

---

Integration Steps

Import SDK into the project ###- Add sensibill SDK maven repository to top level build.gradle

allprojects{
    repositories {
        maven {
            // Sensibill SDK repository
            url 'https://maven.getsensibill.com'
                credentials {
                    username 'to be provided by sensibill'
                    password 'to be provided by sensibill'
                }
        }
    }
}

• Add the Sensibill SDK as a dependency in the build.gradle file of the module that is supposed to host sensibill sdk

dependencies {
    compile "com.getsensibill:sensibill-auth:X.X.X"
    compile "com.getsensibill:sensibill-sdk-all:X.X.X"
    // Optional - For Transaction matching
    compile "com.getsensibill:sensibill-transaction-matcher:X.X.X"
    //Please ask for latest value of X.X.X from Sensibill
}

Pre SDK Initialization

• There are two main ways to use the Sensibill SDK: Logging in using a username/password combination or Logging in using an access token
• In the case of using username/password login, a SensibillAuth object must be used

• SensibillAuth acts as an interface to allow for authentication flows using username/password login

• Before creating the SensibillAuth object, first create OauthSetting object which will hold client information, ie client secret, client key.
  • new OAuthSettings(client_key, client_secret, mCredentialsType, mRedirectUri, redirect);

  • Parameters:

    Name	Description
    client_key	This is the Client Key, provided by Sensibill. It is a very long, random string encoded in base64
    client_secret	client secret, supplied by Sensibill
    credential_type	This represents the type of credentials that are being used to authenticate the user
    redirect_uri	URL provided by Sensibill for client. Used for OAuth 2.0
    redirect	Can be either “true” or “false”. Tells whether or not the authorizationGrant endpoint will issue a redirect if it successfully authenticates the user.

• Before initializing the SDK, first create a SensibillAuth object. This object will be used by the SDK to perform OAuth flow.

• Create SensibillAuth object by using SensibillAuthBuilder, which takes target Sensibill DefaultEnvironment (ie, DefaultEnvironment.BETA_SANDBOX) and an OAuthSetting object (which holds the client_key, client_secret, redirect url, credential type and redirect boolean)

  • SensibillAuth auth = new SensibillAuthBuilder(context, sensibill_env, oauthSettings).build();

  • Parameters:

    Name	Description
    context	Application Context
    sensibill_env	An enum conforming to the DefaultEnvironment type. This specifies what external Sensibill environment you wish your application to access. Example DefaultEnvironment.BETA_SANDBOX
    oauthSettings	Object of OAuthSettings. House client information for Auth flow

IMPORTANT: Make sure that client credentials provided are for the chosen DefaultEnvironment

SDK Initialization

• Initialization can begin using the InitializationBuilder to create a builder object which will be used to initialize the SDK, by providing the application context and Sensibill DefaultEnvironment

  • InitializationBuilder builder = new InitializationBuilder(context, sensibill_env)

  • Parameters:

    Name	Description
    context	Application Context
    sensibill_env	An enum conforming to the DefaultEnvironment type. This specifies what external Sensibill environment you wish your application to access. Example DefaultEnvironment.BETA_SANDBOX

• InitializationBuilder can be extended to provide SDK customization and monitoring. Extensions are optional

Initialization Extension: SDK Lifecycle Listener

• Lifecycle events of activities in the SDK can be monitored by host application by providing an AbstractActivityLifecycleListener during initialization.

  InitializationBuilder builder = new InitializationBuilder(getApplicationContext(), DefaultEnvironment.BETA_SANDBOX)
    .activityLifecycle(new AbstractActivityLifecycleListener() {
        // implement methods here
    }
  

Initialization Extension: Token Provider

• Custom token provider can be applied to the SDK by providing an Auth Token Provider. When session time runs out or token is invalid, SDK will use this token provider to retrieve a new token.

  InitializationBuilder builder = new InitializationBuilder(getApplicationContext(), DefaultEnvironment.BETA_SANDBOX)
    .authTokenProvider(new TokenProvider() {
        // implement methods here
    }
  

Initialization Extension: Event Listener

• SDK events can be monitored by providing an Event Listener during initialization. A class which implements OnTrackEventListener can be passed into InitializationBuilder. SDK events will trigger trackEvent function in said class.

InitializationBuilder builder = new InitializationBuilder(getApplicationContext(), DefaultEnvironment.BETA_SANDBOX)
    .builder.onTrackEventListener(new OnTrackEventListener {
        @Override
        public void trackEvent(AnalyticsEvent eventName, Map<String, Object> attributes, Map<String, Object> superAttributes) {
            // Track Event
        }

        @Override
        public void onDestroy() {
            // Handle Tracker Destruction
        }
    });

Initialization Extension: SDK Customization

• Additional SDK functional customizations can be made via SBSDKConfiguration. Set desired functionality, and pass to initialization builder.

  InitializationBuilder builder = new InitializationBuilder(getApplicationContext(), DefaultEnvironment.BETA_SANDBOX)
    .configuration(new SBSDKConfiguration());
  

Build and Initialize

• Once InitializationBuilder object is created and optional extensions are added, SDK can be initialized by calling the following:

SensibillSDK.getInstance().initialize(builder.build());

Adding Transaction Observer

• Transactions created in SDK, ie. Receipt Creation, can be monitored by providing a TransactionDataObserver after initialization.

  SensibillSDK.addTransactionDataObserver(new : TransactionDataObserver {
    override void notify(Transaction transaction) {
        // Handle Transaction Information
    }
  })
  

Example: Initialization example can be found in [SensibillManager.java]

Signing in User

• Once SDK is initialized, users can now sign in and use the SDK. There are two flows that can be used to sign users into the SDK

Access Token Sign in

• In the case where a token is coming from an external source, ie. an integration server, said token can be used to sign into the SDK
• Before attempting to sign in with the token, verify that the token is valid using SensibillSDK.getInstance().verifyToken()

  SensibillSDK.getInstance().verifyToken(username, access_token, new SessionVerificationListener() {
    @Override
    public void onValidSession() {
        // Valid Token
    }
  
    @Override
    public void onInvalidSession(@NotNull SBError sbError) {
        // Invalid Token
    }
  });
  

• If token is valid, attempt to sign in using SensibillSDK.getInstance().login()

SensibillSDK.getInstance().login(getApplicationContext(), access_token, username, new SDKStartup() {
    @Override
    public void onSDKStarted() {
        // SDK Logged in
    }

    @Override
    public void onSDKFailed(LoginError sdkLoginError, String message) {
        // SDK failed to login
    }
});

• A full implementation would be as follows

  SensibillSDK.getInstance().verifyToken(username, access_token, new SessionVerificationListener() {
    @Override
    public void onValidSession() {
        SensibillSDK.getInstance().login(getApplicationContext(), access_token, username, new SDKStartup() {
            @Override
            public void onSDKStarted() {
                // Proceed to Receipts Activity
            }
  
            @Override
            public void onSDKFailed(LoginError sdkLoginError, String message) {
                // Log in fail
            }
        });
    }
  
    @Override
    public void onInvalidSession(@NotNull SBError sbError) {
        // Bad Token
    }
  });
  

Username - Password

• Use SensibillAuth object created (see above) to sign in.

auth.signIn(username, password, new SensibillAuth.SessionListener() {
@Override
      public void onFailure(@NotNull SensibillAuth.AuthError error) {
        // Authorization Error
      }

      @Override
      public void onSuccess(@NotNull final OauthUser user) {
        // Sign in Successful
      }
}

• If sign in was successful, use retrieved OauthUser’s access token to start SDK, similar to access token login above. Full flow would look as follows:

  auth.signIn(username, password, new SensibillAuth.SessionListener() {
  @Override
      public void onFailure(@NotNull SensibillAuth.AuthError error) {
        // Authorization Error
      }
  
      @Override
      public void onSuccess(@NotNull final OauthUser user) {
        SensibillSDK.getInstance().login(getApplicationContext(), user.getAccessToken(), username, new SDKStartup() {
            @Override
            public void onSDKStarted() {
                // Proceed to Receipts Activity
            }
  
            @Override
            public void onSDKFailed(LoginError sdkLoginError, String message) {
                // SDK failed to login
            }
        });
      }
  }
  

Example: Login example can be found in [SensibillManager.java]

---

Using Sensibill SDK Activities

Launching Capture Activity

• To launch the capture activity, call ReceiptCaptureActivity.newIntent() like the following: startActivity(ReceiptCaptureActivity.newIntent(FeaturesActivity.this, transactionId, true, null));
  • ReceiptCaptureActivity.newIntent() can take 4 parameters.

  • Parameters:

    Name	Description
    context	Activity Context
    transactionId	External transactionId which will be used to match the captured receipt to an external transaction
    showProcessing	Boolean value to determine whether to show the Sensibill Processing Screen after capture is finished
    externalMetaData	External metadata to be added to the captured receipt

Launching Receipt Detail Activity

• To launch the receipt detail activity, call ReceiptDetailActivity.newIntent() as the following: startActivity(ReceiptDetailActivity.newIntent(FeaturesActivity.this, receiptId));
  • ReceiptDetailActivity.newIntent() takes 2 parameters.

  • Parameters:

    Name	Description
    context	Activity Context
    receipt_id	Sensibill receipt id to be displayed in the Receipt detail view

Using SDK Fragment

There are couple of fragments that you can embed in your app’s activities for seamless integration between SDK and your app.

• SBReceiptListFragment contains the list of receipts

• SBReceiptFolderFragment contains the list of folders the user created.

• SBNotificationFragment contains the notification items.

• SBMainTabsFragment is a single fragment hosting all of the above.

All these fragments can also be embedded directly in the layout file (except SBMainTabsFragment).

• Example ReceiptListHostActivity shows example of how to host a Sensibill Fragment ```

> **IMPORTANT** Make sure that Theme.Sensibill or a style extending Theme.Sensibill is applied to any activity hosting a Sensibill Fragment in the Android Manifest

***

### Customize Sensibill Colours
To style SDK with brand colors, extend the Sensibill external theme **Theme.Sensibill**:

<style name="Theme.Sensibill" parent="Base.Theme.Sensibill">
    ...
</style> ```

The SDK has 16 colours which can be overridden in the Theme.Sensibill style. All elements in the SDK map to one of the 16 colours. For further details on the sensibill branding strategy, please refer to the provided style guide. The following is an example of a full re-branding of the Sensibill SDK:

    <style name="Theme.Sensibill" parent="Base.Theme.Sensibill">
        <item name="sb__brandBackground">@color/myBank_brandBackground</item>
        <item name="sb__brandForeground">@color/white</item>
        <item name="sb__brandForegroundDisabled">@color/myBank_brandBackground</item>
        <item name="sb__actionBackground">@color/myBank_actionBackground</item>
        <item name="sb__actionForeground">@color/white</item>
        <item name="sb__accentBackground">@color/myBank_accentBackground</item>
        <item name="sb__accentForeground">@color/black</item>
        <item name="sb__alternateBackground">@color/myBank_alternateBackground</item>
        <item name="sb__alternateForeground">@color/white</item>
        <item name="sb__errorBackground">@color/myBank_errorBackground</item>
        <item name="sb__errorForeground">@color/white</item>
        <item name="sb__disabledBackground">@color/myBank_disabledBackground</item>
        <item name="sb__disabledForeground">@color/white</item>
        <item name="sb__primaryBackground">@color/myBank_primaryBackground</item>
        <item name="sb__offPrimaryBackground">@color/white</item>
        <item name="sb__primaryForeground">@color/black</item>
        <item name="sb__primaryForegroundTwo">@color/myBank_primaryForegroundTwo</item>
        <item name="sb__primaryForegroundThree">@color/myBank_primaryForegroundThree</item>
        <item name="sb__primaryForegroundFour">@color/myBank_primaryForegroundFour</item>
    </style>

To brand the SDK for android versions less than 23, override the following colors to get the same effect:

    <color name="sb__brand_background">@color/myBank_brandBackground</color>
    <color name="sb__action_background">@color/myBank_actionBackground</color>
    <color name="sb__accent_background">@color/myBank_accentBackground</color>
    <color name="sb__accent_foreground">@color/black</color>
    <color name="sb__alternate_foreground">@color/myBank_alternateBackground</color>
    <color name="sb__error_background">@color/myBank_errorBackground</color>
    <color name="sb__disabled_background">@color/myBank_disabledBackground</color>
    <color name="sb__primary_background">@color/myBank_primaryBackground</color>
    <color name="sb__primary_off_background">@color/white</color>
    <color name="sb__primary_foreground">@color/black</color>
    <color name="sb__primary_foreground_two">@color/myBank_primaryForegroundTwo</color>
    <color name="sb__primary_foreground_three">@color/myBank_primaryForegroundThree</color>
    <color name="sb__primary_foreground_four">@color/myBank_primaryForegroundFour</color>
    ...

Customize Sensibill Font

To customize font of the SDK, create a resource folder called assets with subfolder fonts.

Add a bold, italic and regular version of desired font to the fonts folder. Create three string resources of the path to each font, starting from the assets folder, for example:

    <string name="brand_font_regular">fonts/RNHouseSans-Regular.ttf</string>
    <string name="brand_font_bold">fonts/RNHouseSans-Bold.ttf</string>
    <string name="brand_font_italic">fonts/RNHouseSans-Italic.ttf</string>

Override the sb__font_regular, sb__font_italic, sb__font_bold properties of Theme.Sensibill with your string resources pointing to your desired fonts. For example:

    <style name="Theme.Sensibill" parent="Base.Theme.Sensibill">
        ...
        <item name="sb__font_regular">@string/brand_font_regular</item>
        <item name="sb__font_italic">@string/brand_font_italic</item>
        <item name="sb__font_bold">@string/brand_font_bold</item>
        ...
    </style>

---