Location Services

How to geolocate users with Cookie Consent

Architecture

Cookie Consent contains three modules named Popup, Law and Location.

  • Popup can be used on it’s own regardless of it’s location, and contains any and all functionality for displaying a popup on screen.
  • Law accepts the popup options and a country code. Using the country code it modifies the popup options, enabling/disabling certain functionality in order to comply with the law specified by that country
  • Location is simply a tool for getting the two letter country code that the user is in.

Together, these modules: get the country code, apply the law specific to that country, and display the popup (if necessary)

In code form, a service looks like this:

{ url: <string> //The location of the service API isScript: <boolean>, //Whether to use a script tag or a XMLHttpRequest data: <object>, //Useful if the service requires post data headers: <array>, //Useful for setting service specific header callback: <function(done, response)>, //A handler for understanding the response }

The callback provides a done callback. If you need to make additional requests, call done with the country code when you’re finished. Otherwise, just return the country code

Example:
{ url: '//example-service/script.js', isScript: true, callback: function (done, response) { // We just downloaded the 'script.js' which defined a third party object. if (!window.MyService) { done(new Error('The JavaScript file failed to download and define MyService')); } MyService.locateMe(function(response){ done({code: response.countryCode}); }, function(err){ done(new Error(err)); }); }, }

Services

In order to find the location, Cookie Consent uses third-party location services. These third-party services usually provide an API that can be accessed over the internet.

To integrate a new service, you need to define the service location, the type of request (XMLHttpRequest vs <script>) and how the tool should interpret the response.

To do this, define a new service like so:

cookieconsent.initialise({ ...popupOptions, location: { serviceDefinitions: { mynewservice: function(options) { return { url: '//example-service.com/json', callback: function(done, response) { // This function must parse the 'response' and return the country code, or fail. // If this function doesn't fail correctly, then the next service will not run. // Therefore, it's generally best to add a <em>try {...} catch () {...}</em> block try { var json = JSON.parse(response); if (json.countryCode) { return {code: json.countryCode} } throw 'Could not find a country code in the response'; } catch (err) { return new Error('Invalid response (' + err + ')'); } }, }; }, }, services: [ 'mynewservice' ] } });

Above, you can see that we first define our service, then we use it by adding it to the services array. We can add it simply by passing the name of it as a string.
Some service definitions may be more complicated though, and require configuration.

To do this, you can pass an object instead:
services: [ { name:'mynewservice', mySpecialOption: 'some value', KEY: 'uUCGtoyeiH5gsm3Wn2cp9D1Z1deHcpBG8ySA4hYBcQd20Z4C6AwGKqln7mtEfGN' } ]

Then, when defining your service, the options are passed through like so:

mynewservice: function(options) { // `options.mySpecialValue` and `options.KEY` now exist return { url: '//someurl.com?apiKey='+options.KEY // ...serviceDefinition }; }

As well as passing an object with options into the ‘services’ array, you can also pass a function that returns an object, just because.

Notes

Above, we integrated options.KEY with the url by simply appending the two string. If you’re lazy, there is an option called interpolateUrl which will automatically interpolate a string with the values of an object. Use it like so:

serviceDefinitions: { mynewservice: function(options) { return { url: '//example-service.com/json?key={api_key}&someValue=1&callback={callback}', isScript: true, // use this flag to tell the tool to download // the resource as a script tag (using JSONP) callback: function(done, response) { // handle response }, }; }, }, services: [ { name: 'mynewservice', interpolateUrl: { api_key: 'uUCGtoyeiH5gsm3Wn2cp9D1Z1deHcpBG8ySA4hYBcQd20Z4C6AwGKqln7mtEfGN' } } ]

The {callback} string can be used in the URL to automatically write the JSONP callback. It is appended with Date.now() to prevent global namespace collisions.

What's New at Osano

Pentland release offers new features on consent management and data subject access requests

As we here at Osano continue to roll out features to help you do data privacy right, we have some exciting new features to announce with our Pentland release.

Our First Layer Category feature allows you to turn off the “cookie categories” function within your first-layer cookie banner. This impacts end users within the European Economic Area and the U.K. Importantly, you still have the option to maintain the cookie categories function for your customers if preferred, but now, an “on/off” toggle button allows you the choice. 

The change is based on Osano customers’ feedback and aims to present a cleaner user experience and may result in higher opt-in rates to cookies.

In addition, the Pentland release provides a new service to help you comply with California residents’ privacy rights under California’s Consumer Privacy Act. The law requires businesses with an offline component or indirect relationship to provide a toll-free phone number for data subject inquiries. Customers using Twilio as a phone host can now integrate Osano’s “DSAR phone line,” which transcribes the call and places it into your company’s data subject access request center. This eliminates the need for call agents to fulfill your data subject phone line obligation under the CCPA.

Learn more about Pentland features

Osano offers privacy consulting

By now, you know that companies that show their customers that they take privacy seriously will earn their trust and loyalty. And we know that compliance with data privacy laws, like the GDPR or the CCPA, can feel like a burden. But what if it were easy and could boost your bottom line? What if you could relax — maybe even sleep at night! —  because your regulatory commitments were being handled.

We're excited to tell you: We can help you feel that way. Osano is now offering privacy consulting in addition to our compliance software. Whether you need an interim privacy officer, a data protection officer or project-specific resources, our privacy consultants are ready to roll their sleeves up for you. 

You can get started today with a free 30-minute consultation by clicking here. 

Find out more

Sweeney release

We have just released a major new upgrade to our platform. This update features role-based access controls for your business. Admins will now be empowered to restrict a user's access and control to specific parts of Osano's platform.

Role-based access controls are only the most visible of numerous enhancements in this update that improve the performance, integrity and security of the Osano platform. The release notes detail the full list of enhancements and bug fixes.

The name of this release is a hat tip to Latanya Sweeney, a Harvard professor and privacy researcher who has done pioneering privacy research for the past two decades. Click to read more about her impressive work.

Read the Release Notes

Westin release

Announcing a shiny new update to Osano's platform! Updates include:

  • Consent Manager preview showing language translations and popup styling by location
  • Consent Manager versioning and rollback
  • iFrame blocking support
  • Consent Manager configuration duplication
  • Two dozen other features, enhancements, and bug fixes

This release is named in honor of Alan Westin, the father of modern data privacy law. We released an article on our blog about how his work has shaped privacy laws and perceptions today.

Read the Release Notes

White paper: The Osano Data Privacy and Data Breach Link

Announcing a groundbreaking report analyzing the relationship between a company’s privacy practices and their likelihood of experiencing a data breach. The Osano Data Privacy and Data Breach Link reveals a predictive relationship between responsible privacy practices and security outcomes.

Download the White Paper