SDK Integration

This guide explains how to integrate the SDK into your Android application, enabling you to manage sessions and interact with the Prevent SDK for Prevent form processing.

Overview

The SDK provides methods to initialize a session, manage the session state, handle user inputs, and navigate through a series of screens. This documentation demonstrates how to set up the flow of screens and uses a set of example screens to demonstrate the integration: (WelcomeScreen, PreventForm, ResultScreen, and BreakScreen). This SDK provides integration for both Jetpack Compose-based apps and traditional Android apps with Activity/Fragment and XML views.

Key SDK Components

• PaymentContext: Manages the session state and tracks the current session’s progress.
• PreventForm: Displays the form for users to enter payment details.
• ResultScreen: Displays the outcome of the session (e.g., payment successful, failed, or error).
• BreakScreen: Displays a break screen to collect additional information about the user or payment.

Using the SDK in Jetpack Compose

Example Integration

In Jetpack Compose, the SDK can be integrated using Composables like so:

Step 1: Initialize the SDK

To begin, initialize the PaymentContext with your server’s URL and the required appId.

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // Initialize PaymentContext with the backend server URL and appId
        PaymentContext.initialize("http://10.0.2.2:8080", "xyz456")
        setContent {
            ExampleApp()
        }
    }
}

Step 2: Define the Screens and Flow

The ExampleApp composable controls the flow of the different screens based on the session state. The example screens are:

1. Welcome Screen: Displayed at the beginning.
2. Prevent Form: User interacts with the form to provide payment information.
3. Break Screen: A screen to collect additional information about the user.
4. Result Screen: Displays the result of the session (payment successful, failed, or error).

@Composable
fun ExampleApp() {
    MaterialTheme {
        var currentScreen by remember { mutableStateOf("welcome")}

        // Navigate through different screens based on the session state
        when (currentScreen) {
            "welcome" -> WelcomeScreen {
                currentScreen = "paymentForm"
            }
            "paymentForm" -> PreventForm(
                onResult = {
                    currentScreen = "result"
                },
                onBreak = {
                    currentScreen = "break"
                }
            )
            "break" -> BreakScreen {
                PaymentContext.resumeSession() // Resume the session after break
                currentScreen = "paymentForm"
            }
            "result" -> ResultScreen() {
                currentScreen = "welcome"
            }
        }
    }
}

Step 3: Welcome Screen

The WelcomeScreen is a demonstration of the screen that appears immediately predecing the transition into the Prevent SDK. It prompts the user to proceed to the next step which triggers the hand-off (onStartPayment).

@Composable
fun WelcomeScreen(onStartPayment: () -> Unit) {
    // UI layout for the welcome screen
    Scaffold(
        topBar = { TopAppBar(title = { Text("ABC Bank") }) }
    ) { paddingValues ->
        Column(
            modifier = Modifier.fillMaxSize().padding(paddingValues).padding(16.dp),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.SpaceEvenly,
        ) {
            Text("Welcome to ABC Bank", fontSize = 24.sp, modifier = Modifier.padding(bottom = 16.dp))
            Text("Manage your accounts, payees, and more", fontSize = 16.sp)
            Button(onClick = onStartPayment) {
                Text("Add a New Payee", fontSize = 16.sp)
            }
        }
    }
}

Step 4: Prevent Form Screen

The PreventForm composable built into the Prevent SDK displays the form for entering information.

Step 5: Break Screen

If the SDK will return to the originating application (e.g., to gather more information from the user), a BreakScreen composable can be used such as in this example. onResumePayment will return the user to the Prevent SDK:

@Composable
fun BreakScreen(onResumePayment: () -> Unit) {
    Scaffold(
        topBar = { TopAppBar(title = { Text("ABC Bank") }) }
    ) { paddingValues ->
        Column(
            modifier = Modifier.fillMaxSize().padding(paddingValues).padding(16.dp),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.SpaceEvenly,
        ) {
            Text("We'd like to collect some additional information", fontSize = 24.sp, modifier = Modifier.padding(bottom = 16.dp))
            Text("This is to help protect your payment", fontSize = 16.sp)
            Button(onClick = onResumePayment) {
                Text("Continue", fontSize = 16.sp)
            }
        }
    }
}

Step 6: Result Screen

The ResultScreen displays the result of the payment process (success, failure, or error) This example displays text depending on the result of the Prevent analysis.

