​
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'),
    {
        resultLayout: 'cards', // or 'summary'
        campaignId: 'my_campaign_id' // Optional campaign identifier
    }
);
hum.initialize();

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

The campaignId parameter is optional and will be passed to the API and embedded in UTM parameters sent to the providers. This allows for tracking and attribution of widget interactions to specific marketing campaigns or sources.

​
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 and campaign ID, pass a configuration object during initialization:

const hum = new HUM(
    'YOUR_API_KEY_HERE',
    document.getElementById('hum-widget'),
    {
        resultLayout: 'cards', // or 'summary'
        campaignId: 'my_campaign_id' // Optional campaign identifier
    }
);
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

  • See the widget in action on our the Hum website at letshum.com

For additional support, contact support@letshum.com.