Implementing HubBox via Google Tag Manager (GTM)

Introduction: Using GTM for HubBox Tag Implementation

This guide explains how to implement the HubBox pickup point selection functionality on your website using Google Tag Manager (GTM). For more information on HubBox's Tag, please visit the Tag documentation directly.

This approach is primarily intended for websites or ecommerce platforms where you do not have direct access to modify the checkout page code or add custom scripts directly through the platform's backend. GTM allows you to inject the necessary HubBox JavaScript ("Tag") onto the page indirectly.

How it Works

You will configure GTM to insert and execute the HubBox Tag script specifically on your checkout pages. When triggered correctly, this script will load the HubBox interface (e.g., the pickup point selection map/widget) allowing customers to choose a pickup location.

Prerequisites:

1. Active GTM Container: You must have a Google Tag Manager container correctly installed and firing on all relevant pages of your website, including your entire checkout process.
2. GTM Access: You need sufficient permissions within your GTM account to create tags and triggers and publish changes.
3. HubBox Tag Script: You need the specific HubBox JavaScript Tag snippet provided to you by the HubBox team (e.g., by your Integrations Manager).

Important Considerations & Caveats:

• Robustness: While GTM provides flexibility, injecting functional checkout modifications like HubBox via GTM can sometimes be less robust than direct platform integration. Potential issues include script timing conflicts, reliance on specific page structures that might change, or interference from other GTM tags. Direct integration (if possible on your platform) is generally preferred for stability.
• Timing: The timing of when the HubBox Tag fires is crucial. Firing too early might cause errors if the page isn't ready; firing too late might cause the HubBox UI to appear abruptly or "flicker."
• Testing is Crucial: Thorough testing across different browsers, devices, and user scenarios is essential to ensure a seamless experience when using GTM injection.

Step 1: Obtain Your HubBox Tag Script

Before starting in GTM, ensure you have the correct HubBox Tag script. This unique JavaScript snippet will be provided by HubBox (typically by your Integrations Manager).

This script contains the necessary code to initialize the HubBox service, display the pickup point selection interface within your checkout, and handle the selection process. Keep this script readily available for Step 3.

Step 2: Create the GTM Trigger (When/Where to Load HubBox)

The trigger tells GTM when and on which pages to execute the HubBox Tag script. The goal is usually to fire it on your checkout page(s) once the main page elements are loaded.

Using the "Window Loaded" Trigger (Common Method):

This trigger waits until the browser has finished loading the entire page content, including scripts and images. This often ensures the page elements HubBox needs to interact with are available.

1. Navigate to your GTM Workspace and click Triggers in the left menu.
2. Click the New button.
3. Give your trigger a descriptive name, e.g., HubBox - Trigger - Checkout Window Loaded.
4. Click the Trigger Configuration box and select the Window Loaded trigger type.
5. Under This trigger fires on, select the Some Window Loaded Events radio button.
6. Configure the condition to target your checkout page(s). A common approach is:
   • Select Page URL from the first dropdown.
   • Select contains (or matches RegEx, starts with, etc., depending on your URL structure) from the second dropdown.
   • Enter a unique part of your checkout page URL in the text box (e.g., checkout, /store/checkout, order/shipping). Inspect your website's checkout URLs carefully to find a reliable identifier.
7. Click Save.

Important Notes on Triggers:

• URL Matching: Be precise with your URL matching. If checkout appears elsewhere on your site where you don't want HubBox, you'll need a more specific condition (e.g., Page Path starts with /checkout/shipping).
• Single Page Applications (SPAs): If your checkout is an SPA where the URL doesn't fully reload between steps, the "Window Loaded" trigger might only fire once initially. You may need more advanced triggers like "History Change," "DOM Ready," or rely on "Custom Events" pushed to the data layer by your application when specific checkout steps load. Consult your developers or GTM resources if the Window Loaded trigger proves unreliable.
• Timing: While "Window Loaded" is often safest, if it feels too slow (HubBox appears late), you might experiment carefully with the "DOM Ready" trigger, but ensure all necessary elements exist on the page when the script runs.

