# GiroCard Branding SDK Documentation

## Introduction

Netcetera offers a lightweight Android SDK designed to facilitate the implementation and execution of GiroCard Branding confirmation. This SDK is intended for use when a Point of Interaction (POI) accepts payment cards or accounts to provide users with multi-sensory confirmation.

The Android SDK supports the following optional features, allowing you to customize the girocard experience in your application:

* Sound
* Vibration

While the animation is always included, you have the flexibility to choose which optional features accompany it, providing a tailored multi-sensory confirmation experience.

#### Supported Versions

* Android 6 (API Level 23) and above

#### Supported Platforms

* Android-based Point of Sale (POS) terminals
* Android Applications

### SDK Flavors

1. **MP4 Flavor:** Uses MP4 video for the animation.
2. **GIF Flavor:** Uses a GIF image and sound for the animation. This flavor requires Glide, an external dependency, to display the GIF image.

## Integration

### MP4 Flavor

To integrate the MP4 Video flavor of the `GiroCard Branding SDK` into your project, follow these steps:

1. Add the provided `girocardbranding-sdk-mp4-X.X.X.aar` artifact to the `libs/` directory of your Application or Library. For example, if your Application module is named app, the directory would be `app/libs/`.
2. Add the GiroCard Branding SDK dependency in the Application or Library `build.gradle` file:

```gradle
dependencies {
  implementation files('libs/girocardbranding-sdk-mp4-X.X.X.aar')
}
```

### GIF Flavor

To integrate the GIF Image and Sound flavor of the `GiroCard Branding SDK` into your project, follow these steps:

1. Add the provided `girocardbranding-sdk-gif-X.X.X.aar` artifact to the `libs/` directory of your Application or Library. For example, if your Application module is named app, the directory would be `app/libs/`.
2. Add the GiroCard Branding SDK and Glide dependencies in the Application or Library `build.gradle` file:

```gradle
dependencies {
  implementation files('libs/girocardbranding-sdk-gif-X.X.X.aar')
  implementation 'com.github.bumptech.glide:glide:latest_version'
}
```

Replace `latest_version` with the latest Glide version available.

## API

The Public API for the `GiroCard Branding SDK` consists of the `GiroCardBrandingView`, `GiroCardBrandingConfiguration`, and `GiroCardBrandingController`.

### View

The Android View on which the multi-sensory confirmation will be presented is the `GiroCardBrandingView`.

#### XML Layouts

You can add the `GiroCardBrandingView` in an XML Layout as follows:

```xml
<com.netcetera.girocardbranding.sdk.api.GiroCardBrandingView
    android:id="@+id/girocard_branding_view"
    android:layout_width="Xdp"
    android:layout_height="Ydp" />
```

You can access the `GiroCardBrandingView` in your `Activity` as follows:

```kotlin
val girocardBrandingView = findViewById<GiroCardBrandingView>(R.id.girocard_branding_view)
```

#### ComposeUi

Create `ComposeView` in the activity using `GiroCardBrandingView`. This `GiroCardBrandingViewComposable` can then be used to render `GiroCardBrandingView`.

```kotlin
// Create ComposableView of GiroCardBrandingView
@Composable
fun GiroCardBrandingViewComposable(context: Context, onViewCreated: (GiroCardBrandingView) -> Unit) {
    val brandingView = remember { GiroCardBrandingView(context) }
    AndroidView(
        factory = { brandingView },
        modifier = Modifier
            .fillMaxWidth()
            .fillMaxHeight()
    ) { view ->
        onViewCreated(view)
    }
}

// ActivityView to render GiroCardBrandingView ComposableView
@Composable
fun GiroCardBrandingActivityView() {
    val context = LocalContext.current
    lateinit var girocardBrandingView: GiroCardBrandingView

    Column {
        // Surface on which to render the GiroCardBrandingView
        Row(
            modifier = Modifier
                .fillMaxWidth()
                .weight(1F, true)
        ) {
            GiroCardBrandingViewComposable(context, onViewCreated = {
                girocardBrandingView = it
            })
        }
        // ...
    }
}

class GiroCardBrandingActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            GiroCardBrandingTheme {
                Surface(modifier = Modifier.fillMaxSize()) {
                    GiroCardBrandingActivityView()
                }
            }
        }
    }
}
```

### Configuration

The configuration for the GiroCard Branding SDK is provided via `GiroCardBrandingConfiguration` with the following arguments:

| Argument         | Value                                                                                            |
|------------------|--------------------------------------------------------------------------------------------------|
| includeSound     | Boolean value defining if sound should be included during multi-sensory confirmation             |
| useVibration     | Boolean value defining if vibration should be included during multi-sensory confirmation         |

### Controller

Initialize the `GiroCardBrandingController` as follows:

| Argument          | Value                                                                    |
|-------------------|--------------------------------------------------------------------------|
| context           | `Context` of the `Activity` that is in the foreground of the application |

After initialization, invoke `play(...)` to play the multi-sensory confirmation with the following arguments:

| Argument           | Value                           |
|--------------------|---------------------------------|
| view               | `GiroCardBrandingView`          |
| configuration      | `GiroCardBrandingConfiguration` |
| onCompleteListener | `OnCompleteListener`            |

When the multi-sensory confirmation finishes, the GiroCard Branding SDK notifies the integrator via the `OnCompleteListener`:

```kotlin
girocardBrandingController.play(
    view, 
    configuration, 
    object : OnCompleteListener {
        override fun onComplete() {
            // Handle successful completion of the multi-sensory confirmation
        }

        override fun onFailure(reason: String) {
            // Handle error that has occurred in the GiroCard Branding SDK at runtime
        }
    }
)
```
