# Android integration scenarios

<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

Here are a couple of scenarios you might encounter when you integrate the sample Android app.

## Scenario 1: Embed custom website in web view

Embedded a customer's website in the Android web view. The site contains links that use the ZVA WebSDK, such as the example on [Zoom's website](https://zoom.us/).

You don't need to generate the full-page chat URL. However, in **Targeting**, you should check **Mobile**.

![](/img/zva-targeting.png)

## Scenario 2: Trigger web view from native button

Users can trigger native events in the Android app, such as choose a button to open the web view that displays the web chat window.

### Case 1: Close web chat view

When the user clicks the close button to end the web chat, the system:

-   Handles the callback event in the main web view activity.
-   Closes the current native web view window.
-   Initializes the main web view activity with the URL.

Here is an example in Kotlin.

```kotlin
val intent = Intent(this, MainKotlinActivity::class.java).apply {
    putExtra(MainKotlinActivity.ARG_URL, "YOUR URL")
}
startActivity(intent)
```

In the `handleExit` method, add message handling logic to close the current web view.

```kotlin
// JavaScript interface method to handle exit commands
@JavascriptInterface
fun handleExit() {
    Handler(Looper.getMainLooper()).post {
        finish()
    }
}
```

### Case 2: Pass native parameters to web chat

Users can choose the button to open a chat in a webview to bring some parameters into the web context.

Here is an example.

```kotlin
val intent = Intent(this, MainKotlinActivity::class.java).apply {
    putExtra(MainKotlinActivity.ARG_URL, "YOUR URL")
}
startActivity(intent)
```

Format the parameters you need to pass into the .js context in the injected JavaScript strings.

### Case 3: Open URL in the current web view (In-App)

An example of this case is when the web view opens another URL from within. Normally, when users choose a link in the web page, it opens the URL inside the web view.

The web view provides a callback `shouldOverrideUrlLoading`to handle the cases.

```kotlin
override fun shouldOverrideUrlLoading(view: WebView?, request: WebResourceRequest?): Boolean {
    super.shouldOverrideUrlLoading(view, request)
}
```

In the `shouldOverrideUrlLoading` callback, you can handle the navigation action within the current WebView.

After your logic code, such as opening the URL in the system's default browser, you can return `true` to block the default web view behavior.

Here is an example.

```kotlin
override fun shouldOverrideUrlLoading(view: WebView?, request: WebResourceRequest?): Boolean {
    val intent = Intent()
    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
    intent.setAction(Intent.ACTION_VIEW)
    intent.addCategory(Intent.CATEGORY_BROWSABLE)
    intent.setData(Uri.parse(request?.url.toString()))
    startActivity(intent)
    return true
}
```

### Case 4: Open URL in system browser

In the Android app, open the URL of the button of the chat window in the system browser.

When using DOM elements like `<a href="https://www.example.com" target="_blank">Open in New Tab</a>` to open a new URL, we recommend you enable the web view multi-window feature by setting `setSupportMultipleWindows`, and process the logic for different types of target attributes in separate callbacks.

#### `target="_self"`

```kotlin
override fun shouldOverrideUrlLoading(
    view: WebView?,
    request: WebResourceRequest?
): Boolean {
    // Here you handle the behavior for `target="_self"`
    return true
}
```

#### `target="_blank"`

```kotlin
override fun onCreateWindow(
    view: WebView?,
    isDialog: Boolean,
    isUserGesture: Boolean,
    resultMsg: Message): Boolean {

    val newWebView = WebView(this@MainKotlinActivity)
    val transport = resultMsg.obj as WebViewTransport
    transport.webView = newWebView
    resultMsg.sendToTarget()

    newWebView.webViewClient = object : WebViewClient() {
        override fun shouldOverrideUrlLoading(
            view: WebView,
            request: WebResourceRequest): Boolean {
                // Here you handle the behavior for `target="_blank"`
                return true
            }
    }

    // ...
}
```

When using `window.open()` in the JavaScript context, you can set `ARG_USE_JS_URL_HANDLERflag` to `true` to receive command events.

Here is the sample code implementation for this case.

```kotlin
val intent = Intent(this, MainKotlinActivity::class.java).apply {
    putExtra(MainKotlinActivity.ARG_URL, "Your URL")
    putExtra(MainKotlinActivity.ARG_OPEN_URL_IN_SYSTEM_BROWSER, true)
    putExtra(MainKotlinActivity.ARG_USE_JS_URL_HANDLER, true)
}
startActivity(intent)
```

In the `handleCommon` method, process the information passed from the web.

Here is an example.

```kotlin
// Inject JavaScript handler functions into the WebView when the URL is loaded
private fun injectJavaScriptFunction() {
    val js = """
        javascript: window.addEventListener('zoomCampaignSdk:ready', () => {
            if (window.zoomCampaignSdk) {
                window.zoomCampaignSdk.native = {
                    exitHandler: {
                        handle: function() {
                            $EXIT_HANDLER_NAME.handleExit();
                        }
                    },
                    commonHandler: {
                        handle: function(e) {
                            $COMMON_HANDLER_NAME.handleCommon(JSON.stringify(e));
                        }
                    }
                };
            }
        });
    """.trimIndent()

    binding.webView.loadUrl(js)
}

// JavaScript interface method to handle common commands
@JavascriptInterface
fun handleCommon(jsonString: String?) {
    jsonString?.let {
        val jsonObject = JSONObject(jsonString)
        val cmd = jsonObject.getString(ZMCCWebKitMessageCmdKey)
        if (cmd == ZMCCWebkitMessageCmdType_OpenURL) { //Handle OpenURL command
            val value = jsonObject.getString(ZMCCWebkitMessageValueKey)
            val uri = Uri.parse(value)

            //Customize your actions here to handle the URL as needed.
            if (mOpenURLInSystemBrowser) {
                // Case 1: open url in system browser
                openUriInNewBrowser(uri)
            } else {
                // Case 2: open url in new tab but same application, use CustomTabsIntent
                openUriInCustomTabs(uri)
            }
        }
    }
}
```

### Case 5: Open URL in SFSafariViewController (In-App)

Use the internal browser, such as `CustomTabs`, to open the ZVA Web SDK URL in the Android app.

```kotlin
val intent = Intent(this, MainKotlinActivity::class.java).apply {
    putExtra(MainKotlinActivity.ARG_URL, "Your URL")
    putExtra(MainKotlinActivity.ARG_OPEN_URL_IN_SYSTEM_BROWSER, false)
}
startActivity(intent)
```

If you prefer to use JavaScript events, you can set `ARG_USE_JS_URL_HANDLERflag` to `true` and set the `handleCommon` method to handle similar information passed from the web.

For an example, see [Case 4](#case-4-open-url-in-system-browser).

### Case 6: Dispatch support handoff event

Use JavaScript's handoff event to pass data from the web to the Android native app.

```kotlin
val intent = Intent(this, MainKotlinActivity::class.java).apply {
    putExtra(MainKotlinActivity.ARG_URL, "Your URL")
}
startActivity(intent)
```

Handle the handoff callback event in the `handleHandoff` method.

Here is an example.

```kotlin
// Inject handleHandoff function into the WebView when the URL is loaded
private fun injectHandoffFunction() {
    val js = """
        javascript: window.addEventListener('support_handoff', (e) => {
            $SUPPORT_HANDOFF_HANDLER_NAME.handleHandoff(JSON.stringify(e.detail));
        });
    """.trimIndent()

    binding.webView.loadUrl(js)
}

// JavaScript interface method to handle handoff commands
@JavascriptInterface
fun handleHandoff(events: String?) {
    //Customize your actions here to handle the JSON string as needed.
    runOnUiThread {
        AlertDialog.Builder(this)
            .setMessage(events)
            .setPositiveButton("OK", null)
            .show()
    }
}
```