How Coil works

Part 1 of this series made clear why web monetization is a good thing and we web developers should start paying for our articles and documentation. In this second article we’ll take a look at how Coil works.

Step 1: Register with Coil

First, both payer and payee should register with Coil. Unfortunately, for payees this process is not yet as streamlined as it could be.

For now payees need to register both with Coil and with an Interledger-enabled wallet where you can receive payments. This double sign-up is annoying, and you need to remember both sets of credentials. Coil is working on integrating the Interledger part into its service, but this integration has not yet finished at the time of writing.

And what, you might ask, is Interledger? It is an open protocol for exchanging money - initially between cryptocurrency servers, but now also to regular bank accounts. This series will not treat Interledger in more detail, but it is the technical basis for any web monetization system, Coil and all future ones. Stephanie Rieger wrote a great, non-technical introduction to Interledger for those who are interested.

Step 2: Add meta tag

During sign-up payees are given a payment pointer for that wallet in the form $url.of.server/someID. You should insert a <meta> tag into each page that you want to monetize, like:

<meta name="monetization" content="$url.of.server/someID">

This tells Coil where to send payments to. We’ll take a closer look at this <meta> tag in the next part of this series.

Step 3: Install extension

The payer should install the Coil extension in order to actually pay money.

The only browser to support the draft Web Monetization specification is the Gecko-based Puma Browser for Android. Until more browsers support the standard natively you will have to use an extension. A Safari extension is not yet available, but all other major browsers have one.

The extension works with HTTPS and HTTP connections, but not with FILE connections — something to keep in mind during testing.

Step 4: Restrict content

The payee can offer extra content to paying visitors. In the future this might become a vital feature. For instance, you could decide that your blog posts are only visible to users that pay you for the first two weeks or so, after which the paywall will be removed. Or you may keep access to some vital articles restricted to paying users forever.

At the moment hiding content can only be done via a fairly easy to hack scripting solution that we’ll take a closer look at in the next part. A server-side solution is not yet available at the time of writing, though Coil is aware of its importance.

Coil created a Wordpress plugin, and more plugins for other systems are in the works. Still, the most important feature would be a server-side solution to detect the presence of a monetization stream, so that the server can decide whether to send extra content or not. This feature is lacking as of right now, and the Wordpress plugin also relies on JavaScript to show and hide extra content.

Privacy

Coil is serious about privacy. It retains the minimum amount of data it needs to function. It needs to know who you are for its core service (duh) but does not divulge that information to anyone you pay or anyone who pays you. Every payment you make is an anonymous transaction.

The extension you install in your browser must be able to see the Interledger wallet it should pay to (duh), but does not store the URLs of sites you visited. The payee does not get any information about you, either, except for the amount of money you paid.

The extension needs permission to read your browsing history. For obscure reasons this is necessary to deliver payments. Coil does not actually read your browser history.

For more information you should read the Coil privacy statement, which is one of the clearest ones I've ever read.

The payment stream

If you added the <meta> tag to your site, and a user with the Coil extension visits you, you're getting paid. How much? How does it work?

Coil pays out US$0.36 per hour for every visitor of your site. That's not a huge amount of money, but if several thousands of people visit your page for 10 minutes each ... well, you can do the math. Web monetization is about a large number of people paying a small amount each.

There's a catch here. All payers give Coil a fixed amount per month, currently US$5, and if Coil has spent that amount they can give no more. In order to prevent sites you visit later in your billing month getting nothing, Coil starts throttling the payer's payments once $4.50 is spent, and pays a lower amount.

Coil intentionally pays a flat rate. If payers or payees would be able to set prices they would initiate a race to the bottom, where payees would ask for less and less money in order to attract more payers, while payers would cap their payments at the lowest possible level. Since this state of affairs is almost indistinguishable from the current free-content model, Coil decided to short-circuit it by establishing flat rates. See this discussion for more informtion.

Technically, every second or so the extension sends out an Interledger request and, ideally, receives a positive response. At that time a tiny amount is transferred from payer to payee. This process does not need JavaScript to run, though there are JavaScript events that allow you to monitor the process. We’ll get back to those in the next part.

For each request the extension reads out the <meta> tag anew. Thus, if the tag's contents have been changed in the mean time, the extension automatically redirects the payment stream to the new ID.

If the payer loses their connection the payment stream will stop, but the extension will remember how much time the payer spent on the payee's site. Once the connection is restored the extension will calculate the balance and send out an Interledger request for that amount. This information is lost if the payer closes their browser window before the connection is restored, however.

If a monetized page disappears into the background, for instance because the user opens another tab, the payment stream is supposed to stop, only to resume when the user brings the page to the foreground. However, my tests indicate that this is not actually the case, and that the payment stream continues even while the page is in the background. This is an unsolved problem at the time of writing — maybe my tests are incorrect; maybe it’s a bug in the extension; maybe the payment stream is supposed to continue.

Now we have a bird’s eye overview of how Coil works. Part 3 will describe the <meta> tag and the JavaScript API, and in part 4 we’ll take a look at the future, which includes a formal W3C standard.