HKLongd Retailer Widget: Setup Guide

Set Up Your HKLongd Partner Widget

Thank you for partnering with HKLongd. This guide explains how to install, configure, and test the HKLongd - Local Buy & Ship Agent widget on your online store.

Use the complete code snippet provided in Section 3 below and contact us if you need help adapting it to your theme.

1. What the Widget Does

The floating widget gives overseas shoppers a seamless way to request local purchasing and international delivery assistance directly from HKLongd.

When an international shopper clicks the widget, HKLongd’s quote request portal opens in a new browser tab with your product page link automatically pre-populated into their quote request.

Shares the Product URL: Captures the current public product page address so our logistics team knows exactly which item to purchase for the customer.
Zero Operations for Merchants: Clicking the widget starts a quote request handled entirely by HKLongd. It does not modify your native checkout, reserve stock, or collect payment on your site.
100% Non-Intrusive & Secure: The snippet runs purely on client-side frontend code. It does not access your store database, admin API, customer accounts, or order history.

💡 Proactive Security Tip for Your Dev/IT Team:
We encourage your developers or security team to inspect the code or run it through an AI assistant (like ChatGPT, Claude, or Copilot). Prompt: "Our potential logistics partner, HKLongd.com, provided this frontend code. What does it do? Does it access our database or store data?" — They will confirm it is a clean, 100% safe frontend redirect helper.

2. Prepare Your Installation

Before adding the widget code to your live store, prepare your environment with these two steps:

Share with Your Developer: Send this guide and the supplied code snippet to your store’s web developer or IT team.
Test in a Draft or Staging Theme: Install and review the widget on an unpublished duplicate theme or staging environment first.

The widget is built with standard, lightweight HTML, CSS, and vanilla JavaScript. On platforms like Shopify, WooCommerce, or Magento, it installs directly into your global layout template—no app installations or server-side configuration required.

3. Add the Supplied Code

Follow these steps to place the widget on your site:

Copy the complete code block provided below.
Open your platform’s primary layout file (for example, layout/theme.liquid in Shopify, or footer.php in WordPress).
Paste the entire code block directly before the closing </body> tag at the very bottom of the file.
Save your template, preview a live product page, and test the widget.

⚠️ Critical Technical Requirement: Do not place this snippet inside an <iframe>, isolated app block, or plain text container. The script must execute in the main page context so it can accurately capture the public product URL (window.location.href) for the referral handoff.

4. Test the Shopper Journey

Perform these quick verification steps on your live or staging store:

Open a Product Page: Confirm the compact dark floating tab appears cleanly in the bottom corner of the screen.
Test the Portal Redirect: Click the widget. Confirm that a new tab opens pointing to HKLongd’s quote request portal.
Verify Auto-Populated Link: On the HKLongd portal, verify that Item 1’s Product Link field automatically fills with your exact product page URL.
Test Multi-Item Addition: Return to your store, navigate to a second product page, and click the widget again. Confirm that the HKLongd form opens and automatically populates the second link under Item 2 while preserving Item 1!
Test Private/Incognito Mode: Test in both a normal browser window and an Incognito / Private window to ensure local storage or browser caching does not block the URL handoff.
Check UI Overlaps: Verify that the floating tab does not block important UI elements such as live chat widgets, cookie consent banners, or mobile "Add to Cart" sticky bars.

5. URL Security & Data Privacy

When activated, the widget reads window.location.href to build the referral query parameter (source_url).

Install the widget only on public product pages and general site catalog pages.
Do not install the widget on customer account pages, cart pages, checkout flows, or post-purchase order status pages where personal customer data or sensitive tokens might exist in URL parameters.

6. Confirm Your Installation with HKLongd

Once installation and testing are complete, reply to your HKLongd account representative with the following details so we can verify the referral handoff from our end:

Your store name and main website domain.
A direct link to a public product page where the widget is installed.
Any custom positioning adjustments made (e.g., moved to bottom-left to avoid chat tools).

Troubleshooting & FAQs

The widget does not appear on the page.

Ensure the code was added before the closing </body> tag and that no CSS on your site sets #hklongd-floating-tab { display: none; }. Also check if ad-blockers or aggressive script minifiers stripped the snippet.

The widget appears, but clicking it does nothing.

Check your browser’s Developer Console (F12) for JavaScript errors. Ensure popup blockers are not preventing new browser tabs from opening.

The quote form opens, but the product link is blank.

Verify that your site URL is properly URL-encoded during redirect and that the snippet is running directly on your main domain rather than inside an embedded <iframe>.

The widget overlaps our Live Chat or "Back to Top" button.

You can easily adjust its position by modifying the CSS inside the <style> block (e.g., change right: 25px; to left: 25px; or adjust bottom: 25px; to bottom: 80px;).

Need Technical Support?

Our integration team is available to assist your web developers directly:

✉️ Email: info@hklongd.com
🌐 Portal: hklongd.com