SDKs and Reference App

Open Fabric provides access to several SDKs and Reference Apps for our Account tokenization products, specifically for Own App tokens and Digital Wallet Tokens. Please work with our commercial teams and align on the delivery schedules.

When you have access to one of our SDKs, there is a common setup that you may need to be mindful of before you start working with our SDK. In this section we will cover how you should set up your project (to use our SDK) including configuration of unique credentials that we would provide to you.

Android Project Setup

Depending on the product you wish to integrate with we provide a different SDK

Product	SDK	Maven Link
Own App tokens	NFC SDK	https://maven.pkg.github.com/open-fabric-pba-public/openfabric-nfc-sdk
Digital Wallet Tokens	Push Provisioning SDK	https://maven.pkg.github.com/open-fabric-pba-public/openfabric-push-provisioning-sdk

Our SDKs are published as a Maven package and can be added to the mobile application via the standard dependency management system of the Android platform - Gradle.

To be able to access the SDK library, the project’s Gradle settings need to be updated with contents below:

NFC SDK

…
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://maven.pkg.github.com/open-fabric-pba-public/openfabric-nfc-sdk")
            credentials {
                username = "<value provided by Open Fabric>"
                password = "<value provided by Open Fabric>"
            }
        }
    }
}
…

Push Provisioning SDK

…
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://maven.pkg.github.com/open-fabric-pba-public/openfabric-push-provisioning-sdk")
            credentials {
                username = "<value provided by Open Fabric>"
                password = "<value provided by Open Fabric>"
            }
        }
    }
}
…

Supported Android version and required device permissions

The SDKs Android versions support is as follows:

Minimum SDK Version: Android 6.0 Marshmallow (API level 23).

Target SDK Version: up to Android 15 (API level 35).

Compile SDK version: Android SDK 35.

Additional Setup for the NFC SDK

The following additional information only applies to the NFC SDK on Android

Required App Permissions

The NFC SDK specifically will also require the app to have the following permissions to function properly:

Permission	Description
android.permission.INTERNET	required to synchronize data with the back-end platform
android.permission.USE_FINGERPRINT	(deprecated) required to carry out device biometric authentications on android 27- devices
android.permission.USE_BIOMETRIC	required to carry out device biometric authentications on android 28+ devices
android.permission.NFC	required to perform I/O operations over NFC.

These permission requirements have been included within the SDK itself and will be propagated by the Android build process. You do not need to declare those permissions in your App’s AndroidManifest.xml file.

Build script update

The NFC SDK requires some information on the final application during the build process for its anti-tampering mechanism. It is done via the finalization step and requires the following setup on the application's project.

a. Add finalizer plugin files to the application's project

settings.gradle.kts
build.gradle.kts
...
plugins/
  ai.digital.protect-android.jar
  finalizer-linux
  finalizer-macos
  finalizer-windows.exe
app/
  ...
  build.gradle.kts

b. Add finalizer plugin as a project dependency in project's build.gradle.kts

build.gradle.kts

buildscript {
    repositories {
        google()
        mavenCentral()

        flatDir {
            dirs("plugins/")
        }
    }

    dependencies {
        //...
         classpath("ai.digital.protect-android:ai.digital.protect-android:1.0.0")
    }
}

c. Configure finalizer plugin for all build variants in app/build.gradle.kts

app/build.gradle.kts

plugins {
    ...
    id("ai.digital.finalize-android") // apply it last 
}

android {
    ...
}
// Finalization plugin configuration
finalizeAndroid {
    // Configure protection for different build variants
    buildVariants {
        create("debug") {
            // Debug build does not require finalization
            disabled = true
            // Sample configuration when built on a Linux machine. 
            // Update the finalizer to the respective OS. 
            finalizeAndroid = "${rootProject.projectDir.absolutePath}/plugins/finalizer-linux"
            log = "app-finalization-log-debug.txt" 
        }
        create("release") {
            disabled = false
            finalizeAndroid = "${rootProject.projectDir.absolutePath}/plugins/finalizer-linux"
            log = "app-finalization-log-release.txt"
        }
    }
}

