Step 1: Initialise

Mastercard Sonic Branding - Android SDK provides SonicController and SonicView as a public interface to the sdk.

Sonic Controller

SonicController provides a set of APIs for playing sound, animation, and haptics feedback. Initialize SonicController as follows:

Kotlin

import androidx.fragment.app.Fragment
import com.mastercard.sonic.controller.SonicController

class SonicFragment : Fragment(R.layout.fragment_sonic) {

    private val sonicController = SonicController()
    
}

Java

import androidx.fragment.app.Fragment;
import com.mastercard.sonic.controller.SonicController;

public class SonicFragment extends Fragment {

    private SonicController sonicController = new SonicController();

    public SonicFragment(){

    }
}

SonicController exposes the following methods:

Method	Description
fun prepare(sonicType: SonicType = SonicType.SOUND_AND_ANIMATION, sonicCue: String, sonicEnvironment: SonicEnvironment, merchant: SonicMerchant, isHapticsEnabled: Bool = true, context: Context, onPrepareListener: OnPrepareListener)	prepare() method to prepare a set of resources with below parameters sonicType param for sonic type merchant app wants to prepare sonicCue param for the cue merchant app wants to prepare sonicEnvironment Environment for which sonic is getting prepared production - for production environment sandbox - for development and testing. merchant merchant information for that sonic is getting prepared isHapticsEnabled enabling/disabling haptics feedback, default value is true. context is current state of the application OnPrepareListener.onPrepared callback with status code as success, partial success, or failure.
fun play(sonicView: SonicView? = null, onCompleteListener: OnCompleteListener)	play() should be call after successful prepare(). This plays the sonic (sound and/or animation) sonicView the view in which animation will play completion provides status in callback with status code success, partially success or fail.

Sonic View

SonicView is a custom view that displays the Sonic Animation with a background. You can add SonicView into the parent view with any width and height value. It is recommended to provide the following properties to SonicView with a proper value.

Property	Description	Type	Default Value
android:layout_width	Set the width	Integer	320dp, if width is provided as wrap_content
android:layout_height	Set the height	Integer	240dp, if height is provided as wrap_content
sonicBackground	Set the sonic background color. It can set background color as black or white	Enum	black

Note: It is recommended to add SonicView on a full screen without padding. Padding is used to add space between two views. When you add padding to the SonicView, the background of the parent view gets displayed in the padded part which can lead to a bad user experience.

You can add SonicView either in XML or programmatically as follows:

• Add SonicView in XML

Xml

<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    xmlns:app="http://schemas.android.com/apk/res-auto">
    <!-- SonicView in a full screen -->
    <com.mastercard.sonic.widget.SonicView
        android:id="@+id/sonic_view"
        android:layout_width="0dp"
        android:layout_height="0dp"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent" />
        <!-- app:sonicBackground="white" will enable white background when animation will be played-->
        <!-- app:sonicBackground="black" will enable black background when animation will be played-->
</androidx.constraintlayout.widget.ConstraintLayout>

Create an instance of SonicView in Fragment/Activity.

Kotlin

// import SonicView
import com.mastercard.sonic.widget.SonicView

// Create SonicView instance 
private lateinit var sonicView: SonicView

    override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View? {
            return inflater.inflate(R.layout.fragment_sonic, container, false)
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
           super.onViewCreated(view, savedInstanceState)
           sonicView = view.findViewById(R.id.sonic_view)
           sonicView.background = SonicBackground.BLACK
    }

Java

// import SonicView
import com.mastercard.sonic.widget.SonicView;
// Create SonicView instance
private SonicView sonicView;

    @Nullable
    @Override
    public View onCreateView(@NonNull LayoutInflater inflater, @Nullable ViewGroup container, @Nullable Bundle savedInstanceState) {
         return inflater.inflate(R.layout.fragment_sonic, container, false);
    }

    @Override
    public void onViewCreated(@NonNull View view, @Nullable Bundle savedInstanceState) {
        super.onViewCreated(view, savedInstanceState);
        sonicView = view.findViewById(R.id.sonic_view);
        sonicView.background = SonicBackground.BLACK;
    }

• Add SonicView Programmatically

Create a blank layout file in the project and add the following:

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:id="@+id/main_content">

</androidx.constraintlayout.widget.ConstraintLayout>

Add SonicView as a child to ConstraintLayout.

Kotlin

