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>

Add the Hum widget script to your HTML page:

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

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;

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:

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

    <!-- Example form for address input -->
    <form id="wf-form-Contact-Form">
        <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('wf-form-Contact-Form').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://harmony.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')
        );
        
        // Initialize the widget to prepare it for use
        // This sets up the widget but doesn't yet show any content
        hum.initialize();

        // 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);
          })
          .then(sessionToken => {
            // Success callback - receives a session token that uniquely identifies this lookup
            // You can use this token for tracking or further API calls
            // console.log('Session token:', sessionToken);
          })
          .catch(error => {
            // Error handling for any failures in initialization or address submission
            // console.error('Widget error:', error);
          });
    </script>
</body>
</html>

Address Validation

The widget works best with validated addresses. You can use any address validation service (like SmartyStreets, Google Places API, etc.) to validate addresses before passing them to the widget.

Error Handling

The widget initialization can fail for several reasons:

Invalid address data
Network connectivity issues
API rate limiting
Invalid API credentials

Always wrap the widget initialization in a try-catch block to handle potential errors gracefully.

Styling and Customization

The widget is designed to be responsive and will adapt to its container’s dimensions. You can control the widget’s appearance by styling its container element:

#hum-widget {
    width: 100%;
    max-width: 800px;
    margin: 0 auto;
    padding: 20px;
}

Best Practices

Container Element: Always include a named container div with the correct ID
Address Validation: Always validate addresses before passing them to the widget
Error Handling: Implement proper error handling for widget initialization
Loading States: Show appropriate loading states while the widget initializes

Troubleshooting

If you encounter issues with the widget:

Check that the container div with ID ‘hum-widget’ exists on the page (or matches the ID you assign to the containing div)
Verify that your API key is valid
Check the browser console for error messages
Verify that the address data is properly formatted
Ensure the widget script is loading correctly
Check for any network connectivity issues

Next Steps

Check out our Demo Applications for an example of a Widget integration

For additional support, contact support@letshum.com.

Get Started

Widget Integration

Adding Hum to Your Website

Overview

Installation

1. Add the Widget Container

2. Add the Widget Script

3. Initialize the Widget

Address Data Format

Field Descriptions

Integration Examples

Example 1: Form-Based Integration

Example 2: Direct JSON Bundle Integration

Address Validation

Error Handling

Styling and Customization

Best Practices

Troubleshooting

Next Steps

Get Started

​Adding Hum to Your Website

​Overview

​Installation

​1. Add the Widget Container

​2. Add the Widget Script

​3. Initialize the Widget

​Address Data Format

​Field Descriptions

​Integration Examples

​Example 1: Form-Based Integration

​Example 2: Direct JSON Bundle Integration

​Address Validation

​Error Handling

​Styling and Customization

​Best Practices

​Troubleshooting

​Next Steps

Adding Hum to Your Website

Overview

Installation

1. Add the Widget Container

2. Add the Widget Script

3. Initialize the Widget

Address Data Format

Field Descriptions

Integration Examples

Example 1: Form-Based Integration

Example 2: Direct JSON Bundle Integration

Address Validation

Error Handling

Styling and Customization

Best Practices

Troubleshooting

Next Steps