Payment network credentials setup

The SDK needs to be configured with credentials so that it can be identified and communicate with the payment network. Specifically, the AndroidManifest.xml needs to be updated with the following fields:

AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="co.openfabric.pba.sample">

    <application>

        <meta-data
            android:name="co.openfabric.nfc.tenant_id"
            android:value="<value provided by Open Fabric>" />
        <meta-data
            android:name="co.openfabric.nfc.provider_ids"
            android:value="<value provided by Open Fabric>" />
        …
    </application>
</manifest>

The tenant_id and provider_ids here are referring to Payment Network Credentials, and will be provided by Open Fabric during the onboarding process.

Firebase Cloud Messaging setup

The NFC SDK uses Firebase Cloud Messaging (FCM) to securely communicate with our backend services. This integration assumes your application already has FCM configured for its existing push notification functionality.

We will provide a dedicated Firebase app configuration file that should be placed in the app's resources directory (app/src/main/res/raw/of_tap_and_pay_google_services.json). During initialization, the SDK automatically loads this configuration and establishes a separate Firebase instance to receive NFC-related messages from our servers.

This approach ensures that SDK communications remain isolated from your app's primary FCM implementation.

We simply expect the FCM device token to be shared with the SDK. We also expect you to simply forward any received messages pertaining to our operations to our NFC SDK. This above can simply be done within the app’s main FirebaseMessagingService class, as follows:

FirebaseMessagingServiceImpl.kt

class FirebaseMessagingServiceImpl: FirebaseMessagingService() {
    override fun onNewToken(token: String) {
        OpenFabricFirebaseMessagingUtil.onNewToken(baseContext)
        // Continue processing the new token, .i.e send it to the tenant backend
    }

    override fun onMessageReceived(message: RemoteMessage) {
        if (OpenFabricFirebaseMessagingUtil.onMessageReceived(baseContext, message)) {
            // Message designated to the SDK, no further handling is required
            return
        }

        // Message designated to the app, handle it here
    }
}

Register the application callbacks

Your application can implement callbacks for Wallet, Card and Transaction life-cycle events and register them for the SDK. Some callbacks, such as Card.onCardActivated, Card.onCardUpdated, are mandatory, while others are optional.

Example of the TransactionListener class:

TransactionListener.kt

class TransactionListener: NfcTransactionListener() {
    ...
}

It can be registered in the AndroidManifest.xml as follows:

AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="co.openfabric.pba.sample">

    <application>
       ...

       <meta-data
            android:name="co.openfabric.nfc.CardEventListener"
            android:value="co.openfabric.pba.sample.CardListener" />
        <!-- Optional, callbacks for NFC transaction life-cycle events -->
        <meta-data
            android:name="co.openfabric.nfc.NfcTransactionListener"
            android:value="co.openfabric.pba.sample.TransactionListener" />
        <!-- Optional, callbacks for Wallet life-cycle events -->
        <meta-data
            android:name="co.openfabric.nfc.WalletNotificationListener"
            android:value="co.openfabric.pba.sample.WalletNotificationListener" />

        ...
    </application>
</manifest>

Reference App

Open Fabric will provide you with a reference app. The goal with this application is to provide you with a fully built reference app that has already integrated with our SDKs. We hope this will help speed up your development process.

Feel free to reach out to us if you have any questions with our reference app.

Development Support

Debug SDK generates debug logs along its execution and these logs can be shared with the Open Fabric support team in case unexpected behaviors occur within the SDK.

Debug logs are written into 2 files, logA.txt and logB.txt. These log files need to be accessed from Google’s Files app (e.g. from Gmail or Google Drive).

Alternatively, you can use ADB CLI tool to retrieve the log files

adb exec-out run-as com.example.myapp cat files/logs/logA.txt > logA.txt
adb exec-out run-as com.example.myapp cat files/logs/logB.txt > logB.txt