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

# WebView Integration

> Learn how to integrate Hum into mobile applications using WebView with URL parameters

# WebView Integration

The Hum WebView integration provides a simplified way to embed the Hum widget experience into native mobile applications (iOS and Android) or any environment that supports WebViews. Instead of embedding JavaScript code, you simply load a URL with configuration parameters.

<Info>
  This integration method is ideal for mobile apps built with native frameworks (Swift, Kotlin) or hybrid frameworks (React Native, Flutter) that need a quick, no-code integration path.
</Info>

## Base URL

All WebView integrations use the following base URL:

```
https://webview.letshum.com
```

## Quick Start

The simplest WebView integration requires only your API key:

```
https://webview.letshum.com?apiKey=YOUR_API_KEY_HERE
```

<Steps>
  <Step title="Obtain Your API Key">
    Contact your Hum representative to receive your API key if you haven't already.
  </Step>

  <Step title="Construct Your WebView URL">
    Build your URL by appending configuration parameters as query strings to the base URL.

    ```
    https://webview.letshum.com?apiKey=YOUR_API_KEY&resultLayout=checkout&primaryColor=%231274f9
    ```
  </Step>

  <Step title="Load URL in WebView">
    Load the constructed URL in your application's WebView component.

    <Tabs>
      <Tab title="iOS (Swift)">
        ```swift theme={null}
        import WebKit

        let urlString = "https://webview.letshum.com?apiKey=YOUR_API_KEY&resultLayout=checkout"
        if let url = URL(string: urlString) {
            let request = URLRequest(url: url)
            webView.load(request)
        }
        ```
      </Tab>

      <Tab title="Android (Kotlin)">
        ```kotlin theme={null}
        val webView: WebView = findViewById(R.id.webview)
        webView.settings.javaScriptEnabled = true

        val url = "https://webview.letshum.com?apiKey=YOUR_API_KEY&resultLayout=checkout"
        webView.loadUrl(url)
        ```
      </Tab>

      <Tab title="React Native">
        ```javascript theme={null}
        import { WebView } from 'react-native-webview';

        function HumWebView() {
          const url = 'https://webview.letshum.com?apiKey=YOUR_API_KEY&resultLayout=checkout';
          
          return (
            <WebView
              source={{ uri: url }}
              javaScriptEnabled={true}
            />
          );
        }
        ```
      </Tab>

      <Tab title="Flutter">
        ```dart theme={null}
        import 'package:webview_flutter/webview_flutter.dart';

        class HumWebView extends StatelessWidget {
          final controller = WebViewController()
            ..setJavaScriptMode(JavaScriptMode.unrestricted)
            ..loadRequest(Uri.parse(
              'https://webview.letshum.com?apiKey=YOUR_API_KEY&resultLayout=checkout'
            ));

          @override
          Widget build(BuildContext context) {
            return WebViewWidget(controller: controller);
          }
        }
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

## URL Parameters

All configuration options are passed as URL query parameters. Parameters should be properly URL-encoded, especially for special characters.

### Required Parameters

<ParamField query="apiKey" type="string" required>
  Your Hum API key for authentication.

  **Example:** `apiKey=your_api_key_here`
</ParamField>

### Display & Layout Parameters

<ParamField query="resultLayout" type="string">
  Controls the visual presentation of internet service results.

  **Accepted Values:**

  * `summary` - Compact table format with affiliate links
  * `checkout` - Full e-commerce shopping cart experience (default)
  * `plans` - Card layout with affiliate links

  **Default:** `checkout`

  **Example:** `resultLayout=summary`
</ParamField>

<ParamField query="primaryColor" type="string">
  Customizes the primary color for buttons and UI elements. Must be a URL-encoded hex color code.

  **Format:** Hex color without the `#` symbol, or URL-encoded with `%23`

  **Default:** `1274f9` (Hum blue)

  **Examples:**

  * `primaryColor=1274f9`
  * `primaryColor=%23FF5733`
</ParamField>

<ParamField query="showSavePlanButton" type="boolean">
  Controls whether users can save and unsave internet plans for later comparison.

  **Accepted Values:** `true` or `false`

  **Default:** `false`

  **Example:** `showSavePlanButton=true`

  **When enabled:**

  * Save/unsave button appears on plan cards
  * Triggers `humPlanSaved` and `humPlanUnsaved` events
  * Allows users to bookmark plans for future reference
</ParamField>

<ParamField query="showAddressCompletionForm" type="boolean">
  Controls whether the widget renders its own address entry form above the results.

  **Accepted Values:** `true` or `false`

  **Default:** `false`

  **Example:** `showAddressCompletionForm=true`

  **When enabled:**

  * An address field with autocomplete appears above the results
  * Selecting a suggestion starts a new session and reloads results for that address
  * The visitor can look up a different address without the host app reloading the WebView

  Leave this off when your app already passes the address through the URL parameters below. Turn it on when you want the visitor to be able to enter or change the address inside the WebView.
