Dynamic script injection

Installing a static script on your website is sufficient for DataUnlocker to work, and you can stop reading now if you think integrating DataUnlocker to your continuous integration pipelines is an overhead or you're fine updating the script manually when needed.

By design, DataUnlocker's script must be a static synchronous script that will precede all other scripts on the webpage. DataUnlocker decided not to host this script on its own servers to prevent even a small network delay to download this script or any possible availability issues that can affect your production website, hence, you need to inject a static script to the HTML code of your website.

There are 2 benefits of using script injection in continuous integration pipeline over the static script version:

  • 📦 Placing a static script version once doesn't allow DataUnlocker to ship new script versions without asking you to replace the script manually. Occasional script updates may not be an issue, but DataUnlocker also offers an API endpoint to be used in continuous integration, which will allow you to keep DataUnlocker's script up to date automatically.
  • 🚀 Having the entire HTML file processed leaves a chance for DataUnlocker to do more processing in the future, like encoding or modifying already-present 3rd-party scripts in the HTML code. This is not used right now, but upcoming DataUnlocker features like "proxy all request" or additional guards against some very tricky content blockers will be supported out-of-the-box when using HTML injection.

API

DataUnlocker provides a generic way to insert the script into any HTML page of your website. You can also utilize it for any template files used to assemble your front end during the build phase of your front end.

DataUnlocker exposes the following public API endpoints for injecting its script into the HTML code:

  • Useful to get the plain DataUnlocker's JavaScript piece.
    • https://api.dataunlocker.com/properties/{property-id}/scripts/latest
    • ℹ️ To avoid JavaScript-based blocking, it is recommended to prepend DataUnlocker's JavaScript code to your website's critical JavaScript resources (those which your web app can't function without), so that JS ad blockers won't be able to simply block it by a text pattern, for instance .join(''). In this case, make sure trackers scripts execute after DataUnlocker's script, as otherwise DataUnlocker won't be able to unblock them. Use "defer" attribute for scripts (<script async DEFER ...>) where needed to guarantee the order of async scripts execution.
  • Useful to prepend DataUnlocker's JavaScript in HTML (better use the first option).
    • https://api.dataunlocker.com/properties/{property-id}/scripts/latest/inject

Where {property-id} is the same ID you see in browser's URL when looking at your property on DataUnlocker. By using this endpoint, you are guaranteed to always properly place the script in the HTML code, for instance, by using this bash command:

  • Prepend DataUnlocker's script to a critical JavaScript
    • file=index.js && echo -e "$(curl 'https://api.dataunlocker.com/properties/{property-id}/scripts/latest')\n$(cat $file)" > $file
  • Inject DataUnlocker's script into HTML (this does not mix it with existing scripts)
    • output=$(curl --fail -F [email protected] 'https://api.dataunlocker.com/properties/{property-id}/scripts/latest/inject') && echo "$output" > index.html || echo "Failed to inject DataUnlocker's script"

🔮 This DataUnlocker's endpoint is smart enough to detect its own script if it's already present in the HTML code. You can utilize this magic by putting a static script version to the HTML file, which will guard your application in case DataUnlocker's script injection endpoint accidentally fails in one of the builds.

Follow the instructions on the UI to set continuous integration up with DataUnlocker's script injection:

Using continuous integration to install DataUnlocker's script

DataUnlocker Logo
DataUnlocker
Content blockers are friends