Step 3: Create the GTM Tag (Injecting the HubBox Script)

The tag is the container within GTM that holds your HubBox JavaScript and links it to the trigger.

1. Click Tags in the left menu, then click the New button.
2. Give your tag a descriptive name, e.g., HubBox - Custom HTML - Load Widget.
3. Click the "Tag Configuration" box and choose the Custom HTML tag type.
4. Carefully paste the entire HubBox Tag script (provided to you by HubBox in Step 1) into the HTML text area. Ensure you copy and paste it exactly as provided.
5. Click the Triggering box below the HTML section.
6. Select the trigger you created in Step 2 (e.g., HubBox - Trigger - Checkout Window Loaded).
7. Click Save.

Step 4: Previewing, Testing, and Publishing

This is a critical step, especially when injecting scripts into a checkout via GTM.

1. Enable Preview Mode: In the top right of your GTM workspace, click the Preview button. Enter the URL of your website (usually the homepage) and click "Connect". A new browser tab/window connected to GTM Preview mode will open, and you should see the GTM debug panel at the bottom.
2. Navigate and Test:
   • Navigate through your website to the checkout page(s) where you configured the trigger to fire.
   • In the GTM debug panel, select the "Window Loaded" (or your chosen trigger event) on the left. Check if your HubBox tag (HubBox - Custom HTML - Load Widget) appears under the "Tags Fired" section.
   • Verify Functionality: Does the HubBox pickup selection UI appear correctly on the page? Does it appear without excessive delay or causing other page elements to jump ("flicker")?
   • Test Interactions: Go through the process of selecting a pickup point. Does it work smoothly? Does the shipping address update correctly upon selection (as described in "Expected Outcome" below)?
   • Check for Errors: Open your browser's Developer Console (usually F12 key). Look for any JavaScript errors, especially any originating from the HubBox Tag script or GTM itself.
   • Cross-Browser/Device Testing: Repeat the functional tests on major browsers (Chrome, Firefox, Safari, Edge) and different devices (desktop, tablet, mobile) using GTM's preview sharing feature or by publishing to a test environment if available.
   • Conflict Testing: Test with other potential checkout actions, different payment methods, guest vs. logged-in checkout, etc., to ensure no conflicts with other scripts or GTM tags.
3. Iterate if Needed: If the tag doesn't fire, double-check your trigger conditions against the actual page URL/events. If the HubBox UI doesn't work correctly or causes errors, double-check the script was pasted exactly and contact HubBox support. You may need to adjust trigger types or timing for complex sites.
4. Publish Changes: Only after you are fully satisfied with testing in Preview mode, go back to your GTM workspace, click the Submit button. Provide a descriptive name and description for your changes (e.g., "Added HubBox Tag for Click & Collect") and click Publish. The HubBox Tag will now be live for all users.

Expected Outcome

Once the HubBox Tag is correctly implemented via GTM and published:

• Customers visiting your checkout page(s) should see the HubBox pickup option presented within the checkout flow (the exact appearance depends on your HubBox configuration).
• Clicking the pickup option should allow customers to search for, view, and select an available pickup location via the HubBox map/list interface.
• Upon successful selection of a pickup location, the shipping address associated with the order should be automatically updated to reflect the address of the chosen pickup point.
• The customer can then complete the checkout process as normal with the pickup location set as the destination.

Troubleshooting & Support

• Tag Not Firing: Verify trigger conditions exactly match the page URL or event in GTM Preview mode. Ensure the GTM container is correctly installed on the checkout page.
• HubBox UI Not Appearing/Working: Check the browser's Developer Console for JavaScript errors. Ensure the HubBox Tag script was pasted correctly and completely. Verify you have the correct script from HubBox.
• Timing Issues/Flickering: Experiment cautiously with trigger timing (DOM Ready vs. Window Loaded) or investigate if other scripts are interfering. Advanced users might look into tag sequencing in GTM.

If you encounter persistent issues during setup or testing using GTM, please contact the HubBox Client Support team at clientsupport@hub-box.com for assistance, providing details about your GTM setup (tag, trigger configuration) and any errors observed.