</ParamField>

### Address Parameters

Pre-populate the address to show results immediately when the WebView loads.

<ParamField query="street1" type="string">
  Primary street address (street number and name).

  **Example:** `street1=123%20Main%20St`

  <Note>
    When providing an address, `street1` and `zip` are required. `city` and `state` are optional but recommended for improved address match quality.
  </Note>
</ParamField>

<ParamField query="street2" type="string">
  Secondary address information (apartment, suite, unit number).

  **Example:** `street2=Apt%20205`
</ParamField>

<ParamField query="city" type="string">
  City name.

  **Example:** `city=Detroit`
</ParamField>

<ParamField query="state" type="string">
  Two-letter state code.

  **Example:** `state=MI`
</ParamField>

<ParamField query="zip" type="string">
  ZIP code (5 or 9 digits).

  **Example:** `zip=48226`
</ParamField>

<ParamField query="s" type="string">
  Alternative to individual address fields - provide the complete address as a single string.

  **Example:** `s=123%20Main%20St%20Apt%204B%2C%20Detroit%2C%20MI%2048226`

  <Note>
    Unit or apartment designators included in the single address string are parsed into `street2` automatically.
  </Note>

  <Warning>
    When using the `s` parameter, do not include `street1`, `city`, `state`, or `zip` parameters. Use either `s` OR the individual fields, not both.
  </Warning>
</ParamField>

<ParamField query="latitude" type="number">
  Latitude coordinate for the address (improves performance).

  **Example:** `latitude=42.3317`

  <Note>
    Both `latitude` and `longitude` must be provided together.
  </Note>
</ParamField>

<ParamField query="longitude" type="number">
  Longitude coordinate for the address (improves performance).

  **Example:** `longitude=-83.0479`
</ParamField>

### Tracking & Analytics Parameters

<ParamField query="campaignId" type="string">
  Identifier for tracking attribution and analytics. Use this to associate sessions with marketing campaigns, traffic sources, or user segments.

  **Example:** `campaignId=mobile-app-Q4-2024`
</ParamField>

### Customer Data Parameters

Pre-populate customer information to streamline the checkout process.

<ParamField query="firstName" type="string">
  Customer's first name.

  **Example:** `firstName=Jane`
</ParamField>

<ParamField query="lastName" type="string">
  Customer's last name.

  **Example:** `lastName=Smith`
</ParamField>

<ParamField query="email" type="string">
  Customer's email address (must be URL-encoded).

  **Example:** `email=jane.smith%40example.com`
</ParamField>

<ParamField query="phoneNumber" type="string">
  Customer's phone number.

  **Example:** `phoneNumber=555-123-4567`
</ParamField>

### Filtering Parameters

<ParamField query="limitProviders" type="string">
  Comma-separated list of FCC provider IDs to restrict results to specific providers.

  **Example:** `limitProviders=130077,130317`

  <Info>
    Use [Get FCC Service Providers](/api-reference/informational/get-fcc-service-providers) to retrieve provider IDs programmatically.
  </Info>
</ParamField>

<ParamField query="primaryProviders" type="string">
  Comma-separated list of FCC provider IDs to feature prominently at the top of results.

  **Example:** `primaryProviders=130077,130317`
</ParamField>

<ParamField query="limitTechnologies" type="string">
  Comma-separated list of technology types to filter results.

  **Accepted Values:** `Fiber`, `Cable`, `Wireless`, `Satellite`, `DSL`, `Other`

  **Example:** `limitTechnologies=Fiber,Cable`
</ParamField>

## Complete URL Examples

### Example 1: Basic Integration

Minimal configuration with just the API key:

```
https://webview.letshum.com?apiKey=your_api_key_here
```

### Example 2: With Pre-populated Address

Show results for a specific address immediately:

```
https://webview.letshum.com?apiKey=your_api_key_here&street1=123%20Main%20St&city=Detroit&state=MI&zip=48226
```

### Example 3: Full Address String

Using the single address parameter:

```
https://webview.letshum.com?apiKey=your_api_key_here&s=123%20Main%20St%2C%20Detroit%2C%20MI%2048226
```

### Example 4: Customized Layout and Branding

Change the layout and primary color:

```
https://webview.letshum.com?apiKey=your_api_key_here&resultLayout=summary&primaryColor=%23FF5733
```

### Example 5: Pre-populated Customer Data

Streamline checkout with known customer information:

```
https://webview.letshum.com?apiKey=your_api_key_here&street1=123%20Main%20St&city=Detroit&state=MI&zip=48226&firstName=Jane&lastName=Smith&email=jane.smith%40example.com&phoneNumber=555-123-4567
```

