Integrating HubBox using the Tag Script

Introduction

The HubBox Tag is a flexible JavaScript-based solution for adding HubBox's pickup point selection functionality directly into your website's checkout frontend. It's designed to be relatively easy to implement, especially on platforms where deep backend modifications are difficult or restricted.

How it Works:

A snippet of JavaScript (the "Tag") is added to your checkout page(s). This script contains a configuration object and typically loads a main HubBox "payload" script from our CDN. Together, they:

• Inject the necessary HubBox UI elements (like delivery choice buttons/toggles, the map widget modal).
• Handle user interactions (searching for locations, selecting a point).
• Communicate the chosen pickup point address back to your checkout form fields.

Initial Setup:

Typically, the HubBox Integrations team will prepare the initial Tag script tailored for your site, including identifying the necessary CSS selectors for injecting the UI and populating address fields. Your development team (or agency) is then responsible for adding this script to your website's checkout pages using the appropriate method for your platform (e.g., theme files, script managers, tag managers).

Tag vs. SDK:

The Tag offers a quicker, lower-code implementation focused on frontend integration. However, for highly customized checkout experiences, complex logic, or deeper backend integration needs, the HubBox Software Development Kit (SDK) provides greater flexibility and control.

How the HubBox Tag Works: Anatomy of the Script

The HubBox Tag typically consists of a few key parts working together in the browser:

