> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wearepion.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup

> This document outlines the technical steps for integrating a web view component within native Android or iOS mobile apps. This allows you to display a web page, specified by a URL, directly within your mobile app, providing a seamless, integrated user experience.

## **Android Application Integration**

Integrating a web view into an Android application involves adding a `WebView` component or utilizing `Chrome Custom Tabs` to load the desired URL.

### **Permissions**

Before you can load any web content, your `AndroidManifest.xml` file must include the `INTERNET` permission. Add the following line inside the `<manifest>` tag:

```text theme={null}
<uses-permission android:name="android.permission.INTERNET" />
```

### **Chrome Custom Tabs**

Chrome Custom Tabs provide a way for Android apps to open web links directly in a customized Chrome browser experience. This offers better performance and security than `WebView` for external links.

<Steps>
  <Step title="Add Dependency" titleSize="h4">
    First, add the Custom Tabs support library to your `build.gradle` (app-level) file:

    ```text theme={null}
    dependencies {
        implementation "androidx.browser:browser:1.4.0" // Use the latest version
    }
    ```
  </Step>

  <Step title="Launching a URL with Chrome Custom Tabs (Kotlin)" titleSize="h4">
    To open a URL using Chrome Custom Tabs:

    ```text theme={null}
    // In your Activity or Fragment
    import android.net.Uri
    import androidx.browser.customtabs.CustomTabsIntent
    import androidx.core.content.ContextCompat

    // ... inside a method, e.g., onClick listener
    fun openUrlInCustomTab(url: String) {
        val builder = CustomTabsIntent.Builder()

        // Optional: Customize the toolbar color
        builder.setToolbarColor(ContextCompat.getColor(this, R.color.colorPrimary))

        // Optional: Add a custom close button (e.g., from your drawables)
        // builder.setCloseButtonIcon(BitmapFactory.decodeResource(resources, R.drawable.ic_arrow_back))

        // Optional: Enable the share action button
        builder.setShowShareButton(true)

        // Build the CustomTabsIntent
        val customTabsIntent = builder.build()

        // Launch the URL
        customTabsIntent.launchUrl(this, Uri.parse(url))
    }

    // Example usage:
    // openUrlInCustomTab("https://www.example.com")
    ```
  </Step>
</Steps>

### **WebView**

<Steps>
  <Step title="Adding the WebView to Layout" titleSize="h4">
    You can add a `WebView` to your activity's layout XML file (e.g., `activity_main.xml`).

    ```text theme={null}
    <!-- activity_main.xml -->
    <RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        tools:context=".MainActivity">

        <WebView
            android:id="@+id/webView"
            android:layout_width="match_parent"
            android:layout_height="match_parent" />

    </RelativeLayout>
    ```
  </Step>

  <Step title="Loading a URL in the Activity (Kotlin)" titleSize="h4">
    In your activity's Kotlin code, you will find the `WebView` by its ID and then load the URL.

    ```text theme={null}
    // MainActivity.kt
    package com.example.mywebviewapp

    import android.os.Bundle
    import android.webkit.WebView
    import android.webkit.WebViewClient
    import androidx.appcompat.app.AppCompatActivity

    class MainActivity : AppCompatActivity() {

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

            val webView: WebView = findViewById(R.id.webView)

            // Configure WebView settings (optional but recommended)
            webView.settings.javaScriptEnabled = true // Enable JavaScript
            webView.settings.domStorageEnabled = true // Enable DOM storage

            // Set a WebViewClient to handle page navigation within the WebView itself
            webView.webViewClient = object : WebViewClient() {
                // This method is called when a new URL is about to be loaded in the WebView.
                // Returning true means the WebView will handle the URL, false means the system will.
                override fun shouldOverrideUrlLoading(view: WebView?, url: String?): Boolean {
                    view?.loadUrl(url!!)
                    return true
                }
            }

            // Load the specified URL
            val urlToLoad = "https://www.example.com" // Replace with your supplied URL
            webView.loadUrl(urlToLoad)
        }

        // Handle back button presses to navigate within the WebView history
        override fun onBackPressed() {
            val webView: WebView = findViewById(R.id.webView)
            if (webView.canGoBack()) {
                webView.goBack()
            } else {
                super.onBackPressed()
            }
        }
    }
    ```
  </Step>
</Steps>

### **Important Considerations for Android**

* `WebViewClient` (for WebView): Always set a `WebViewClient` to keep navigation within your `WebView`. Without it, Android might open external links in the device's default browser, which we don’t want. We want to keep the user within your mobile app.
* `WebChromeClient` (for WebView): For handling JavaScript alerts, prompts, console messages, and progress updates, you should also set a `WebChromeClient`.
* JavaScript `alert()` (for WebView): `WebView` does not natively handle `alert()` calls from JavaScript in a user-friendly way. If your web content uses `alert()`, you'll need to override `onJsAlert` in `WebChromeClient` to display a custom dialog.
* Security: Be cautious when loading untrusted content in `WebView`. Sanitize URLs and restrict permissions where possible. `Chrome Custom Tabs` offer enhanced security as they run in a separate process and leverage the browser's security model.
* Hardware Acceleration (for WebView): `WebView` generally benefits from hardware acceleration, which is enabled by default for apps targeting Android 3.0 (API level 11) and higher.
* Fallback for Custom Tabs: Always consider a fallback for devices where Chrome or a Custom Tabs-supporting browser is not installed. You might open a `WebView` or the default browser as an alternative.

***

## **iOS Application Integration**

In iOS, you use `SFSafariViewController`(introduced in iOS 9) for a Safari-like browsing experience.

<Warning>
  Do not use `WKWebView` as it is unsupported for this product.
</Warning>

### **SFSafariViewController**

`SFSafariViewController` provides a secure and performant way to display web content within your app, leveraging Safari's features like AutoFill, Reading List, and Shared Cookies. It's ideal for presenting external web content.

<Steps>
  <Step title="Import SafariServices" titleSize="h4">
    First, import the `SafariServices` framework into your ViewController.

    ```text theme={null}
    // ViewController.swift
    import UIKit
    import SafariServices
    ```
  </Step>

  <Step title="Presenting a URL with SFSafariViewController (Swift)" titleSize="h4">
    To present a URL using `SFSafariViewController`:

    ```text theme={null}
    import UIKit
    import SafariServices

    class ViewController: UIViewController {
        func didTapButton() {
            guard let url = URL(string: "http://www.example.com") else {
                return
            }

            open(url: url)
        }

        private func open(url: URL) {
            let safariVC = SFSafariViewController(url: url)

            // Optional: Customize the tint color
            safariVC.preferredControlTintColor = .blue
            safariVC.preferredBarTintColor = .lightGray

            // Present the SFSafariViewController
            present(safariVC, animated: true, completion: nil)
        }
    }
    ```
  </Step>
</Steps>

### **Important Considerations for iOS**

* `SFSafariViewController` Benefits: Offers shared cookie storage with Safari, better performance, and access to Safari's features. It's managed by the system, providing a consistent experience.
* `SFSafariViewController` Limitations: Customization options are limited by design to maintain user trust and consistency with Safari. It is not intended for displaying your *own* app's web content but rather for opening external links.