# Mastercard Sonic Reference App.
---
An Android application project which demonstrates the integration of Android SDK for Mastercard Sonic Brand at Checkout.

The purpose of this reference application is to show the appropriate placement of code snippets to initialize the SDK and play the Checkout Sound and Animation.

For detail Android SDK documentation, visit [here](https://developer.mastercard.com/mastercard-sonic-branding/documentation/).

# Technologies & Tools used
---
#### Language
* Kotlin 1.8.20 and above

#### Supported OS
* Android Lollipop and above

### Supported OS Version for Haptics Feedback
* API 26 and above

#### IDE used
* Android Flamingo | 2022.2.1 Patch 2 and above
* Gradle 8.2.1 and above

#### Run the application.
* Open Android Studio and select open existing android project.
* Wait for Gradle Sync to complete.
* Connect real device or start emulator.
* Run the application from android studio on device or emulator.

# Features
---
This application implements the following primary use cases:

1. A transaction using Mastercard payment card
2. A transaction using payment card other than Mastercard


## 1. A transaction using Mastercard payment card

When checkout is performed using Mastercard payment card, Mastercard Checkout Sound and Animation needs to be played on approval of the transaction.

Note: Mastercard Checkout Sound and Animation must not be played if the transaction is declined or failed. The fail scenario is not covered in the reference application.

### Actors
* Consumer/Shopper
* Merchant Application

### Preconditions

The user has selected products to be purchased and is ready to perform checkout.

### User journey
* User is on the checkout screen
* User ***selects the Mastercard payment card*** from saved cards
* User confirms the order and initiates the payment.
* The transaction is processed and successfully approved.
* ***Mastercard Checkout Sound and Animation is played*** which enhances sensory experience and enforces trust in the Mastercard brand.
* The order is placed and the user can see the order ID.

#### Code Example

* Android SDK provides 3 types of configuration to be played on successful transactions. All of them are self explanatory. This value goes under `sonicType`.

  1. `SOUND_AND_ANIMATION` *(default)*
  2. `SOUND_ONLY`
  3. `ANIMATION_ONLY`

  This reference app implements `SOUND_AND_ANIMATION`. To change other modes like `SOUND_ONLY` or `ANIMATION_ONLY`, go to `ConfirmOrderFragment` at line number `146`

* We have two separate environment to test this - 
  1. `SANDBOX`
  2. `PRODUCTION`

  This environment can be setup in the parameter `sonicEnvironment`. `SANDBOX` is used for developing and testing environment, whereas `PRODUCTION` is used for production or live environment.
  ___
  > :warning: **_WARNING:_** Please do not use `PRODUCTION` for testing purpose
  ___

* For playing different sound and animation we have separate cues for different occasions. This can be configured for `sonicCue` at line number `147`. For now you can have following values -

  1. `checkout`
  2. `securedby`

* You also need to provide Merchant details. You can update them from line number `133` of `ConfirmOrderFragment`. Merchant details has following properties that can be updated -

  1. `merchantId` - Merchant ID (Merchant Identification Number) is a unique identifier(15-digit code) assigned to each merchant at a time of onboarding process by their payment processor or acquiring bank for Mastercard Transactions.
  2. `merchantName` - Name of the Merchant provided during the merchant onboarding process with payment processor or acquiring bank. This information can be obtained by contacting their customer support or merchant services department.
  3. `countryCode` - 3 digit iso country code of the merchant accepting the Mastercard payment is identified based on the merchant’s physical address associated with their apps or POS device. You can complete list of country codes from developer zone documentation from [here](https://developer.mastercard.com/mastercard-sonic-branding/documentation/android/code-and-formats/#country-codes).
  4. `city` - City of the merchant accepting the Mastercard payment is identified based on the merchant’s physical address associated with their apps or POS hardware.
  5. `merchantCategoryCodes` - Merchant Category Code (MCC) is a four-digit code used to categorize businesses based on the type of products or services they offer by Mastercard to classify and track transactions. Make sure you provide values in `Array`. List of category codes can be found over [here](https://www.mastercard.us/content/dam/mccom/en-us/documents/rules/quick-reference-booklet-merchant-edition.pdf).
  6. `isHapticsEnabled` - To enable or disable haptic feedback. By default, haptics is enabled.
  
      ```kotlin
            private fun prepareSonicAnimation() {
                   sonicMerchant = SonicMerchant.Builder()
                       .merchantName(/*merchant name*/)
                       .city(/*city*/)
                       .merchantCategoryCodes(arrayOf(/*merchant category codes*/))
                       .countryCode(/*country code*/)
                       .merchantId(/*merchant ID*/)
                       .build()
    
                   sonicController.prepare(sonicType = SonicType.SOUND_AND_ANIMATION,
                       sonicCue = "checkout",
                       sonicEnvironment = SonicEnvironment.SANDBOX,
                       merchant = sonicMerchant,
                       isHapticsEnabled = true,
                       context = requireContext(),
                       onPrepareListener = object : OnPrepareListener {
                           override fun onPrepared(statusCode: Int) {
                               Log.d(TAG, "onPrepared() statusCode = $statusCode")
                           }
                       })
        }
     ```

* The animation will be played with a black background by default. To change the background to white, go to `ConfirmOrderFragment` and uncomment the code at line number `76`.

    ```kotlin
        val sonicView = findviewById(R.id.sonic_view)
        sonicView.background = SonicBackground.WHITE
    ```

* It can also be done via layout xml file. Go to `fragment_confirm_order.xml` and add `app:sonicBackground="white"` to change the background to white.

    ```xml
        <com.mastercard.sonic.widget.SonicView
            android:id="@+id/sonic_view"
            android:layout_width="match_parent"
            android:layout_height="match_parent"
            app:sonicBackground="white"
        />
    ```

## 2. A transaction using payment card other than Mastercard

### User journey

* User is on the checkout screen
* ***User selects the payment card other than Mastercard*** from saved cards
* User confirms the order and initiates the payment.
* The transaction is processed and successfully approved.
* ***Mastercard Checkout Sound and Animation is NOT played***.
* The order is placed and the user can see the order ID.

#### Code Example

* Mastercard payment card is selected by default. The card option is set in `ConfirmOrderFragment` at line number `167`

    ```kotlin
            private fun getSelectedPaymentCard(position: Int = selectedPaymentCardPosition): PaymentCard {
                    return edtPayCards.adapter.getItem(position) as PaymentCard
            }
    ```

* `paymentSuccess()` is responsible for playing Mastercard Checkout Sound and Animation based on card type

    ```kotlin
            private fun paymentSuccess() {
                    if (dialogShown) {
                        dialogShown = false
                        orderGroup.visibility = View.GONE
                        sonicView.visibility = View.VISIBLE

                        if (getSelectedPaymentCard().type() != CardType.MASTERCARD) {
                            findNavController().navigate(R.id.action_confirmOrderFragment_to_thankYouFragment)
                        } else {
                            sonicController.play(sonicView, object : OnCompleteListener {
                                override fun onComplete(statusCode: Int) {
                                    Log.d(TAG, "onComplete() statusCode = $statusCode")
                                    isSonicAnimationCompleted = true
                                    findNavController().navigate(R.id.action_confirmOrderFragment_to_thankYouFragment)
                                }
                            })
                        }

                    }
                }

    ```

   Note:- `sonicController.play` must be followed by `sonicController.prepare` call.

## Author
---
- Name: **Mastercard Sonic Brand**
- Contact: **Ask.Brand.Manager@mastercard.com**

## Support
---
Please email to **Ask.Brand.Manager@mastercard.com** for additional support if required.

## License
---
Apache 2.0 License

### Copyright © 1994-2020, All Right Reserved by Mastercard.