# Android

SPIDX Button is an Android library conceived to be integrated into an Android Application. It provides a Button View to be used in the application and a class that communicates with SPIDX server to retrieve a Dynamic Link and ID for the transaction defined by a Use Case.

## Requirements

* Minimum Android Version

  > Android 8.0 (SDK 26), “Oreo”.
* Development environment

  > Recommended to use Android Studio IDE

## Configuration

For the library to work correctly, the following configuration is needed:

### Import .aar lib

* To import the .aar lib in your application, it is recommended to follow the [Android official documentation](https://developer.android.com/studio/projects/android-library).

### Internet permission

* SPIDX button usage requires the application to provide internet connection. Within the `AndroidManifest.xml` file, add the internet access permission:

  ```xml
  <manifest xmlns:android="http://schemas.android.com/apk/res/android"
  	package="com.griaule.spidxbutton">
  	...
  	<uses-permission android:name="android.permission.INTERNET" />
  	...
  </manifest>
  ```

### Dependencies

* Some dependencies are required to use SPIDX Button. Within the `build.gradle` file, in `:app` scope, add the following dependencies:

  ```gradle
  dependencies {
  	...
  	implementation 'com.squareup.retrofit2:retrofit:2.9.0'
  	implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
  	implementation 'com.squareup.retrofit2:converter-scalars:2.9.0'
  	implementation 'com.squareup.okhttp3:logging-interceptor:3.13.1'
  }
  ```

## Classes and Methods

The library provides the Class `SpidxAuth` that has two parameters: `apiKey` and `useCaseName`, with two methods to retrieve data from SPIDX API. The methods are described below (Kotlin pattern):

* `collection(callback: Callback)`
  * This method will use `apiKey` and `useCaseName` to retrieve the Dynamic Link and Transaction ID from SPIDX API. The response is described in the section below.
* `verification(spidx: String, callback: Callback)`
  * This method will use `apiKey`, `useCaseName`, and `spidx` to retrieve the Dynamic Link and Transaction ID from SPIDX API. The response is described in the section below.

### Responses

These methods use the object `callback` that implements the interface `Callback`. This interface has two methods:

* `onSuccess(useCaseData: UseCaseData)`
  * This method is called when the request succeeds and returns the object `useCaseData`, of type `UseCaseData`. This object has two fields: `dynamicLink`, which is the dynamic link for the transaction, and `transactionID`, which is the id of the transaction.
* `onFailure(useCaseError: UseCaseError)`
  * This method is called when the request fails and returns the object `useCaseError`, of type `UseCaseError`. This object has three fields: `type`, which is the type of the error, `code`, which is the code of the error, and `message`, which is the message describing the error.

## Usage

It is recommended to use the Button View provided along with the SPIDX Button library. With the Dynamic Link received, it’s possible to create an *Intent* that will call SPIDX app.

### Add the button in your application layout

* In the application layout, add the following code:

  ```xml
  <com.griaule.spidxbutton.views.SpidxButton
   android:id="@+id/spidx_button"
   android:layout_width="wrap_content"
   android:layout_height="wrap_content"/>
  ```

### Configure the button click listener and call SPIDX API:

Some examples of the classes and methods usage in Kotlin and Java are provided below:

* In Kotlin, use:

  ```kotlin
  val spidxButton = findViewById<SpidxButton>(R.id.spidx_btn)
  spidxButton.setOnClickListener {
  	SpidxAuth("apiKey", "useCaseName")
  		.collection(object : Callback {
  			override fun onSuccess(useCaseData: UseCaseData) {
  				// Deal with success data returned. For example, creating an Intent and calling startActivity()
  				...
  			}

  			override fun onFailure(useCaseError: UseCaseError) {
  				// Deal with the error returned
  				...
  			}
  		})
  }
  ```
* In Java, use:

  ```java
  SpidxButton spidxButton = findViewById(R.id.spidx_button);
  SpidxAuth spidxAuth = new SpidxAuth("apiKey", "useCaseName");
  spidxButton.setOnClickListener(view -> spidxAuth.collection(new Callback() {
  	@Override
  	public void onSuccess(@NotNull UseCaseData useCaseData) {
  		// Deal with success data returned. For example, creating an Intent and calling startActivity()
  		...
  	}

  	@Override
  	public void onFailure(@NotNull UseCaseError useCaseError) {
  		// Deal with the error returned
  		...
  	}
  }));
  ```