1. Initialization Snippet: This is the main piece of code you add to your site. It usually defines a global window.HUBBOX object.
2. config Object: Nested within window.HUBBOX.payload, this JSON object contains all the settings, selectors, and customizations that control the Tag's behaviour and appearance on your specific site. This is the primary object you or the HubBox team will modify.
3. Payload Script: The initialization snippet often dynamically loads the core HubBox Tag functionality (the "payload") from a HubBox CDN URL (e.g., https://cdn.hub-box.com/tag-payload/x.y.z/tag-payload.iife.js). This payload reads the config object you defined and executes the necessary actions.
4. CSS Styles (Optional but Recommended): Custom CSS rules, often injected alongside the main script or defined within it, are used to style the HubBox UI elements to match your brand.

Example Structure (Illustrative)

// 1. Initialization Snippet defining window.HUBBOX
window.HUBBOX = {
  payload: {
    // 2. Config Object with site-specific settings
    config: {
      configId: 'your_unique_config_id',
      environment: 'production',
      mode: 'live',
      language: 'en',
      // ... Many other configuration options ...
      launchExperience: { /* ... */ },
      addressFields: { /* ... */ },
      callbacks: { /* ... */ },
      translations: { /* ... */ }
    }
  }
};

// Optional: 3. Inline CSS Styling Block
var styles = `
  /* Your custom CSS rules here */
  :root { --button-color: #FF0000; }
  hubbox-local-pickup-toggles::part(title) { font-weight: bold; }
`;
var styleSheet = document.createElement("style");
styleSheet.innerText = styles;
document.head.appendChild(styleSheet);

// 4. Loading the main Payload Script from CDN
setTimeout(function () {
  var script = document.createElement('script');
  script.type = 'text/javascript';
  script.async = true;
  // The version (e.g., 6.2.1) might change
  script.src = '[https://cdn.hub-box.com/tag-payload/6.2.1/tag-payload.iife.js](https://cdn.hub-box.com/tag-payload/6.2.1/tag-payload.iife.js)';
  document.getElementsByTagName('head')[0].appendChild(script);
});

Initial Setup Process

1. HubBox Prepares Script: The HubBox Integrations team analyzes your checkout page structure and prepares the initial Tag script, focusing on the essential configuration (configId, launchExperience.injection, addressFields.selectors).
2. Retailer Deploys Script: You (or your developer/agency) receive the prepared script and add it to your checkout page(s) using the method appropriate for your platform:
   • BigCommerce: Use Script Manager.
   • WooCommerce: Use a Code Snippet Plugin or Child Theme functions.php.
   • Other Platforms (or Restricted Checkouts): Potentially use Google Tag Manager (with caveats).
   • Custom Platforms: Add directly to your checkout template files.
   • Ensure the script is loaded on the checkout page where shipping options are presented/selected. Loading in the footer is often recommended.
3. Testing: Thoroughly test the implementation using the Tag's test mode (see Testing section below).
4. Styling & Customization: HubBox team often assists with initial styling. Further customizations can be made by editing the CSS or the config object (see relevant sections below).
5. Go Live: Once testing is complete, switch the Tag to live mode.

Understanding the config Object: Core of Customization

The config object within the window.HUBBOX.payload is where you control most of the Tag's behaviour. While HubBox sets this up initially, understanding its structure is key for troubleshooting and customization.

Here's a breakdown of common top-level properties:

Property	Type	Description
configId	String	Identifies your specific HubBox configuration (e.g., yourstore). Determines which networks, base styles, and widget settings are loaded. Provided by HubBox.
environment	String	Set to "sandbox" for testing against test environments or "production" for the live environment.
mode	String	Controls visibility. "test" requires a URL parameter (?hubboxPayloadTest=true) to show HubBox; "live" shows HubBox to all users.
language	String	Sets the primary language for the UI elements (e.g., "en", "en-GB", "en-US", "fr", "de"). Affects default text and potentially number/date formatting.
logLevel	String	Controls the level of detail logged to the browser's console for debugging. Options: "DEBUG", "INFO", "WARN", "ERROR", "OFF" (Default is often "DEBUG" during setup, can be changed to "ERROR" or "WARN" in production).
launchExperience	Object	Defines how the HubBox choice (Pickup vs. Home) is presented. (See below).
addressFields	Object	Maps HubBox data to your checkout's address form fields. (See below).
carrierSpecificDataInjection	Object	Configures how carrier-specific codes (like DPD "S2S" or UPS ".D2R.") are added to address fields. (See below).
shippingMethods	Object	Configures shipping rate filtering. (See Advanced Configuration section).
callbacks	Object	Allows you to execute custom JavaScript at specific points in the Tag's lifecycle. (See Advanced Configuration section).
translations	Object	Allows overriding default UI text. (See Customizing Text section).

Other specific configurations like shippingAsBilling, saveAddress, urlRegex, otherElements may also be used - see examples and Advanced Options section.

Configuring Core Behaviour

These config sections are fundamental to making the Tag work correctly on your specific checkout page. HubBox configures these initially based on your site analysis.

launchExperience

Defines how the initial choice between Home Delivery and Local Pickup is presented.

config: {
  // ... other config ...
  launchExperience: {
    design: 'toggles', // Common design: 'toggles', 'multi-button', 'stacked', 'switch', 'tab' (Visual style)
    injection: {
      // Where to insert the launch UI elements in the HTML DOM
      reference: '#checkout-shipping-options', // CSS Selector of an existing element on your page
      positioning: 'beforebegin', // Where to insert relative to the reference:
                                 // 'beforebegin': Before the element itself
                                 // 'afterbegin': Just inside the element, before its first child
                                 // 'beforeend': Just inside the element, after its last child
                                 // 'afterend': After the element itself
    },
    swapComponents: false, // Optional: Set to true to swap the visual order of Home vs Pickup options
  },
  // ... other config ...
}

design

Controls the visual appearance of the choice (e.g., radio-style toggles, larger buttons). Examples include toggles and multi-button.

injection

This is critical. It tells the Tag where to physically add the Home/Pickup choice elements onto your checkout page.

• reference: A CSS selector targeting a stable existing element on your checkout page (e.g., a specific div, fieldset).
• positioning: How to insert relative to the reference element.

addressFields

Maps the selected pickup point's address details to your checkout form's input fields. The interactionPreventionAction property determines the action to perform on the selected element(s) when pickup is active ("hide", "lock", "hide parent", etc.) so that the user cannot manually modify the shipping address once these fields are populated with the address of the selected Pickup Point location.

config: {
  // ... other config ...
  addressFields: {
    selectors: {
      // Map HubBox address parts to the CSS selectors of your form fields
      // Available HubBox parts: company, address1, address2, city, county, postcode, country
      company: "#shipping-company-field", // Selector for Company Name field
      address1: "#shipping-address1-field", // Selector for Address Line 1
      address2: "#shipping-address2-field", // Selector for Address Line 2
      city: "input[name='shipping_city']",   // Selector for City field
      county: "#shipping-state-selector",   // Selector for State/County/Province field
      postcode: "#shipping-postcode-input", // Selector for Postcode/Zip field
      country: "#shipping-country-select" // Selector for Country field (often needs ISO code)
      // 'other': Can sometimes be used for unmapped parts, check with HubBox
    },
    // What to do with the address fields when pickup is selected:
    interactionPreventionAction: "lock", // Options:
                                        // 'lock': Disable the fields (read-only)
                                        // 'hide': Hide the fields individually
                                        // 'hide parent': Hide the parent container of each field
                                        // 'hide .{selector}': Hide elements matching a specified selector
                                        // Can combine with | : "lock | hide .form-group"
  },
  // ... other config ...
}

selectors

This mapping is essential. Each key (e.g., address1) must contain the correct CSS selector for the corresponding input/select field in your checkout form. HubBox uses these selectors to populate the form when a pickup point is chosen.

interactionPreventionAction

Defines what happens to the mapped address fields after a pickup point is selected, preventing the customer from manually overriding the pickup address. lock (disabling) is common.

carrierSpecificDataInjection

Handles how carrier-specific codes required for manifesting (like DPD's S2S..., DHL's DHL... or UPS's .D2R...) are inserted into the address fields.

config: {
  // ... other config ...
  carrierSpecificDataInjection: {
    dpd: { // Carrier key (lowercase)
      action: 'set', // Usually 'set'
      destination: 'address2' // Which address field (from addressFields.selectors) receives the code
    },
    ups: { // Carrier key
      action: 'set',
      destination: 'address2' // Or 'address1', 'company' etc. depending on best fit
    }
    // Add entries for other carriers if needed
  },
  // ... other config ...
}

HubBox configures this based on the network(s) used and your checkout form structure, ensuring codes needed for manifesting are placed correctly.

widget and pickupConfirmation Configuration

For advanced control, you can sometimes override the default design or injection point specifically for the map widget modal or the confirmation display block, although this is less common for standard Tag implementations.

config: {
  // ... other config ...
  widget: { // Controls the map/list modal
    // design: 'modal', // Currently only 'modal' is typical for Tag
    injection: { // Advanced: Override where the modal container is injected
      // reference: 'body',
      // positioning: 'beforeend'
    }
  },
  pickupConfirmation: { // Controls the display block shown after selection
    design: 'modern', // e.g., 'modern', 'blank', 'legacy'
    injection: { // Where to place the confirmation block
      // reference: '#shipping-summary',
      // positioning: 'afterbegin'
    }
  },
  // ... other config ...
}

Customizing Appearance (Styling)

You can tailor the visual appearance of the HubBox Tag elements (buttons, modal widget, confirmation display) using CSS.

Injecting CSS

The most common method is to include a block of CSS within your Tag script itself, or load a separate CSS file alongside it.

// Example of injecting CSS within the Tag script
// language=CSS
var styles = `
  /* Define CSS Variables for easier theming */
  :root {
    --hb-primary-color: #0056A0; /* Example: Set primary color */
    --hb-button-color: #0056A0;
    --hb-button-text-color: #FFFFFF;
    --hb-border-radius: 4px;
    --hb-font-family: inherit; /* Inherit font from your site */
  }

  /* Style specific parts of HubBox web components */
  hubbox-local-pickup-toggles::part(title) {
    font-weight: bold;
    color: var(--hb-primary-color);
  }

  hubbox-modal::part(header) {
    background-color: var(--hb-primary-color);
    color: white;
  }
`;

var styleSheet = document.createElement("style");
styleSheet.innerText = styles;
// Append to <head> to apply styles
document.head.appendChild(styleSheet);

CSS Shadow Parts (::part())

HubBox UI elements are built using Web Components. To style elements inside these components (which are normally encapsulated in a "shadow DOM"), you use the ::part() pseudo-element. You target the component's tag name (e.g., hubbox-local-pickup-toggles) followed by ::part(part-name).

Finding Part Names

You'll need to know the specific part names exposed by each component. These are often found in HubBox's component documentation or by inspecting the element's HTML structure in browser developer tools (look for the part="..." attribute).

Example: hubbox-local-pickup-toggles::part(title) { color: blue; } styles the title text within that specific component.

Changing Icons

Icons within components can often be changed using the content: url(...) CSS property on the relevant ::part(). HubBox provides URLs for common icons (see internal notes). You can use these or host your own. Color can sometimes be adjusted using CSS filter properties (see internal notes for generator link).

/* Example changing the icon in a specific button component */
hubbox-local-pickup-multi-button::part(icon) {
  content: url([https://cdn.hub-box.com/assets/icons/store.svg](https://cdn.hub-box.com/assets/icons/store.svg));
}
/* Example changing an icon color to white using filter */
hubbox-local-pickup-toggles::part(icon) {
  filter: invert(100%) sepia(0%) saturate(2%) hue-rotate(107deg) brightness(111%) contrast(101%);
}

Layout Adjustments

Use standard CSS (like CSS Grid or Flexbox) targeting the HubBox component tags or their container parts (::part(container)) to adjust layout (e.g., side-by-side vs. stacked, width). See internal notes for CSS Grid examples.

For detailed part names, available CSS variables, and more styling examples, please refer to theHubBox Components Documentation or the style examples provided by your HubBox Integrations Manager.

Customizing Text and Language (Translations)

You can change the default language and override specific text strings within the HubBox UI.

Setting Language

Use the config.language property (e.g., "en-GB", "fr-FR", "de-DE"). This sets the base locale.

Overriding Text

The primary method is using the config.translations object. Provide translations for the specific language code you set in config.language. You can override specific text keys provided by the components.

  config: {
      language: "en-GB", // Set desired language/locale
      // ... other config ...
      translations: {
          // Use the same language code as config.language
          "en-GB": {
              // Component Key (e.g., 'localPickup', 'homeDelivery', 'pickupConfirmation', 'modal')
              localPickup: {
                  // Text Key within the component
                  localPickup: "Collect from Store", // Override default title
                  select: {
                      selectedState: {
                          active: "(Chosen)", // Override "Selected" text
                          inactive: "Choose this",
                          neutral: "Choose this"
                      }
                  }
                  // ... other text keys for this component ...
              },
              homeDelivery: {
                  homeDelivery: "Ship to my Address",
                  // ... other text keys ...
              },
              pickupConfirmation: {
                    thankYou: "Thanks for choosing Click & Collect!",
                    // Use {network} placeholder which gets replaced by HubBox
                    orderWillBeSent: "Your order is heading to your chosen {network} point.",
                    // ... days of week, other text keys ...
              },
              modal: { // Text inside the map widget modal
                    headerLine1: "Find your nearest collection point",
                    // ... other text keys ...
              }
              // ... potentially add priceInfoItems arrays directly here too ...
              // localPickupPriceInfoItems: ["Usually Free!", "Ready in 24h"],
              // homeDeliveryPriceInfoItems: ["Standard: £3.99"]
          }
          // Add other language blocks if needed, e.g., "fr-FR": { ... }
      },
      // ... callbacks etc ...
  }

Finding Keys

Refer to the HubBox Components Documentation or examples provided by HubBox for the available component keys (like localPickup) and text keys (like localPickup, homeDelivery, thankYou) within each component.

Alternative (Callbacks)

While config.translations is preferred, text could potentially be set dynamically using the onWebComponentsCreated callback, accessing the component instances and setting their .translations property, as shown in some internal examples. This might be useful for highly dynamic text but is generally more complex.

Advanced Configuration & Dynamic Behaviour

The Tag offers powerful ways to control its behaviour using callbacks and specific configuration sections.

Using Callbacks

Callbacks allow you to execute your own custom JavaScript code at specific points during the Tag's execution lifecycle or in response to user actions. They are defined within the config.callbacks object.

Functions you define here are called by the HubBox Tag payload. They often receive a utils object (containing helper functions like utils.$ for DOM manipulation) and sometimes component instances.

Common Lifecycle Callbacks

• onCheckoutPageLoaded: Fires when the Tag first initializes on the checkout page.
• onWebComponentsCreated: Fires after the main HubBox UI Web Components (like toggles/buttons) have been created and added to the page. Useful for setting initial translations or styles on components.
• onLocalPickupSelected: Fires after the user selects the "Local Pickup" option but before the map widget typically opens.
• onHomeDeliverySelected: Fires after the user selects the "Home Delivery" option.
• onAddressFieldsPopulated: Fires after HubBox has populated the address fields with a selected pickup point's details.

Utility Functions (utils)

The utils object passed to some callbacks provides helpers:

• utils.$(selector): A convenience function similar to document.querySelector for finding elements.
• utils.$(selector).click(): Simulate a click.
• utils.$(selector).general.show() / hide(): Show or hide elements.
• utils.$(selector).input.checkbox.check() / uncheck(): Interact with checkboxes.

Use Cases

• Dynamically changing text/styles based on conditions.
• Interacting with other checkout elements (e.g., hiding/showing sections, clicking hidden buttons for SPAs, checking/unchecking "shipping same as billing").
• Implementing complex eligibility logic (getShouldBailOut).
• Handling specific edge cases or checkout flows (e.g., populating fields in popups).

config: {
    // ... other config ...
    callbacks: {
        // Example: Log when pickup is selected
        onLocalPickupSelected: (utils) => new Promise((resolve) => {
            console.log("Local Pickup Selected!");
            // Example: Maybe hide a specific home-delivery-only message
            // utils.<span class="math-inline">\('\.home\-delivery\-message'\)\.general\.hide\(\);
resolve\(\); // Important to resolve the promise
\}\),
// Example\: Log when home delivery is selected
onHomeDeliverySelected\: \(utils\) \=\> new Promise\(\(resolve\) \=\> \{
console\.log\("Home Delivery Selected\!"\);
// Example\: Maybe show a specific home\-delivery\-only message
// utils\.</span>('.home-delivery-message').general.show();
            resolve();
        }),

        // Example: Set translations when components are ready
        onWebComponentsCreated: ({ localPickup, homeDelivery /*, ...other components */ }) => new Promise((resolve) => {
            localPickup.translations = { "en": { localPickup: "Collect Here" } };
            homeDelivery.translations = { "en": { homeDelivery: "Deliver To Me" } };
            resolve();
        }),

        // Example: Bailout discussed below
        getShouldBailOut: () => new Promise(/* ... logic ... */)

    } // End callbacks
}

Product Eligibility Filtering (getShouldBailOut)

Dynamically hide the HubBox UI entirely if the cart contains ineligible items. Implement the callbacks.getShouldBailOut function within your config. This function must return a Promise that resolves to true to hide HubBox, or false to show it.

This feature Requires custom JavaScript within the function to:

1. Access cart contents (via global JS variables, data layer, AJAX calls to backend, or Storefront APIs).
2. Check items against your eligibility criteria (SKU list, category, attributes, dimensions, value).
3. Resolve the Promise with true or false.

More Info: See the dedicated Product Eligibility documentation for strategies. Consult platform-specific Tag guides (WooCommerce, BigCommerce) for examples of accessing cart data.

config: {
  // ... other config ...
  callbacks: {
    getShouldBailOut: () => new Promise(resolve => {
      // --- Your custom logic here ---
      // 1. Fetch/Access Cart Data
      // 2. Check items against rules (e.g., check SKUs, dimensions, tags)
      const shouldBailout = false; // Replace with your actual check result
      // 3. Resolve promise
      resolve(shouldBailout);
    }),
    // ... other callbacks ...
  }
} 

Shipping Rate Filtering (shippingMethods)

Dynamically hide specific shipping rate options based on whether Home Delivery or Local Pickup is selected. Essential if using the "Toggles" launch experience or complex multi-carrier rules.

Configuration

• wrapper: A CSS selector for the main container holding all shipping rate options.
• interactionPreventionAction: How to disable rates within the wrapper when pickup is selected (e.g., hide li hides list items).
• excludeOnLocalPickup: An array of rules defining which rates to hide when Local Pickup is active.
• excludeOnHomeDelivery: An array of rules defining which rates to hide when Home Delivery is active.
• Rules Object: Each rule object within the arrays contains:
  • selectors: An array of strings used to identify shipping methods that should be hidden.Use text-fragment: Your Rate Name as a simpler way to target based on visible text.
  • networks (Optional): Array of network keys (e.g., ["ups", "dpd"]) to apply this rule only when specific networks are active/selected.
  • mode (Optional): "first" (default) hides only the first element matching the selectors; "all" hides all matching elements.

More Info: See the dedicated Shipping Rate Filtering documentation.

Other Advanced Options

URL Regex: Select the page where the Tag script executes

This configuration controls on which specific pages the HubBox Tag script actively runs its core logic (like injecting the launch experience or populating address fields). It uses regular expressions to match the current browser URL. The Tag script checks the browser's current URL (window.location.href) against the RegEx patterns provided. If the URL matches the pattern, the Tag script will execute. Common RegEx patterns include words like checkout or order.

The RegEx patterns must accurately match the URL structure of your checkout pages. Incorrect patterns will prevent the Tag from loading where needed. ^.* matches the start of the URL and any characters, .*$ matches any characters and the end of the URL. Parentheses () group parts, and | means OR.

config: {
  // ... other config ...
  urlRegex: {
    // Matches any URL containing "checkout" or "cart"
    checkout: "^.*(checkout|cart).*$",
    // Matches any URL containing "order-confirmation" or "success"
    confirmation: "^.*(order-confirmation|success).*$" // Optional: Used by some advanced features/tracking
  },
  // ... other config ...
} 

Conditional Config: Change Widget based on URL

This technique allows you to use a single HubBox Tag script deployment across multiple websites (storefronts or domains) but apply slightly different configurations based on which site the user is currently visiting. This configuration is ideal for businesses managing several brands or regional sites (e.g., brand1.com, brand2.co.uk) from a shared codebase. You might want different networks enabled (configId), different styling, or slightly different selectors for each site.

To implement this, you use standard JavaScript conditional logic (like a ternary operator or if/else statements) when defining values within your config object. The script checks a condition (commonly window.location.hostname for the domain name) and assigns a config value accordingly. Below is an example of setting configId based on the domain:

config: {
  // ... other config properties ...

  // Set configId dynamically based on the website hostname
  configId: (window.location.hostname === "[www.brand-a.com](https://www.brand-a.com)" ? "brandA_prod_config" : "brandB_prod_config"),

  language: (window.location.hostname.endsWith(".fr") ? "fr-FR" : "en-GB"), // Example for language

  // ... other config properties ...
}

This code checks if the current website's hostname is exactly "www.brand-a.com".

• If true, it sets configId to "brandA_prod_config".
• If false, it sets configId to "brandB_prod_config".
• A similar check is shown for setting the language based on the domain suffix.
• You can apply this conditional logic to various properties within the config object as needed.

Modal Styling: Adjust modal appearance (e.g., remove header, fix positioning):

This configuration provides methods to customize the look of the HubBox map/list modal (the pop-up window for location selection) or troubleshoot display issues like overlapping elements or incorrect sizing/positioning.

Example: Removing the Modal Header

If you want a cleaner look without the modal's default title bar. This uses the onWebComponentsCreated callback to access the modalComponent instance after it's created and sets its noHeader property to true.

// Method: Set property via onWebComponentsCreated callback
config: {
    // ... other config ...
    callbacks: {
        onWebComponentsCreated: ({ modalComponent /*, ...others */ }) => new Promise(resolve => {
            if (modalComponent) {
                modalComponent.noHeader = true; // Set property to remove header
            }
            resolve();
        })
    }
}

Example: Constraining Modal Height (CSS)

To prevent the modal from becoming too tall and overflowing off-screen, especially on mobile or with long location lists. This CSS rule targets the main content panel part (panel) inside the hubbox-modal component. Setting max-height (e.g., to 95vh or 95% of the viewport height) prevents it from exceeding that height.

// Method: Add custom CSS via the 'styles' variable injection
// language=CSS
var styles = `
  hubbox-modal::part(panel) {
    /* Limit height to 95% of viewport height */
    max-height: 95vh;
    /* Optionally ensure vertical scrollbar appears if needed */
    overflow-y: auto;
  }
`;
// (Include the rest of the CSS injection code: document.createElement('style')...)

Example: Adjusting Modal Injection Point (Advanced Troubleshooting)

If the modal appears underneath other checkout elements due to complex z-index issues that CSS alone cannot easily fix. This advanced configuration tells the Tag to inject the modal's main HTML element directly into the <body> tag, rather than near the launch experience components. This can sometimes lift it above other elements in the stacking context but should be used cautiously as it changes the DOM structure. Consult HubBox support if considering this.

// Method: Configure modalInjection within the main config object
config: {
  // ... other config ...
  modalInjection: { // Note: Check if this specific config key is supported in your Tag version
    reference: "body",     // Inject directly into the <body> tag
    positioning: "append"  // Add as the last child of the body
  },
  // ... other config ...
}

Shipping Same as Billing: Manage interaction with "Shipping Same as Billing" checkboxes:

This configuration controls how the HubBox Tag interacts with your checkout's "Shipping address is the same as my billing address" checkbox. When a pickup point is selected, the shipping address is different from the customer's billing address, so this checkbox usually needs to be automatically unchecked and potentially hidden or disabled.

The interactionPreventionAction property determines the action to perform on the selected element(s) when pickup is active ("hide", "lock", "hide parent", etc.)

The invert property enables you to switch the behaviour if the checkbox is "Shipping address is different from my billing address". This property should be set as false if your checkbox label means "Shipping address is the SAME as billing" and set to true only if your label means "Billing address is DIFFERENT from shipping" - this ensures the Tag logic correctly unchecks (or checks, if inverted) the box when the addresses become different due to pickup selection.

config: {
  // ... other config ...
  shippingAsBilling: {
    // Required: CSS selector targeting the checkbox <input> element
    checkbox: "#shipping-same-as-billing-checkbox",

    // Required: Action when pickup is selected ('hide' or 'lock' recommended)
    interactionPreventionAction: "hide", // Or "lock", "hide parent"

    // Optional: Set true ONLY if your checkbox label means
    // "Billing is DIFFERENT from Shipping" (rare). Default is false.
    invert: false
  },
  // ... other config ...
}

Save Address: Stop the Tag from saving the shipping address to customer's account

This configuration manages the "Save this address for future use" checkbox commonly found on checkout forms. When a HubBox pickup point address is populated into the shipping fields, you typically want to prevent the customer from accidentally saving this non-residential pickup point address to their personal address book. The interactionPreventionAction property determines the action to perform on the selected element(s) when pickup is active ("hide", "lock", "hide parent", etc.)

config: {
  // ... other config ...
  saveAddress: {
    checkbox: '#save-shipping-address-checkbox-id', // CSS selector for the checkbox
    interactionPreventionAction: 'hide parent' // Hide the checkbox and its immediate container
  },
  // ... other config ...
}

Other Elements: a tool to hide or lock any other elements on the page

This configuration provides a flexible way to hide or lock miscellaneous elements on your checkout page specifically when the HubBox Local Pickup option is active (i.e., after the user selects 'Pickup' or confirms a pickup location). The configuration is an array ([]) of objects and each object defines a rule for elements to control. The interactionPreventionAction property determines the action to perform on the selected element(s) when pickup is active ("hide", "lock", "hide parent", etc.)

Use cases include:

• Hiding specific delivery instruction fields that only apply to home delivery.
• Disabling form sections irrelevant to pickup orders.
• Hiding promotional banners related only to home shipping.

config: {
  // ... other config ...
  otherElements: [
    {
      // Rule 1: Hide the 'Leave with neighbour' instructions field
      selector: '#delivery-instructions-neighbour',
      interactionPreventionAction: 'hide'
    },
    {
      // Rule 2: Hide the entire 'Special Delivery Options' fieldset
      selector: 'fieldset.special-delivery-options',
      interactionPreventionAction: 'hide'
    },
    {
      // Rule 3: Lock a 'Gift Wrap for Home Delivery' option
      selector: '#gift-wrap-home-option',
      interactionPreventionAction: 'lock'
    }
  ],
  // ... other config ...
}

Consult your HubBox Integrations Manager for more complex scenarios like handling popups, populating specific fields like phone numbers, or adding the Tag to multiple distinct checkout flows.

Testing the Tag Implementation

Rigorous testing is essential for a smooth launch.

1. Use Test Mode:
   • If you are testing on your production environment, set mode: "test" in your config object within the Tag script.
   • Access your checkout page and append ?hubboxPayloadTest=true to the URL.
   • Only you (with the parameter) will see HubBox; live customers won't.
2. Comprehensive Checks:
   • Visibility: Does the HubBox launch UI appear correctly where expected?
   • Functionality: Search for locations, select a point, confirm selection. Does the map/list work?
   • Address Population: CRITICAL - Does selecting a pickup point correctly populate the checkout's shipping address fields?
   • Filtering: If using eligibility or rate filtering, test various cart contents and delivery choices to ensure options hide/show correctly.
   • Console Errors: Check the browser's Developer Console (F12) for any JavaScript errors. Use config.logLevel: "DEBUG" during testing.
   • Cross-Browser/Device: Test thoroughly on Chrome, Firefox, Safari, Edge, and on desktop, tablet, and mobile views/devices.
   • User Flows: Test as both a guest and a logged-in customer. Test with different products and quantities.

You can use HubBox's UAT plans by visiting the Testing Documentation.

Troubleshooting Common Issues

HubBox UI Not Appearing

• Check config.launchExperience.injection selectors are correct and the reference element exists on the page before the Tag runs.
• Verify config.urlRegex.checkout matches your checkout page URL pattern.
• Check browser console for JavaScript errors (syntax errors in config, loading failures).
• Ensure the Tag script is actually being added to the page by your platform/method.
• Check for CORS/CSP issues blocking the CDN payload script. Whitelist https://cdn.hub-box.com.

Tag Conflicts / Broken Checkout

• Minification: If your site aggressively minifies JavaScript, it might break the already-minified HubBox payload. Exclude the HubBox Tag script/CDN URL from your site's minification process.
• JavaScript Errors: Look for errors in the console -- conflicts with other scripts or theme JS can occur.
• Selector Issues: Incorrect selectors in addressFields or shippingMethods can cause errors or unexpected behaviour. Double-check them carefully.

Styling Issues / Modal Problems

• Z-index: Other elements on your page might have a higher z-index, appearing over the HubBox modal. You may need custom CSS to increase the modal's z-index (e.g., hubbox-modal { z-index: 9999 !important; }).
• Modal Position/Size: If the modal appears off-screen or cut off, try adjusting its container styles (hubbox-modal::part(panel) { max-height: 95vh; }) or investigate the modalInjection config option (see internal notes - advanced).

Address Fields Not Populating/Locking

• Verify config.addressFields.selectors are precise and correct for your current checkout form HTML.
• Check the interactionPreventionAction setting.

Going Live

1. Complete thorough testing in test mode or in your staging environment.
2. Edit the HubBox Tag script.
3. Change mode: "live" in the config object or move Tag script to production environment.
4. Save and deploy/publish your changes.

Support

For assistance with configuring the Tag, troubleshooting, or understanding advanced features, please contact the HubBox Client Support or Integrations team at clientsuccess@hubbox.com. Provide specific details about your configuration, the issue observed, and relevant URLs or screenshots.