Setup

12 min

Credentials

To be able to add the Toro SDK to your project, you will need access to our Maven repository, which we will provide credentials for.

We recommend creating a toro.properties file to store the credentials at the root directory of your project.

 MAVEN_REPO_URL=<repository-url>
 MAVEN_USERNAME=<your-username>
 MAVEN_PASSWORD=<your-password>

Ensure you add toro.properties to your .gitignore (or equivalent) to avoid commiting the credentials to your project's version control.

You could also set these as environment variables on your system if you wanted.

Add Maven repository to project

You will then need to add the repository in your project.

Your repositories block could be in settings.gradle or project-level build.gradle depending on how your project is setup. Our example shows the setup in settings.gradle.

// If you are using a properties file, you can load it here
def toroProps = new Properties()
def propsFile = file("toro.properties")
if (propsFile.exists()) {
    propsFile.withInputStream { stream ->
        toroProps.load(stream)
    }
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
    repositories {
        google()  // Keep your existing repositories
        mavenCentral()
        // Add the Toro Maven repository
        maven {
            name 'ToroRepo'
            url = uri(toroProps.getProperty('MAVEN_REPO_URL') ?:
                    System.getenv('MAVEN_REPO_URL') ?:
                    { throw new GradleException('No URL found for Toro repository') }())
            credentials {
                username = toroProps.getProperty('MAVEN_USERNAME') ?:
                        System.getenv('MAVEN_USERNAME') ?:
                        { throw new GradleException('No username found for Toro repository') }()
                password = toroProps.getProperty('MAVEN_PASSWORD') ?:
                        System.getenv('MAVEN_PASSWORD') ?:
                        { throw new GradleException('No password found for Toro repository') }()
            }
        }
    }
}

In this snippet we support adding credentials from both environment variables and the toro.properties file. The reason being it tends to be easier to use a properties file locally, and environment variables are typically better suited for CI/CD pipelines.

Declare the dependencies

In your app-level build.gradle you can now add the Toro SDK as a dependency.

dependencies {
    releaseImplementation "services.cabcard.toro:toro:${toroVersion}"
    debugImplementation "services.cabcard.toro:toro-debug:${toroVersion}"
}

Ensure you declare the dependencies like this. The release variant is obfuscated with logging disabled by default for security reasons. We do retain the mapping, so you can contact us to decode stack traces and help diagnose production issues if necessary.

Manifest Permissions

Ensure the following permissions are present in your AndroidManifest.xml:

    <!-- These are only required if you want to collection geolocation for transactions -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <!-- These are always required to connect to Miura devices over Bluetooth -->
    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
    <!-- This is for devices below Android 12 (API 31) -->
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />

Initialisation

In the sample application, we use Dagger Hilt to handle dependency injection and initialisation, but you can feel free to use any other method you prefer.

Dagger Hilt

@Module
@InstallIn(SingletonComponent::class)
object AppModule {

    @Provides
    @Singleton
    fun provideToroClient(@ApplicationContext context: Context): ToroClient {
        return ToroClient(
            applicationContext = context,
            config = ToroConfig(
                merchant = MerchantConfig(
                    categoryCode = "5812" // Your merchant category code
                )
            )
        )
    }
}

Then in your view model, you can inject the ToroClient instance:

@HiltViewModel
class TransactionViewModel @Inject constructor(
    private val toro: ToroClient
)

Alternative

Create a singleton object to manage the SDK instance:

object ToroSdk {
    private var _instance: ToroClient? = null
    val instance: ToroClient
        get() = checkNotNull(_instance) {
            "ToroSDK not initialised. Call ToroSdk.initialise() in your Application class"
        }
    fun initialise(applicationContext: Context) {
        if (_instance != null) {
            return  // Already initialised
        }
        _instance = ToroClient(
            applicationContext = applicationContext,
            config = ToroConfig(
                merchant = MerchantConfig(
                    categoryCode = "5812" // Your merchant category code
                )
            )
        )
    }
}

Initialise the SDK in your Application class:

class MainApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        ToroSdk.initialise(applicationContext)
    }
}

Then use it in your ViewModels or other classes:

public class TransactionViewModel extends ViewModel {
    private final ToroClient toro = ToroSdk.getInstance();
}

You must provide applicationContext (not any other context) to the ToroClient constructor.

The SDK should only be initialised once during the app's lifecycle.