Visitor Localization SDK

Javascript SDK for integrating localization to show Franchisee/Location information into your corporate website experiences

What is Visitor Localization

Allows you to "localize" corporate website experiences using the Local/Franchisee information. Examples include showing the Location name and phone number in the Header with key CTAs like calling, visiting the Local site or contacting the Location.

Franchisee information can be displayed within corporate pages after they have already visited the Franchisee's local site, or optionally you can auto-detect the visitor location and show them the local information of the Franchisee nearest to them.

Configuration options

List of all the available script options that can be set (via sbGeoipOptions). More details on each option below

OptionDescriptionConfiguration examples

automaticLocalization

Automatically localize the visitor using their IP address

true or false (default)

dni

Dynamic Number Insertion to replace all numbers within pages to the local number

true or false (default)

ignorePaths

List of website page paths where you do not want the Visitor localization to run

[ "/locations/",

"/privacy-policy" ]

localizeLinks

Option to provide a list of page paths that should be "localized" to the Franchisee/Local site version when clicked

[ "/about-us/",

"/contact-us/" ]

locationApiOptions

Advanced options to configure the Local search API call used when automaticLocalization is enabled.

{ threshold: 200 }

locationCacheType

Method of browser storage used for the Location information

"localStorage" (default) or "sessionStorage"

onLocationSet

Primary callback function that runs once we have the Franchisee/Location information available

function (data) {

// use the localization data }

More details on each option below

Installation

Place the following script at the end of the <body> of any page your want the localization to run.

  • Replace the data-api-key="YOUR-API-KEY-HERE" with the API key provided to you by DevHub.

  • Update the onLocationSet to use the Location information to update your page. More examples below

  • Add additional configuration options to sbGeoipOptions as needed

<script>
var sbGeoipOptions = {
  onLocationSet: function (data) {
    // use the Location information to update your page
    // additional examples below
  }
};
</script>
<script defer id="sb-geoip" data-api-key="YOUR-API-KEY-HERE" src="https://cloudbackend.scdn7.secure.raxcdn.com/stat/jsutils/js/geoip_localization.js"></script>

Example: Simple Vanilla JS example

Simple onLocationSet example that displays the Location name within an element on the page.

Target element

<div id="custom-element">
    Placeholder content
</div>

onLocationSet example

var sbGeoipOptions = {
  onLocationSet: function (data) {
    let el = document.getElementById('custom-element');
    if (el) {
        el.innerHTML = '<span>' + data.location.location_name + '</span>';
    }
  }
};

Example: Using Handlebars.js templating

For more complicated HTML templating, we suggest using a client-side templating library like Handlebars.js to render the HTML needed.

Here is an example that replaces an element's content with some HTML containing the location name, phone number, CTA button and the display's the estimated visitor's zip code if available.

Target element

<div id="custom-element">
    Placeholder content
</div>

Handlebars template and utility function

<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/handlebars.js/4.0.12/handlebars.min.js"></script>

<script id="localization-template" type="text/x-handlebars-template">
<div class="sb-location-name">{{data.location.location_name}}</div>
<div class="sb-location-phone">{{data.location.phonemap.phone}}</div>
<div class="sb-location-cta">
  <a href="{{data.location.location_url}}">Visit website</a>
</div>
{{# if geoip.zip}}
  <div class="sb-visitor-postal-code">at {{data.geoip.zip}}</div>
{{/if}}
</script>

<script>
var sbHandlebarsTemplate = function(id) {
  // handling of handlebars custom templates
  var el = document.getElementById(id);
  if (typeof Handlebars === 'undefined' || !el || !el.innerHTML) {
    return;
  }
  return Handlebars.compile(el.innerHTML);
};
</script>

onLocationSet example

var sbGeoipOptions = {
  onLocationSet: function (data) {
    let el = document.getElementById('custom-element');
    if (el) {
        let tpl = sbHandlebarsTemplate('localization-template');
        el.innerHTML = tpl(response);
    }
  }
};

More details on configuration options

Automatic localization (automaticLocalization)

If a visitor does not already have a Franchisee/Location assigned from a previous visit, should we use the visitor's IP address to search for their nearest location.

If disabled, then the only way a visitor is assigned a Location is by visiting a Franchisee/Local site first.

Example:

var sbGeoipOptions = {
  automaticGeolocation: true
};

Dynamic Number Insertion (dni)

Using the Franchisee/Location phone number entered into DevHub, should we replace all phone numbers within the corporate page content with the local number.

Note: if you are using your own call tracking provider, you will want to confirm that their DNI scripts work well in combination with ours.

Example:

var sbGeoipOptions = {
  dni: true
};

Ignore Paths (ignorePaths)

This is a list of website page paths where you do not want the Visitor location to run. If one of these paths if opened by the visitor, no localization will execute. List of page paths starting with slash ("/")

Example:

var sbGeoipOptions = {
  ignorePaths: [
    "/locations/",
    "/privacy-policy/"
  ]
};

Option to provide a list of page paths that should be "localized" to the Franchisee/Local site version when clicked.

Example: if the corporate site has a /contact-us/ and an /about-us/ page, and the Franchisee sites also have the same pages, but under their Location site URL like /seattle/contact-us/ and /seattle/about-us/. If the visitor clicks on any corporate link to those pages, they will instead get routed to the Local version of that page instead.

Note: This only works if the paths are exactly the same on the Corporate and Local sites

Example:

var sbGeoipOptions = {
  localizeLinks: [
    "/about-us/",
    "/contact-us/"
  ]
};

Location search API options (locationApiOptions)

Advanced options to configure the Local search API call used when automaticLocalization is enabled.

  • threshold: 200 - Used to limit how far a nearby location will be searched based on the visitor location.

Example:

var sbGeoipOptions = {
  locationApiOptions: {
    threshold: 250
  }
};

Location cache type (locationCacheType)

Method of storage for the Location information in the browser.

"localStorage" (default) or "sessionStorage".

  • localStorage will keep the location information if the visitor closes the window and comes back for a future session

  • sessionStorage will only keep the visitor localized for the current session and cleared after closing the browser window.

Example:

var sbGeoipOptions = {
  locationCacheType: "localStorage"
};

Location set (onLocationSet)

This is the primary callback function that runs once we have the Franchisee/Location information available. This is where you can then use this information to render content into your site.

On successful lookup, will return a response object that contains the following:

response.location

This is our standard Location object containing address, phones, and location_url

response.geoip

This is the geo IP data about the visitor

Includes:

  • geoip.zip - Zip code detected for the visitor

Example:

var sbGeoipOptions = {
  onLocationSet: function (data) {
    // use the Location information to update your page
    // additional examples within these docs
  }
};

Using Headless content to Localize navigations

Using the headlessContent utility within onLocationSet, you can fetch a copy of the Local site header or footer and using that HTML content then "mirror" that Local navigation into the Corporate navigation.

onLocationSet: function(response) {

  if (response.location.location_url) {
    sbGeoip.headlessContent(response.location.location_url, ['header_html'], (content) => {
      // get the local nav element
      const localNav = content.rendered.header_html.getElementById('nav-target');
      // replace the current nav
      const corpNav = document.getElementById('nav-target');
      if (corpNav && localNav) {
        corpNav.replaceWith(localNav);
      }
    });
  }

}

Last updated