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.

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.

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

Obtain Your API Key

Contact your Hum representative to receive your API key if you haven’t already.

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

Load URL in WebView

Load the constructed URL in your application’s WebView component.

iOS (Swift)
Android (Kotlin)
React Native
Flutter

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)
}

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)

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}
    />
  );
}

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);
  }
}

URL Parameters

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

Required Parameters

string

required

Your Hum API key for authentication.Example: apiKey=your_api_key_here

Display & Layout Parameters

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: checkoutExample: resultLayout=summary

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 %23Default: 1274f9 (Hum blue)Examples:

primaryColor=1274f9
primaryColor=%23FF5733

boolean

Controls whether users can save and unsave internet plans for later comparison.Accepted Values: true or falseDefault: falseExample: showSavePlanButton=trueWhen enabled:

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

boolean

Controls whether the widget renders its own address entry form above the results.Accepted Values: true or falseDefault: falseExample: showAddressCompletionForm=trueWhen 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.

Address Parameters

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

string

Primary street address (street number and name).Example: street1=123%20Main%20St

When providing an address, street1 and zip are required. city and state are optional but recommended for improved address match quality.

string

Secondary address information (apartment, suite, unit number).Example: street2=Apt%20205

string

City name.Example: city=Detroit

string

Two-letter state code.Example: state=MI

string

ZIP code (5 or 9 digits).Example: zip=48226

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

Unit or apartment designators included in the single address string are parsed into street2 automatically.

When using the s parameter, do not include street1, city, state, or zip parameters. Use either s OR the individual fields, not both.

number

Latitude coordinate for the address (improves performance).Example: latitude=42.3317

Both latitude and longitude must be provided together.

number

Longitude coordinate for the address (improves performance).Example: longitude=-83.0479

Tracking & Analytics Parameters

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

Customer Data Parameters

Pre-populate customer information to streamline the checkout process.

string

Customer’s first name.Example: firstName=Jane

string

Customer’s last name.Example: lastName=Smith

string

Customer’s email address (must be URL-encoded).Example: email=jane.smith%40example.com

string

Customer’s phone number.Example: phoneNumber=555-123-4567

Filtering Parameters

string

Comma-separated list of FCC provider IDs to restrict results to specific providers.Example: limitProviders=130077,130317

Use Get FCC Service Providers to retrieve provider IDs programmatically.

string

Comma-separated list of FCC provider IDs to feature prominently at the top of results.Example: primaryProviders=130077,130317

string

Comma-separated list of technology types to filter results.Accepted Values: Fiber, Cable, Wireless, Satellite, DSL, OtherExample: limitTechnologies=Fiber,Cable

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`

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

Platform-Specific Implementation

iOS Implementation

Configure WKWebView

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)
    }
}

Build and Load URL

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)
    }
}

URLComponents automatically handles URL encoding for you.

Android Implementation

Setup WebView in Layout

res/layout/activity_main.xml

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

Configure and Load WebView

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)
    }
}

React Native Implementation

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;

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

Configure your WebView to handle postMessage events to receive notifications from the Hum widget.

Best Practices

Enable JavaScript and DOM Storage

The Hum widget requires JavaScript and DOM storage to function properly. Ensure these are enabled in your WebView configuration.

// iOS
webView.configuration.preferences.javaScriptEnabled = true

// Android
webView.settings.javaScriptEnabled = true
webView.settings.domStorageEnabled = true

Handle Navigation Events

Consider restricting navigation to keep users within the Hum experience or handle external links appropriately.

// 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)
        }
    }
}

Implement Error Handling

Handle WebView errors gracefully to improve user experience.

// 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()
    }
}

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.

// 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
});

Troubleshooting

Widget doesn't load or appears blank

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

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

Next Steps

Widget Hook Notifications

Learn how to listen for and handle events from the Hum widget

JavaScript Widget Integration

Explore the full JavaScript widget integration for web applications

API Integration

Build custom integrations using the Hum API

Get Support

Contact our team for integration assistance

Get Started

Integration

WebView Integration

WebView Integration

Base URL

Quick Start

URL Parameters

Required Parameters

Display & Layout Parameters

Address Parameters

Tracking & Analytics Parameters

Customer Data Parameters

Filtering Parameters

Complete URL Examples

Example 1: Basic Integration

Example 2: With Pre-populated Address

Example 3: Full Address String

Example 4: Customized Layout and Branding

Example 5: Pre-populated Customer Data

Example 6: Filtered Providers and Technologies

Example 7: Complete Configuration

URL Encoding Reference

Platform-Specific Implementation

iOS Implementation

Android Implementation

React Native Implementation

Listening to Widget Events

Best Practices

Troubleshooting

Next Steps

Widget Hook Notifications

JavaScript Widget Integration

API Integration

Get Support

​WebView Integration

​Base URL

​Quick Start

​URL Parameters

​Required Parameters

​Display & Layout Parameters

​Address Parameters

​Tracking & Analytics Parameters

​Customer Data Parameters

​Filtering Parameters

​Complete URL Examples

​Example 1: Basic Integration

​Example 2: With Pre-populated Address

​Example 3: Full Address String

​Example 4: Customized Layout and Branding

​Example 5: Pre-populated Customer Data

​Example 6: Filtered Providers and Technologies

​Example 7: Complete Configuration

​URL Encoding Reference

​Platform-Specific Implementation

​iOS Implementation

​Android Implementation

​React Native Implementation

​Listening to Widget Events

​Best Practices

​Troubleshooting

​Next Steps

Widget Hook Notifications

JavaScript Widget Integration

API Integration

Get Support

WebView Integration

Base URL

Quick Start

URL Parameters

Required Parameters

Display & Layout Parameters

Address Parameters

Tracking & Analytics Parameters

Customer Data Parameters

Filtering Parameters

Complete URL Examples

Example 1: Basic Integration

Example 2: With Pre-populated Address

Example 3: Full Address String

Example 4: Customized Layout and Branding

Example 5: Pre-populated Customer Data

Example 6: Filtered Providers and Technologies

Example 7: Complete Configuration

URL Encoding Reference

Platform-Specific Implementation

iOS Implementation

Android Implementation

React Native Implementation

Listening to Widget Events

Best Practices

Troubleshooting

Next Steps