//import statement
import android.os.Bundle
import android.view.View
import androidx.constraintlayout.widget.ConstraintLayout
import com.mastercard.sonic.widget.SonicView

    //declare sonic view in a fragment
    private lateinit var sonicView: SonicView
    
    //declare onCreateView with a newly created layout file
    override fun onCreateView(inflater: LayoutInflater, container: ViewGroup?, savedInstanceState: Bundle?): View? {
                return inflater.inflate(R.layout.fragment_sonic, container, false)
        }

    //create sonicView instance and add to parent view in onViewCreated method
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        var constraintLayout : ConstraintLayout = view.findViewById(R.id.main_content)
        sonicView = SonicView(requireContext())
        constraintLayout.addView(sonicView)
        sonicView.layoutParams = ConstraintLayout.LayoutParams(ConstraintLayout.LayoutParams.MATCH_PARENT, ConstraintLayout.LayoutParams.MATCH_PARENT)
    }

Java

//import statement
import android.os.Bundle;
import android.view.LayoutInflater;
import android.view.View;
import android.view.ViewGroup;
import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import androidx.constraintlayout.widget.ConstraintLayout;
import com.mastercard.sonic.widget.SonicView;

    //declare sonicView in a fragment
    private SonicView sonicView;

    //declare onCreateView with a newly created layout file
    @Nullable
    @Override
    public View onCreateView(@NonNull LayoutInflater inflater, @Nullable ViewGroup container, @Nullable Bundle savedInstanceState) {
         return inflater.inflate(R.layout.fragment_sonic, container, false);
    }

    //create sonicView and add it to parent view in onViewCreated 
    @Override
    public void onViewCreated(@NonNull View view, @Nullable Bundle savedInstanceState) {
        super.onViewCreated(view, savedInstanceState);
        ConstraintLayout constraintLayout = view.findViewById(R.id.main_content);
        sonicView = new SonicView(getContext());
        sonicView.setLayoutParams(new ConstraintLayout.LayoutParams(ConstraintLayout.LayoutParams.MATCH_PARENT, ConstraintLayout.LayoutParams.MATCH_PARENT));
        constraintLayout.addView(sonicView);
    }

ComposeUI

@Composable
fun SonicViewComposable(onViewCreated: (SonicView) -> Unit) {
    val context = LocalContext.current
    val sonicView = remember { SonicView(context) }
    AndroidView(factory = { sonicView.also { it.background = SonicBackground.BLACK } },
        modifier = Modifier.fillMaxWidth().fillMaxHeight()) { view ->
        onViewCreated(view)
    }
}

Sonic Merchant

SonicMerchant needs to be initialized and required to be pass it in prepare() method.

Kotlin

    private lateinit var sonicMerchant: SonicMerchant

    sonicMerchant = SonicMerchant.Builder()
                .merchantName("Uber")
                .city("New York")
                .merchantCategoryCodes(arrayOf("MCC 5122"))
                .countryCode("USA")
                .merchantId("UberId")
                .build()

Java

    private SonicMerchant sonicMerchant;
    
    sonicMerchant = new SonicMerchant.Builder()
            .merchantName("Uber")
            .city("New York")
            .merchantCategoryCodes(new String[]{"MCC 5122"})
            .countryCode("USA")
            .merchantId("UberId")
            .build();

Below properties needs to be provided by merchant to configure SonicMerchant.

Property	Description	Type	Required	Reference
merchantName	Name that the business is known by. It will be the name that is used on all official communications. This information can be obtained by contacting your payment processor, acquiring bank’s customer support and merchant services department or Mastercard Representative. Note: If you are a service provider that engages in 1-to-many integrations, you can include your business name	String	Yes
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. This information can be obtained by contacting payment processor or acquiring bank’s customer support or merchant services department.	String	No
countryCode	3 digit ISO country code of the merchant accepting the Mastercard payments. The country is identified based on the country where the POS device is installed and accepting payments, or the merchant’s country associated with its app.	String	Yes	‘USA’ Country Codes
city	City of the merchant is identified based on the location where the POS device is installed and accepting Mastercard payments, or the merchant’s city associated with its app.	String	No
merchantCategoryCodes	Merchant Category Code (MCC) is a four-digit code used to categorize businesses based on the type of products or services. This information can be obtained by contacting your payment processor, acquiring bank’s customer support and merchant services department or Mastercard Representative. Note: If you are a service provider that engages in 1-to-many integrations, please insert [‘MCC 0000’]	String[]	Yes	[‘MCC 5122’] Codesopens in a new tab