​
Adding Hum to Your Website

The Hum widget provides a seamless way to integrate internet service provider discovery into your website. With just a few lines of code, you can add a fully functional internet service search interface to your site.

​
Overview

The Hum widget is a JavaScript component that can be embedded into any web page. It provides a seamless interface for users to:

  • Check internet service availability at their address
  • View available plans and pricing
  • Order internet service directly through the widget

​
Installation

​
1. Add the Widget Container

First, add a container div with a specific ID where the widget will be rendered:

<div id="hum-widget"></div>

​
2. Add the Widget Script

Add the Hum widget script to your HTML page:

<script src="https://cdn.letshum.com/widget.js"></script>

​
3. Initialize the Widget

After adding the script, you’ll need to initialize the Hum widget instance inside a script tag with your API key and container element:

const hum = new HUM(
    'YOUR_API_KEY_HERE',
    document.getElementById('hum-widget')
);
hum.initialize();

// Store the instance globally for access by other page components
window.humInstance = hum;

​
Widget Layout Options

The Hum widget supports two different layout modes that can be configured during initialization:

​
Card Layout

The card layout provides a more engaging, user-friendly interface. This is ideal for:

  • Consumer-facing applications
  • Websites focused on user experience
  • Applications where visual appeal is important

​
Summary Layout

The summary layout presents available internet service options in a clean, tabular format. This is ideal for:

  • Quick comparison of plans and pricing
  • Displaying multiple providers in a compact space
  • Technical or business-focused applications

To specify the layout mode, pass a configuration object during initialization:

const hum = new HUM(
    'YOUR_API_KEY_HERE',
    document.getElementById('hum-widget'),
    {
        resultLayout: 'cards' // or 'summary'
    }
);
hum.initialize();

If no layout is specified, the widget will default to the card layout.

​
Address Data Format

The widget expects address data in a specific JSON format. Here’s the structure with explanations for each field:

{
  "street1": "1001 Woodward Ave",        // Primary street address
  "street2": "Suite 500",                // Optional secondary address (apartment, suite, etc.)
  "city": "Detroit",                     // City name
  "state": "MI",                         // Two-letter state code
  "zip": "48226",                        // ZIP code
  "campaign_id": "Optional Campaign ID"  // Optional tracking identifier
}

​
Field Descriptions

  • street1: The primary street address. This is required and should contain the street number and name.
  • street2: Optional secondary address information. Use this for apartment numbers, suite numbers, or any additional address details.
  • city: The city name. Required field.
  • state: Two-letter state code (e.g., “MI” for Michigan). Required field.
  • zip: The ZIP code. Required field.
  • campaign_id: Optional identifier for tracking purposes. Can be used to associate the widget interaction with specific marketing campaigns or sources. This campaign_id will be embedded in the UTM parameters sent to the ISP and will be available in your Hum tracking.

​
Integration Examples

​
Example 1: Form-Based Integration

Here’s an example of how to integrate the widget with an HTML form if you have an address form on your website:

<!DOCTYPE html>
<html>
<head>
    <title>Hum Widget Demo</title>
    <script src="https://cdn.letshum.com/widget.js"></script>
</head>
<body>
    <!-- Widget container -->
    <div id="hum-widget"></div>

    <!-- Example form for address input -->
    <form id="address-search">
        <input type="text" name="street1" placeholder="Street Address" required>
        <input type="text" name="street2" placeholder="Apartment/Suite (Optional)">
        <input type="text" name="city" placeholder="City" required>
        <input type="text" name="state" placeholder="State (2 letters)" required>
        <input type="text" name="zip" placeholder="ZIP Code" required>
        <input type="hidden" name="campaign_id" value="your-campaign-id">
        <button type="submit">Check Availability</button>
    </form>

    <script>
        // Initialize Hum widget with API key and container
        const hum = new HUM(
            'YOUR_API_KEY_HERE',
            document.getElementById('hum-widget')
        );
        hum.initialize();

        // Store the instance globally
        window.humInstance = hum;

        // Handle form submission
        document.getElementById('address-search').addEventListener('submit', async (event) => {
            event.preventDefault();
            
            try {
                // Get form data
                const formData = new FormData(event.target);
                const addressData = Object.fromEntries(formData.entries());
                
                // Remove empty optional fields
                if (!addressData.street2) delete addressData.street2;
                if (!addressData.campaign_id) delete addressData.campaign_id;

                // Initialize the widget with the address
                const sessionToken = await hum.internetServiceFromAddress(addressData);
                console.log('Widget initialized with session token:', sessionToken);
            } catch (error) {
                console.error('Error initializing widget:', error);
            }
        });
    </script>
</body>
</html>

​
Example 2: Direct JSON Bundle Integration

You can also pass the address data directly as a JSON bundle without using a form:

<!DOCTYPE html>
<html>
<head>
    <title>Hum Widget Demo</title>
    <script src="https://cdn.letshum.com/widget.js"></script>
</head>
<body>
    <!-- Widget container -->
    <div id="hum-widget"></div>

    <script>
        // Create a new instance of the HUM widget
        // Parameters:
        // 1. Your API key from Hum dashboard
        // 2. The DOM element where the widget will be rendered
        const hum = new HUM(
            'YOUR_API_KEY_HERE',
            document.getElementById('hum-widget')
        );
        
        // Store the widget instance in the global window object
        // This allows other scripts on the page to access and control the widget
        window.humInstance = hum;

        // Create an address object with all required fields
        // This is the format Hum expects for address data
        const addressData = {
            street1: "1001 Woodward Ave",    // Primary street address (required)
            street2: "Suite 500",            // Secondary address info (optional)
            city: "Detroit",                 // City name (required)
            state: "MI",                     // Two-letter state code (required)
            zip: "48226",                    // ZIP code (required)
            campaign_id: "summer-2024"       // Optional tracking identifier
        };

        // Chain of promises to handle the widget initialization and address submission
        hum.initialize()
          .then(() => {
            // After widget is initialized, submit the address to get internet service options
            // This will trigger the widget to display available providers and plans
            return hum.internetServiceFromAddress(addressData);
          })
          .catch(error => {
            // Error handling for any failures in initialization or address submission
            // console.error('Widget error:', error);
          });
    </script>
</body>
</html>

​
Address Validation

The widget uses the same address validation rules as the API:

  1. Required fields:

    • street1 (primary address)
    • city
    • state (2-letter code)
    • zip (5 or 9 digits)

  2. Optional fields:

    • street2 (unit/apartment)
    • campaign_id (tracking)

  3. Validation rules:

    • State must be a valid US state code
    • ZIP must be in 12345 or 12345-6789 format
    • Address must be geocodable
    • Address must be serviceable

​
Troubleshooting

If you encounter issues with the widget:

  1. Verify that the address data is properly formatted
  2. Check that the container div with ID ‘hum-widget’ exists on the page (or matches the ID you assign to the containing div)
  3. Verify that your API key is valid
  4. Check the browser console for error messages

​
Next Steps

For additional support, contact support@letshum.com.

Was this page helpful?