Integrate Hello with JavaScript

Learn how to do a custom Hello integration with JavaScript.

If your website uses an ecommerce platform that we don't have a pre-built plugin for, you can integrate Zonos Hello with JavaScript. This gives you the most flexibility in customizing what your shoppers see and how they interact with Hello.

This guide assumes that you have already created a Zonos account and are familiar with the basics of JavaScript/HTML. If you are not familiar with JavaScript/HTML, we recommend that you use one of our pre-built plugins instead or contact our Professional Services team for a custom development quote.

Insert the Zonos JavaScript snippet

Add the following snippet to the head tag of your site. In order for Hello to be available across all pages on your site, you need to insert the snippet in a spot that is loaded on every page. For example, if you have a header file that is included on every page, you can insert the snippet there.

Zonos JS snippet

<script src="https://cdn.zonos.com/zonos.js" />
<script>
  zonos.init();
</script>

Add your API key

Retrieve your Zonos API key via Dashboard:

Go to Dashboard -> Settings.
Click Integrate.
Copy your API key.

Once you have your API key, add it to the Zonos JS snippet in your website's head tag. The snippet should look like this:

Zonos JS snippet

<script src="https://cdn.zonos.com/zonos.js" />
<script>
  zonos.init({
    apiKey: 'credential_token_29d4450c-a4b7-44f7-a0b7-4cc181ce3227', // Replace with your actual API key
  });
</script>

We recommend using a server-side template engine or other secure techniques to insert your API key into your HTML with an environment variable. This will avoid exposing your API key in your HTML source code.

Configure the JavaScript snippet

Via the zonos.init function, you can customize the behavior of Hello. The following options are available:

Option	Description	Default
convertCurrency	If set to `true`, Hello will automatically convert prices on your site to the shopper's local currency.	`true`
greetShoppers	If set to `true`, Hello will automatically greet shoppers in their local language.	`true`
showForDomestic	If set to `true`, Hello will automatically show for shoppers in your domestic country.	`false`
restrictItems	If set to `true`, Hello will automatically restrict items that cannot be shipped to the shopper's country.	`true`
priceSelector	The CSS selector for the element that contains the price of your items. Used for currency conversion and duty/tax estimations.	`'.price'`
estimateDutyTax	If set to `true`, Hello will automatically estimate the duty and tax for your items and insert it inline with the price.	`false`

Zonos JS snippet

<script src="https://cdn.zonos.com/zonos.js" />
<script>
  zonos.init({
    apiKey: 'credential_token_29d4450c-a4b7-44f7-a0b7-4cc181ce3227', // Replace with your actual API key
    convertCurrency: true,
    priceSelector: '.price',
    // Any other options you want to set
  });
</script>

Test your integration

If you've configured everything properly, you should see Hello appear as your browse around your online store. If you don't see Hello, check your browser's console for any errors. See our Testing guide for full testing instructions.

Was this page helpful?

Questions?

See Zonos

policies and agreements.