@Composable
fun ResultScreen(onBackToWelcome: () -> Unit) {
    Scaffold(
        topBar = { TopAppBar(title = { Text("ABC Bank") }) }
    ) { paddingValues ->
        Column(
            modifier = Modifier.fillMaxSize().padding(paddingValues).padding(16.dp),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.SpaceEvenly,
        ) {
            val sessionState by PaymentContext.sessionState.collectAsState()
            when (sessionState?.state) {
                ClosedSessionState.ERROR -> {
                    Text("Error during payment", fontSize = 24.sp)
                }
                ClosedSessionState.RESOLVED -> {
                    Text("Payment Successful!", fontSize = 24.sp)
                }
                ClosedSessionState.FAILED -> {
                    Text("Payment Failed", fontSize = 24.sp)
                }
            }
            Button(onClick = {
                PaymentContext.clearSessionState()
                onBackToWelcome()
            }) {
                Text("Return Home", fontSize = 16.sp)
            }
        }
    }
}

---

Using the SDK in Traditional Activity/Fragment with XML Views

Example Integration

In traditional Activity/Fragment-based apps, the SDK can be integrated using fragments and XML views. Below is an example integration using ResultFragment, WelcomeFragment, PreventFormFragment, and BreakFragment. These example fragments represent equivalent fragments in your application.

Main Activity Integration (Similar to Compose-based app)

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        PaymentContext.initialize("http://10.0.2.2:8080", "xyz456")  // Initialize PaymentContext

        val startPaymentButton: Button = findViewById(R.id.startPaymentButton)
        startPaymentButton.setOnClickListener {
            supportFragmentManager.beginTransaction()
                .replace(R.id.fragmentContainer, PreventFormFragment())
                .addToBackStack(null)  // Allows the user to go back to the Welcome screen
                .commit()
        }
    }
}

Welcome Fragment

This fragment serves as the initial screen where the user can start the transition to the Prevent SDK.

class WelcomeFragment : Fragment(R.layout.fragment_welcome) {

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        val startPaymentButton: Button = view.findViewById(R.id.startPaymentButton)
        startPaymentButton.setOnClickListener {
            activity?.supportFragmentManager?.beginTransaction()
                ?.replace(R.id.fragmentContainer, PreventFormFragment())  // Replace with PreventFormFragment
                ?.addToBackStack(null)
                ?.commit()
        }
    }
}

Break Fragment

This fragment shows a screen where the user can resume the session after a break.

class BreakFragment : Fragment(R.layout.fragment_break) {

    private lateinit var continueButton: Button

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        continueButton = view.findViewById(R.id.continueButton)

        continueButton.setOnClickListener {
            parentFragmentManager.beginTransaction()
                .replace(R.id.fragmentContainer, PreventFormFragment())  // Replace with PreventFormFragment
                .addToBackStack(null)  // Allows the user to go back to BreakFragment if needed
                .commit()
        }
    }
}

Result Fragment

This fragment displays the result of the SDK operation based on the session state. The text of the message in the xml layout is set according to the Prevent SDK result.

class ResultFragment : Fragment(R.layout.fragment_result) {

    private lateinit var resultMessage: TextView
    private lateinit var descriptionMessage: TextView
    private lateinit var returnHomeButton: Button

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        resultMessage = view.findViewById(R.id.resultMessage)
        descriptionMessage = view.findViewById(R.id.descriptionMessage)
        returnHomeButton = view.findViewById(R.id.returnHomeButton)

        val sessionState = PaymentContext.sessionState.value?.state

        when (sessionState) {
            ClosedSessionState.ERROR -> {
                resultMessage.text = "We had an issue adding the payee, please try again or contact our customer support at +44 1234 1234"
            }
            ClosedSessionState.RESOLVED -> {
                resultMessage.text = "Payee Added Successfully"
            }
            ClosedSessionState.FAILED -> {
                resultMessage.text = "We were unable to add the specified payee into your account. The recipient's account was unable to be verified at this time."
            }
            else -> {
                resultMessage.text = "Return to Home"
            }
        }

        returnHomeButton.setOnClickListener {
            PaymentContext.clearSessionState()  // Clear session state
            onBackToWelcome()
        }
    }

    private fun onBackToWelcome() {
        requireActivity().supportFragmentManager.beginTransaction()
            .replace(R.id.fragmentContainer, WelcomeFragment())  // Replace with Welcome Fragment
            .commit()
    }
}

---

Conclusion

The SDK supports both Jetpack Compose-based and traditional Activity/Fragment apps with XML views. The complete code for both Compose-based app and traditional Activity/Fragment xml view based app integrations can be found in our SDK.

The SDK is designed with clear entry and exit points and supports handling “breaks” where additional information may be required from the user. It is important to properly handle each session state and display the appropriate screen based on the session’s status (e.g., success, failure, error, etc.).

By following the examples and best practices in this documentation, you can seamlessly integrate the SDK into your app, ensuring smooth session management and payment processing across both Compose and traditional Android environments.