### Example 6: Filtered Providers and Technologies

Show only fiber and cable from specific providers:

```
https://webview.letshum.com?apiKey=your_api_key_here&street1=123%20Main%20St&city=Detroit&state=MI&zip=48226&limitProviders=130077,130317&limitTechnologies=Fiber,Cable
```

### Example 7: Complete Configuration

All parameters combined:

```
https://webview.letshum.com?apiKey=your_api_key_here&resultLayout=checkout&primaryColor=%231274f9&street1=123%20Main%20St&city=Detroit&state=MI&zip=48226&latitude=42.3317&longitude=-83.0479&campaignId=mobile-app-Q4-2024&firstName=Jane&lastName=Smith&email=jane.smith%40example.com&phoneNumber=555-123-4567&limitProviders=130077,130317&primaryProviders=130077&limitTechnologies=Fiber,Cable
```

## URL Encoding Reference

When constructing URLs, ensure special characters are properly encoded:

| Character | Encoded Value | Example                                   |
| --------- | ------------- | ----------------------------------------- |
| Space     | `%20`         | `Main St` → `Main%20St`                   |
| `#`       | `%23`         | `#FF5733` → `%23FF5733`                   |
| `@`       | `%40`         | `user@example.com` → `user%40example.com` |
| `&`       | `%26`         | `AT&T` → `AT%26T`                         |
| `,`       | `%2C`         | `MI, 48226` → `MI%2C%2048226`             |

<Tip>
  Most programming languages provide built-in URL encoding functions. Use these instead of manually encoding characters to avoid errors.
</Tip>

## Platform-Specific Implementation

### iOS Implementation

<Steps>
  <Step title="Configure WKWebView">
    ```swift theme={null}
    import WebKit

    class HumWebViewController: UIViewController {
        var webView: WKWebView!
        
        override func viewDidLoad() {
            super.viewDidLoad()
            
            // Configure WebView
            let webConfiguration = WKWebViewConfiguration()
            webView = WKWebView(frame: view.bounds, configuration: webConfiguration)
            webView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
            view.addSubview(webView)
        }
    }
    ```
  </Step>

  <Step title="Build and Load URL">
    ```swift theme={null}
    func loadHumWebView() {
        var components = URLComponents(string: "https://webview.letshum.com")!
        
        components.queryItems = [
            URLQueryItem(name: "apiKey", value: "your_api_key_here"),
            URLQueryItem(name: "resultLayout", value: "checkout"),
            URLQueryItem(name: "street1", value: "123 Main St"),
            URLQueryItem(name: "city", value: "Detroit"),
            URLQueryItem(name: "state", value: "MI"),
            URLQueryItem(name: "zip", value: "48226")
        ]
        
        if let url = components.url {
            let request = URLRequest(url: url)
            webView.load(request)
        }
    }
    ```

    <Note>
      `URLComponents` automatically handles URL encoding for you.
    </Note>
  </Step>
</Steps>

### Android Implementation

<Steps>
  <Step title="Setup WebView in Layout">
    ```xml res/layout/activity_main.xml theme={null}
    <WebView
        android:id="@+id/hum_webview"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
    ```
  </Step>

  <Step title="Configure and Load WebView">
    ```kotlin theme={null}
    import android.webkit.WebView
    import android.webkit.WebSettings
    import java.net.URLEncoder

    class MainActivity : AppCompatActivity() {
        private lateinit var webView: WebView
        
        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            setContentView(R.layout.activity_main)
            
            webView = findViewById(R.id.hum_webview)
            setupWebView()
            loadHumWebView()
        }
        
        private fun setupWebView() {
            webView.settings.apply {
                javaScriptEnabled = true
                domStorageEnabled = true
                loadWithOverviewMode = true
                useWideViewPort = true
            }
        }
        
        private fun loadHumWebView() {
            val params = mapOf(
                "apiKey" to "your_api_key_here",
                "resultLayout" to "checkout",
                "street1" to "123 Main St",
                "city" to "Detroit",
                "state" to "MI",
                "zip" to "48226"
            )
            
            val queryString = params.entries.joinToString("&") { (key, value) ->
                "$key=${URLEncoder.encode(value, "UTF-8")}"
            }
            
            val url = "https://webview.letshum.com?$queryString"
            webView.loadUrl(url)
        }
    }
    ```
  </Step>
</Steps>

### React Native Implementation

