DocumentationGeneralHow DataUnlocker works

How DataUnlocker works

A very high-level explanation of why DataUnlocker works can be depicted as this:

How DataUnlocker recovers blocked requests

Ad blockers and other content blocking software block requests to URLs which match particular patterns, or target a specific domain.

When setting up DataUnlocker, it will ask you to create a new unique "URL prefix", which is either a DNS record or a path prefix at your own domain, which is not present in any of the content filtering lists. DataUnlocker will then encode URLs and proxy any blocked requests using this unique "URL prefix", which can also be changed at any time if it ever appears in any of filtering lists.

Because proxying requests to some third-party services may have unwanted side effects, DataUnlocker proxies only blocked traffic to not to break any existing functionality of your web application or third-party services it is using. To achieve this, DataUnlocker's script monkey-patches certain browser APIs, enabling an invisible proxy layer in case the request fails or is not loaded properly (by being replaced by, for instance, stubbed locally served resources).

The following diagram demonstrates how DataUnlocker's monkey-patching works:

DataUnlocker's monkey patching of the client-side browser APIs

From the web application's perspective, no code changes are required, as the interface and all patched browser APIs stay look and behave identically to the original APIs, with the only exception of what happens under the hood when the blocked request has been detected:

  1. The JavaScript application invokes the browser's API, for instance, fetch(url).
  2. In fact, JavaScript application invokes patched fetch. It performs the HTTP request just like it should.
  3. Now the browser's extension blocks url used in fetch. The patched implementation understands it and issues a proxy request under the hood.
  4. Proxied request bypasses URL filtering lists and returns the original response.
  5. In the JavaScript application, fetch(url) returns a proxied response instead of returning an error, thus behaving like the request wasn't even blocked.

Please note that by default DataUnlocker tries to proxy all failed requests regardless of their status, including requests returning 4xx or 5xx HTTP statuses in the response. To change this behavior, see configuring what to proxy.

The following diagram demonstrates a sequence of actions for successful and blocked requests, when DataUnlocker script is installed.

A sequence diagram of blocked and allowed request and how DataUnlocker unblocks blocked requests

Behind the scenes, DataUnlocker performs a lot of additional "magic" to make it work, which includes, but is not limited to:

  • Encoding and decoding client request and response data to bypass filtering lists.
  • Detecting content blocker intrusion and fixing its impact.
  • Recovering stubbed resources (resources that were loaded from ad blocker instead of the original server).
  • Transforming the client's request so that the target third-party server understands that was proxied properly.
  • Monitoring web applications and content filtering lists to ensure your web apps stay unblocked.
  • Any additional work required to keep its web applications unblocked, such as hot-swapping DataUnlocker servers' IP addresses if they end up in any of the blacklists.
  • Many additional features to configure the proxy for your needs and monitor DataUnlocker's impact.

In case DataUnlocker's setup (either the proxy endpoint or the script) lands in any of content filtering lists, DataUnlocker notifies its customers with the given impact and update steps for their configuration. Also, DataUnlocker offers automation for the complete installation refresh. Thus, blocking DataUnlocker is not feasible from the content blockers' perspective. Content blockers also risk to either break a lot of websites without a good reason or blacklist a good chunk of internet, because DataUnlocker can easily change its domains (offered via automation) and IP addresses, and it also uses JavaScript obfuscation and common JavaScript APIs which content blockers cannot filter out deterministically.

As for DataUnlocker's website itself, we expect our customers to be ready for adding an exception to visit in their browser, just like they already do, for example, to access Google Analytics.

DataUnlocker Logo
Content blockers are friends