Skip to content

Integrating Unlock on your site

Julien Genestoux edited this page Jul 17, 2019 · 9 revisions

We describe Unlock as a way to sell membership, but at it's core, Unlock is an open protocol which can be used to lock access to content, features, status, or physical spaces...

  • Content could include text, audio, video, or downloadable files.
  • Unlock can be used to restrict access to features of a software application or service, or to selectively activate advanced functionality.
  • Status could include badges and memberships.
  • Finally, physical spaces might include ticketing or dynamic door locks.

In order to limit access, creators create one (or more) lock. In order to gain access consumers send a payment to the lock and receive a key.

Unlock Inc (the company behind the protocol) provides several applications which implement the core protocol. One of them, called the "paywall" (and hosted at, is a web-based application whose purpose is to provide an easy front-end integration. It can be used to build an actual paywall - i.e., to restrict access to content - but it can also limit the ability to leave comments, or even to show only the list of supporters for a given open source project...

Our blog showcases a good example of what can be achieved:

  • The bottom bar shows the status (lock or unlocked)
  • On each post, comments are only available to members (see this one for example)
  • Some posts have content that is locked and only available to members, like this one.

This document shows how to integrate our "paywall" application on your web application.

Integration Consists of Five Steps

  1. Creating a Lock
  2. Installing the Lock on a web page
  3. Configuring the Lock
  4. Handling Events
  5. Initiating Checkout

Creating a Lock

Locks are smart contracts on the Ethereum blockchain. This provides creators with unmediated control over who can access their creations, and how much they want to charge for this. Unlock Inc. provides a simple dashboard to create a lock at [note: this currently requires an Ethereum wallet. Please get in touch if you need help. We can even create the lock for you and transfer its ownership to you so that you don't even need Ether to do it]

When creating a lock, the creator can select the following attributes:

  • The name of the lock (easier to identify it than its ethereum address)
  • The duration of each key (how long they are valid for)
  • The price consumers need to pay to get a key
  • How many keys at most can be sold

Once deployed the lock has its own address and is fully owned by the creator (no-one, including Unlock Inc. can change or remove it). Locks can also be transferred to a different owner after they've been created.

Installing the Lock on a web page

The first part of this requires embedding a script on the web page where the lock should be installed. You need to achieve this in the ​<head> section of the HTML body. The script to be loaded is located at the following address:

There are several ways to load that script in a non-blocking way. We recommend using the following approach:

<script> (function(d, s) {
var js = d.createElement(s),
sc = d.getElementsByTagName(s)[0];
sc.parentNode.insertBefore(js, sc); }(document, "script"));

We are using very strict caching (including a service worker) to make sure this script is loaded instantly.

Configuring the Lock

The following snippet should also be put in the ​<head>​ section of the HTML document and will let you configure the behavior of the paywall.

The ​unlockProtocolConfig​ is a global object which includes the locks indexed by their addresses on the Ethereum chain. Each lock is an object which can have an optional name (string). [Other configuration options may be added at a later point]

There is also an optional ​icon​ which will be shown on the modal and ​callToAction​ object with a ​default​ value set to the string of text shown on the checkout modal.

var unlockProtocolConfig = { 
  locks: {
    '0xabc': { // 0xabc is the address of a lock.
      name: 'One Week'
    '0xdef': {
      name: 'One Month' 
    '0xghi': {
      name: 'One Year'
    } // you can add as many locks as you want.
  icon: '', 
  callToAction: {
    default: 'This content is locked. Pay with cryptocurrency to access it!'

Handling Events

Once loaded the unlock script will trigger events on the page’s ​window​ object. These events will indicate to the page whether the current visitor owns a key to any of the lock (the state should be ​unlocked​ or if they do not, and the state should be ​locked​).

On your site, you can now implement the behavior based on whether the current visitor has a key to any of the locks or not.

Here is an example:

window.addEventListener('unlockProtocol', function(e) {
  var state = e.detail
  // the state is a string whose value can either be 'unlocked' or 'locked'...
  // If state is 'unlocked': implement code here which will be triggered when 
  // the current visitor has a valid lock key  
  // If state is 'locked': implement code here which will be
  // triggered when the current visitor does not have a valid lock key

Note: the callback can be invoked several times. For example, a visitor might purchase a key while they are on the page, going from the unlocked to the locked state. Similarly, the key that the visitor owns may expire during a visit which would result in the state going from unlocked to locked.

Initiating Checkout

In order to purchase keys, Unlock provides a modal which lets the user pick the lock of their choice (based on the configuration above). The modal can be loaded by invoking the following:

window.unlockProtocol && window.unlockProtocol.loadCheckoutModal()

It is good practice to ensure that the ​unlockProtocol​ object is defined before invoking the loadCheckoutModal() ​function.

Our blog shows multiple example of integration on existing CMS or front end web frameworks.

You can’t perform that action at this time.