PUDO INTEGRATION ANDROID

Arvato PUDO Widget Version 2.0.0

This documentation outlines how to integrate a web component into an Android mobile application using a WebView.

⚠️️ Important: Geolocation Limitation: Getting the user's current geolocation is only supported in web browsers and is not available in iOS or Android WebView integrations. If the web component relies on the user's current position, you will need to implement a native geolocation solution and pass the coordinates to the web component with the search attribute.

PREREQUISITES

Android application using Kotlin.
Internet access to load the web component bundle.
A valid CLIENT-ID and BASE-URL for the PUDO web service.

IMPLEMENTATION DETAILS

1. Create the PUDOWebView Component

In your Android project, create an Activity class that will host the WebView where your web component will be loaded.

package example.pudofinderandroid

import android.annotation.SuppressLint
import android.os.Bundle
import android.util.Log
import android.webkit.JavascriptInterface
import android.webkit.WebSettings
import android.webkit.WebView
import android.webkit.WebViewClient
import androidx.activity.ComponentActivity

class PUDOWebView : ComponentActivity() {
    @SuppressLint("SetJavaScriptEnabled")
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // HTML content for the page
        val htmlContent = """
            <!DOCTYPE html>
            <html lang="en">
            <head>
                <meta charset="UTF-8">
                <meta name="viewport" content="width=device-width, initial-scale=1.0">
                <title>PUDO Finder Android Example</title>
            </head>
            <body></body>
            </html>
        """

        val bundleSrc = "https://<CLIENT-ID>.pudo.cxc.arvato-scs.digital/bundle.js"
        val baseUrl = "https://<BASE-URL>"

        // WebView setup
        val webView = WebView(this).apply {
            settings.javaScriptEnabled = true
            settings.allowFileAccess = true
            settings.domStorageEnabled = true
            settings.cacheMode = WebSettings.LOAD_NO_CACHE

            // Load content and handle page load completion
            webViewClient = object : WebViewClient() {
                override fun onPageFinished(view: WebView?, url: String?) {
                    super.onPageFinished(view, url)
                    val script = """
                        var script = document.createElement('script');
                        script.src = '$bundleSrc';
                        script.onload = function() {
                            window.CXCPudo.open({
                                language: '<LANGUAGE>',
                                country: '<COUNTRY>',
                                ismobileapp: 'true',
                                onClose: () => {
                                    AndroidInterface.onClose();
                                },
                                onSelectPoint: (point) => {
                                    AndroidInterface.onPointReceived(JSON.stringify(point));
                                }
                            })
                        };
                        document.head.appendChild(script);
                    """
                    // Inject script to load the web component
                    evaluateJavascript(script, null)
                }
            }

            // Add JavaScript interface to communicate with the Android app
            addJavascriptInterface(WebAppInterface(this@WebViewActivity), "AndroidInterface")

            // Load HTML content with the provided base URL
            loadDataWithBaseURL(baseUrl, htmlContent, "text/html", "UTF-8", null)
        }

        // Set the WebView as the activity content
        setContentView(webView)
    }
}

2. Add JavaScript Interface

The WebAppInterface class allows the web component to communicate with the Android application. Methods annotated with @JavascriptInterface can be called from the web component's JavaScript code.

class WebAppInterface(private val activity: WebViewActivity) {

    // Callback for when the web component is closed
    @JavascriptInterface
    fun onClose() {
        Log.d("WebView", "Close Callback Triggered")
        activity.finish()
    }

    // Callback for when a point is selected in the web component
    @JavascriptInterface
    fun onPointReceived(point: String) {
        Log.d("WebView", "Point received: $point")
    }
}

3. Permissions

Ensure that the necessary permissions are granted for the app to use the WebView and load the content.

Internet permission: This allows the WebView to access external resources. File access: Ensure the WebView settings allow file access if required. In your AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />

KEY FEATURES

Dynamic JavaScript Injection: Loads the PUDO web component script dynamically into the WebView.
Native-to-Web Communication: Uses WebAppInterface to listen for JavaScript events (onClose and onSelectPoint).
Kotlin Integration: Can be used within any native Kotlin application.

USAGE IN KOTLIN VIEW

You can embed the PUDOWebView inside any Kotlin view as follows:

href="#__codelineno-3-1">class MainActivity : ComponentActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) enableEdgeToEdge() setContent { PudoFinderAndroidTheme { Scaffold(modifier = Modifier.fillMaxSize()) { innerPadding -> Box( modifier = modifier.fillMaxSize(), contentAlignment = Alignment.Center ) { Button(onClick = { context.startActivity(Intent(context, WebViewActivity::class.java)) }, modifier = Modifier.padding(16.dp)) { Text("Open PUDO Finder Android") } } } } } } }