General Usage


For the first installation, the documentation can be found here.


Using the only API Widget, you can register events that are dispatched by the widget.

The API widget is inserted into the head tag of your theme via the extension. Therefore, it is recommended to access Geolizr through events to ensure that Geolizr has been initialized correctly.


Depending on the logic you want to incorporate, there are different entry points.

 

You can register an event using the following function:

document.addEventListener


Registers a callback function for a specific event.


document.addEventListener([event], [callback]);


Parameters


event The event you'd like to listen to.


callback The function that is called whenever the event is dispatched.



Events


Here is a list of currently available events.


geolizr.geoData


It is dispatched as soon as the customer's geo data is available.
<script>
   document.addEventListener('geolizr.geoData', [callback]);
</script>


 

Callback parameters


geoData An object containing geo-related information:


{
  status: [success|false],
  as: "<provider id ex: ASxxxx Telecom GmbH>",
  city: "<city ex: Cologne>",
  country: {
    code: "<country-code ex: DE>",
    country": "<country-name ex: Germany>"
  },
  countryCode": "<country-iso-code ex: DE>",
  isp: "<Internet Service Provider ex: Telekom GmbH>",
  lat: <latitude ex: 50.9326>,
  lon: <longitude ex: 6.9342>,
  org: "<Organisation or Provider ex: Telekom GmbH>",
  query: "<ip adress ex: 87.78.185.249>",
  region: "<region-code ex: NW>",
  regionName: "<region-name: ex: North Rhine-Westphalia>",
  timezone: "<time-zone ex: Europe/Berlin>",
  zip: "<zip-code>",
  currencyCode: "<currency-code>",
  currency: {
    code: "<currency-code ex: EUR>"
  },
  countryName: "<country-name ex: Germany>"
}



Example


<script>
document.addEventListener('geolizr.geoData', (data) => {
        console.log(data);
});
</script>

Notifications

notification.show


It is dispatched whenever a notification is displayed.

<script>
   document.addEventListener('notification.show', [callback]);
</script>


 

Callback parameters


notification The notification:


{
  id: [notification id],
  dismissible: [true|false],
  rememberCloseState: [true|false],
  linkText: [text of the link],
  linkUrl: [URL of the link],
  message: [notification message],
  font: [list of fonts],
  backgroundColor: [background color],
  textColor: [text color],
  linkColor: [link color]
}




Example

<script>
document.addEventListener('notification.show', (notification) => {
        console.log(notification);
});
</script>


notification.resize

It is dispatched whenever a notification is resized.
<script>
   document.addEventListener('notification.resize', [callback]);
</script>


document.addEventListener('notification.resize', [callback]);

 

Callback parameters


notification The notification:


{
  id: [notification id],
  dismissible: [true|false],
  rememberCloseState: [true|false],
  linkText: [text of the link],
  linkUrl: [URL of the link],
  message: [notification message],
  font: [list of fonts],
  backgroundColor: [background color],
  textColor: [text color],
  linkColor: [link color]
}



notification.height The height of the notification.


Example


<script>
document.addEventListener('notification.resize', function(notification) {
    console.log(notification.notification);
    console.log(notification.height);
});
</script>



notification.hide


It is dispatched whenever a notification is hidden.


Callback parameters


notification The notification:


{
  id: [notification id],
  dismissible: [true|false],
  rememberCloseState: [true|false],
  linkText: [text of the link],
  linkUrl: [URL of the link],
  message: [notification message],
  font: [list of fonts],
  backgroundColor: [background color],
  textColor: [text color],
  linkColor: [link color]
}



Example


<script>
document.addEventListener('notification.hide', function(notification) {
   console.log(notification);
});
</script>



Popups


popup.show


It is dispatched whenever a pop-up is displayed.


document.addEventListener('popup.show', [callback]);

 

Callback parameters


popup The popup:


{
  id: [popup id],
  backgroundColor: [background color],
  pageBackgroundColor: [page background color],
  textColor: [text color],
  dismissible: [true|false],
  roundCorner: [true|false],
  rememberCloseState: [true|false],
  filterlistType: [none|blacklist|whitelist],
  filterlistUrls: [urls for the filter]
}




Example


<script>
document.addEventListener('popup.show', function(popup) {
   console.log(popup);
});
</script>



popup.resize

It is dispatched whenever a pop-up is resized.


GeolizrAPI.addEventListener('popup.resize', [callback]);

 

Callback parameters


popup The popup:


{
  id: [popup id],
  backgroundColor: [background color],
  pageBackgroundColor: [page background color],
  textColor: [text color],
  dismissible: [true|false],
  roundCorner: [true|false],
  rememberCloseState: [true|false],
  filterlistType: [none|blacklist|whitelist],
  filterlistUrls: [urls for the filter]
}




Example


<script>
document.addEventListener('popup.show', function(popup) {
    console.log(popup);
});
</script>


popup.hide


It is dispatched whenever a notification is hidden.



Callback parameters


popup The popup:


{
  id: "[popup id]",
  backgroundColor: "[background color]",
  pageBackgroundColor: "[page background color]",
  textColor: "[text color]",
  dismissible: "[true|false]",
  roundCorner: "[true|false]",
  rememberCloseState: "[true|false]",
  filterlistType: "[none|blacklist|whitelist]",
  filterlistUrls: "[urls for the filter]"
}




Example


<script>
document.addEventListener('popup.show', function(popup) {
    console.log(popup);
});
</script>


Redirects


redirect.executed


It is dispatched whenever the redirects are configured, but blocks the execution.


Callback parameters


redirectResult The result of the redirect.


{
     code: [rejected code],
     message: [rejected Message],
     redirect: {
         id: [redirect id],
         filterlistType: [none|blacklist|whitelist],
         filerlistUrls: [urls for the filter],
         redirectIgnoreReferrers: [urls for ignored referrers],
         redirectUrl: [target URL for the redirect]
     }
}


Codes and Messages


CodeMessage / Description
200<empty string> / No error - should be executed
904"Filter blocks the Redirect"
905"Referrer ... blocks the redirect"
906"Destination and current URL are the same."


Example


<script>
document.addEventListener('redirect.executed', function(result) {
  console.log(result);
});
</script>




Currency Converter


currency.change


It is dispatched whenever the currency has changed.


Callback parameters


currency The currency code.


Example

<script>
document.addEventListener('currency.change', function(currency) {
    console.log(currency);
});
</script>

currency.api


It is dispatched as soon as the currency api is available.


Callback parameters


api.switchCurrency  => A function that can be called to switch the currency.


api.getCurrency => A function that returns the currently selected currency.


Example

<script>
document.addEventListener('currency.api', function(api) {
   api.switchCurrency('USD') // switches the currency to USD;
   console.log(api.getCurrency());
});
</script>