```javascript theme={null}
import React from 'react';
import { WebView } from 'react-native-webview';
import { SafeAreaView, StyleSheet } from 'react-native';

function HumWebViewScreen() {
  const buildUrl = () => {
    const baseUrl = 'https://webview.letshum.com';
    const params = {
      apiKey: 'your_api_key_here',
      resultLayout: 'checkout',
      street1: '123 Main St',
      city: 'Detroit',
      state: 'MI',
      zip: '48226',
      firstName: 'Jane',
      lastName: 'Smith',
      email: 'jane.smith@example.com'
    };
    
    const queryString = Object.entries(params)
      .map(([key, value]) => `${key}=${encodeURIComponent(value)}`)
      .join('&');
    
    return `${baseUrl}?${queryString}`;
  };
  
  return (
    <SafeAreaView style={styles.container}>
      <WebView
        source={{ uri: buildUrl() }}
        javaScriptEnabled={true}
        domStorageEnabled={true}
      />
    </SafeAreaView>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
});

export default HumWebViewScreen;
```

## Listening to Widget Events

The WebView integration supports the same hook notifications as the standard widget integration. See the [Widget Hook Notifications](/widget-integration/hooks) page for detailed information on handling order completion, plan save, and plan unsave events.

<Tip>
  Configure your WebView to handle postMessage events to receive notifications from the Hum widget.
</Tip>

## Best Practices

<AccordionGroup>
  <Accordion title="Enable JavaScript and DOM Storage">
    The Hum widget requires JavaScript and DOM storage to function properly. Ensure these are enabled in your WebView configuration.

    ```swift theme={null}
    // iOS
    webView.configuration.preferences.javaScriptEnabled = true
    ```

    ```kotlin theme={null}
    // Android
    webView.settings.javaScriptEnabled = true
    webView.settings.domStorageEnabled = true
    ```
  </Accordion>

  <Accordion title="Handle Navigation Events">
    Consider restricting navigation to keep users within the Hum experience or handle external links appropriately.

    ```swift theme={null}
    // iOS
    func webView(_ webView: WKWebView, 
                 decidePolicyFor navigationAction: WKNavigationAction, 
                 decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
        if let url = navigationAction.request.url?.absoluteString {
            if url.contains("webview.letshum.com") {
                decisionHandler(.allow)
            } else {
                // Open external links in Safari
                UIApplication.shared.open(navigationAction.request.url!)
                decisionHandler(.cancel)
            }
        }
    }
    ```
  </Accordion>

  <Accordion title="Implement Error Handling">
    Handle WebView errors gracefully to improve user experience.

    ```kotlin theme={null}
    // Android
    webView.webViewClient = object : WebViewClient() {
        override fun onReceivedError(
            view: WebView?,
            request: WebResourceRequest?,
            error: WebResourceError?
        ) {
            // Show error message to user
            Toast.makeText(
                this@MainActivity,
                "Failed to load content. Please check your connection.",
                Toast.LENGTH_LONG
            ).show()
        }
    }
    ```
  </Accordion>

  <Accordion title="Pre-populate Data When Available">
    If your app already has user information or location data, pass it as URL parameters to reduce friction and improve conversion rates.

    ```javascript theme={null}
    // React Native example
    const getUserData = () => ({
      firstName: user.firstName,
      lastName: user.lastName,
      email: user.email,
      phoneNumber: user.phone
    });

    const getLocationData = () => ({
      street1: location.street,
      city: location.city,
      state: location.state,
      zip: location.zip
    });
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Widget doesn't load or appears blank">
    **Possible causes:**

    * JavaScript is disabled in WebView settings
    * DOM storage is disabled
    * Network connectivity issues
    * Invalid API key

    **Solutions:**

    * Verify JavaScript is enabled
    * Enable DOM storage
    * Check network connection
    * Validate your API key with Hum support
  </Accordion>

  <Accordion title="Address parameters not working">
    **Possible causes:**

    * Missing required address fields
    * Incorrect URL encoding
    * Using both `s` parameter and individual fields

    **Solutions:**

    * Ensure the required fields (`street1` and `zip`) are present
    * Include `city` and `state` when available to improve address match quality
    * Use proper URL encoding functions
    * Use either `s` OR individual fields, not both
  </Accordion>

  <Accordion title="Custom colors not applying">
    **Possible causes:**

    * Hex color not URL-encoded
    * Invalid hex color format

    **Solutions:**

    * Use `%23` for the `#` symbol: `primaryColor=%23FF5733`
    * Or omit the `#` entirely: `primaryColor=FF5733`
    * Verify the hex color is valid
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Widget Hook Notifications" icon="webhook" href="/widget-integration/hooks">
    Learn how to listen for and handle events from the Hum widget
  </Card>

  <Card title="JavaScript Widget Integration" icon="code" href="/widget-integration/javascript">
    Explore the full JavaScript widget integration for web applications
  </Card>

  <Card title="API Integration" icon="brackets-curly" href="/api-integration">
    Build custom integrations using the Hum API
  </Card>

  <Card title="Get Support" icon="life-ring" href="mailto:support@letshum.com">
    Contact our team for integration assistance
  </Card>
</CardGroup>