DEV Community: Peter-Paul Koch

WMS changes part 2: Background information

Peter-Paul Koch — Tue, 26 Oct 2021 09:09:23 +0000

In part 1 we treated two upcoming breaking changes in web monetization. This article looks ahead to potential other changes, and introduces you to the reasoning behind them. It also gives one piece of background.

These changes will not take place immediately, but they will likely come into effect somewhere in 2022.

New events

Currently the Coil extension supports four events; you can read more about them here. These events are going to be revised, in particular because there is no error event that warns you of monetization stream errors.

The changing of the event model may be breaking change; we can't say yet because it's not yet certain exactly what the new events are going to be.

Errors

As with any request over the Internet, a lot can go wrong with web monetization requests. The Interledger protocol (ILP) that underlies web monetization is able to handle some of these problems itself. A payment request or response, or delivery of a receipt, may go wrong. Much like TCP, ILP has some built-in error correction mechanisms.

These corrected errors do not have to be reported to a web page, just as regular JavaScript events do not report TCP problems. It's only when ILP cannot recover from an error and gives up that browsers should be notified and should fire an event. Thus you as a web developer know that something exceptional has happened, and can react appropriately.

You might, for instance, decide to pause access to paid content, or decide to continue giving the user access for a while longer, until, for instance, several error messages have come in.

The problem with errors is that there are so many types. A networking error like the one described above is one of them, and it’s a complicated one. Will the extension fire an error event if a single payment or receipt goes missing? Or only when a whole string of them disappear? That has not been decided yet.

Simpler errors include the inability to connect a certain payment pointer (the pointer is probably wrong), or receiving invalid JSON as a response. Error events should certainly be fired in circumstances like these that prevent normal monetization.

Maybe a property should be added that states the nature of the error; incorrect pointer, invalid JSON, or network error. You'll likely want to do different things in these circumstances. This, too, has yet to be decided.

Monetization as a state machine

A first attempt has been made to define the states a web monetization stream can be in. In the future, the state property will reflect the state of the stream. Currently discussed values include:

error: an error has occurred, as discussed above
active: all's going well
paused: monetization possible, but not occurring right now; maybe the <link> tag has been temporarily disabled
idle: monetization possible, but the stream hasn't started yet.

Maybe the paused and idle values are going to be combined — that depends on how much difference there is between the two states.

pointers

Currently, if you want to access the payment pointer you do this:

document.monetization.pointer

The payment pointer contains the content of the <meta> tag, for instance $url.of.server/myID. Here several changes will take place as well:

document will change to navigator
the payment pointer will be in a <link> tag, not a <meta> tag and will become a valid URL instead of the current $-prepended string
Maybe the internal logic of pointer will change as well.

Part 1 discussed the first two changes. Here we’ll discuss the final change. Changing pointer’s internal logic would probably be a breaking change.

Multiple pointers

Currently a document can have only one payment pointer at a time. Future iterations of the specification might change this — consider, for instance, an article with three authors who split the money evenly. The document would need three payment pointers. But which one of them should be in pointer?

The likely answer is: none of them. Future versions of the spec will likely have a collection pointers that contains all payment pointers in the document. Maybe there will be an activePointer or activePointers property as well to denote payment pointers that are currently active — though it's unclear as yet how 'active pointers' will be defined.

In fact, it's not yet completely clear how to define multiple payment pointers. Multiple <link> tags? One tag with all the pointers? And if the three authors in the example do not split the proceeds evenly but, for instance, 50% / 25% / 25%, how are we going to add that information to the <link>? And to the JavaScript API?

These questions have to be solved before pointer can change.

media queries

Currently web monetization works at the HTML and JavaScript levels. It might be a good idea to bring the third leg of the front-end stool, CSS, into the mix as well. Maybe a monetization media query could be useful. Something like this:

.hidden-content {
    display: none;
}

@media all and (monetization: true) {
    .hidden-content {
        didplay: block;
    }
}

The question is exactly how it's going to be implemented. The current discussion sees two options:

A simple boolean flag: a page is either monetized or not monetized. This is what the simple example code above does.
A more nuanced system where the source of the payment stream is also considered. Examples could be ads, subscription, webmonetization, or other payment options.

The second option is clearly the most forward-thinking one, but also harder to implement. Once they support web monetization natively browsers will know if a page is web-monetized or not, but how will it learn a page is ad-monetized? Or subscription-monetized? We can probably find a solution, but it will take time.

Maybe the media query will be implemented before all these issues are solved. It's possible we'll just start with the webomnetization and none values and add new ones as they are implemented. Thus the example above might become:

.hidden-content {
    display: none;
}

@media all and (monetization: webmonetization) {
    .hidden-content {
        didplay: block;
    }
}

This discussion is still in its infancy, and it will take some time before a monetization media query actually exists.

With that, you are now up to speed on the near future of web monetization. We’ll let you know if new functionalities appear in the extension, or browsers start to support web monetization natively, or if the specification changes significantly.

WMS changes part 1: Breaking changes

Peter-Paul Koch — Tue, 12 Oct 2021 10:00:08 +0000

In this two-part series we will look at recent developments in the Web Monetization specification and the Coil extension. This article discusses two upcoming breaking changes, while the next one treats several planned changes that won’t take effect immediately, as well as one piece of background.

This year, two breaking changes will be introduced in the Web Monetization specification and the Coil extension. The payment pointer will move from the <meta> to the <link> tag, and the JavaScript monetization interface will move from document to navigator. We will discuss those two changes and what you have to do to adjust your code.

`<meta>` to `<link>`

When a user with the Coil extension — or, in the future, a browser that supports web monetization — visits a monetized page the browser has to fetch a JSON file with monetization information. The location of this file has to be defined somewhere. Where?

One of the decisions made in the Web Monetization workshop was to move this definition from the <meta> tag to the <link> tag.

The old situation

The Coil extension currently uses <meta>; for instance

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

Browsers now download the JSON file from url.of.server/someID.

In the first draft of web monetization this tag was useful because <meta> tags do not have any default behavior, and Coil's extension could do anything it liked. Since web monetization was a new idea Coil needed to be able to work unimpeded by earlier decisions and functionalities already baked into browsers. Thus, using a neutral tag like <meta> was a good idea.

Why `<link>`?

Meanwhile web monetization is entering a new stage, where it has to be made ready for formal specification and native browser support. Use of <meta> is starting to restrict the future standard and the current implementations. By contrast there are several reasons why <link> is more future-friendly.

<link> specifies a relationship of the HTML document it appears in with an external resource, while <meta> gives more information about the HTML document itself. From the browsers' perspective, web monetization is an external resource. It doesn't have anything to do with the rendering process of the page; it merely defines external functionality. Thus, <link> is the correct tag to use here.

In addition, <link> has some useful functionalities that are already built into browsers:

With <link>, browsers already have a fetching mechanism for downloading external assets such as style sheets and favicons. Adding the monetization JSON file as a new one is fairly easy.
<link>’s referrerpolicy attribute allows you to decide how much information about the page the user is visiting browsers will send while they fetch the JSON.
<link> allows you to decide what to do about cross-origin policies. If browsers fetch the JSON file, what kind of information about the user will be sent to the payment end-point? From a privacy perspective the best answer is None, and the crossorigin="anonymous" attribute makes sure nothing is sent. Still, it allows web developers to define other CORS policies if necessary.
The disabled attribute allows web authors to disable the monetization link if they want to pause monetization.
A <link> tag is equivalent to a Link HTTP header. HTTP headers allow monetization information to be added to non-HTML documents as well — such as a PDF with an article that you'd like to monetize. Right now neither the specification nor the extension support this, but it can be easily added in the future.

Again, the main reason for the switch is that <link> contains these functionalities out of the box. It is possible to add all of them to <meta>, but why bother if browsers already offer a perfectly good alternative? You can read more about <meta> vs. <link> in this discussion.

Changes to your pages

The switch to <link> is a breaking change because you have to add a <link> to your website instead of <meta>. Fortunately that's quite simple. If you have this <meta> tag

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

you replace it with this <link> tag:

<link rel="monetization" href="https://url.of.server/someID">

As you see, the content/href of the two is not exactly the same. The current <meta> tag does not use a URL, but the <link> tag is required to — it should link to an external resource, after all, and browsers can only find that resource if you use a proper URL. In this simple example, replacing the custom $ by the standard https:// is all that's necessary.

Unfortunately there are also more complex cases, where <meta content> does not map to <link href> one on one. Be sure to read the payment pointer syntax article in order to convert all your pointers correctly.

The current Coil extension supports both <meta> and <link>, so it should seamlessly switch between the two. Even if it finds both tags in the HTML the extension will make sure only one payment occurs. Once browsers start supporting web monetization natively they will only recognize <link> and ignore <meta>.

Setting the payment pointer

The only minor outstanding problem is the way you change the payment pointer. Up until now the only way to do so was to change the content attribute of the <meta> tag, like so:

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

function changePointer() {
    let meta = document.querySelector('#paymentPointer');
    meta.setProperty('content','$url.of.server/myOtherID');
}

It's ugly, but it works. (For more information about the current JavaScript API, see this earlier article.)

Once you use <link>, though, you have to write a slightly different script, and if you use both <link> and <meta> you have to change both of them.

<meta name="monetization" content="$url.of.server/someID" id="paymentPointer">
<link rel="monetization" href="https://url.of.server/someID" id="otherPaymentPointer">

function changePointer() {
    let meta = document.querySelector('#paymentPointer');
    meta.setProperty('content','$url.of.server/myOtherID');
    let link = document.querySelector('#otherPaymentPointer');
    link.setProperty('href','https://url.of.server/myOtherID');
}

This is not impossible, but it's not very developer-friendly, either. What we need is a way to set the payment pointer directly in the API instead of messing about with HTML attributes. Ideally, it would be something like this:

function changePointer() {
    document.monetization.pointer = 'https://url.of.server/myOtherID';
}

Right now the extension supports getting the payment pointer in monetization.pointer, but not setting it. While a settable pointer is under discussion in the standards track, it turns out there are some issues that make it unlikely it will be implemented in the manner shown above. We’ll get back to this problem in the second part of this series.

document to navigator

The monetization interface is a collection of useful properties and events that let you monitor the monetization state of your web pages. The full current API is described here. Up until now it was a part of document, but it’s going to switch to navigator.

This, too, is a breaking change, and it has similar reasons as the switch from <link> to <meta>.

From document to navigator

At the moment the monetization interface is part of the document; for instance:

document.monetization.state

It's going to move to navigator, and this line of code will become:

navigator.monetization.state

Appending monetization to document has never made a lot of sense. Furthermore, document.monetization is a <div> tag, and that has never made any sense either.

In addition, appending monetization to the document could cause problems. It's possible to create a new document in JavaScript, and if monetiztion would be appended to that document it would also be monetized. This could lead to odd situations that it's better to prevent than repair.

Besides, the existence of web monetization is a top-level function of the browser, and not of the page. Moving it to navigator, especially in conjunction with moving the <meta> tag to a <link> tag, makes excellent sense. Also, navigator.monetization will no longer be a <div>.

The Coil extension will add navigator.monetization later this year — right now the road map says November. The Puma browser, which uses the Coil extension, will add it a few weeks later. For now they will also continue to support document.monetization.

Changes to your pages

Although there will be a transition period where the extension supports both, eventually support for document.monetization will end, and by that time this will become a breaking change.

That is, in the future any script that still uses document.monetization will break, since it cannot find the document.monetization interface. It should look for navigator.monetization instead, and you will have to code that explicitly. It’s best to do it right now so that you won’t have to worry again.

I advise you to do the following:

Throughout your scripts, change document.monetization to navigator.monetization.
Add the following snippet at the start of your script:

if (!navigator.monetization) {
    navigator.monetization = document.monetization
}

if (navigator.monetization) {
    // your scripts that use navigatior.monetization go here
}

If navigator.monetization does not exist, make it an alias of document.monetization. If your user’s browser does not support monetization document.monetization will not exist, either, but that’s OK.

Then check again if navigator.monetization exists. If it’s either supported natively or it’s an alias of document.monetization your script will run. If it’s still undefined your script will fail gracefully.

With that we have treated the upcoming changes in the Coil extension. Meanwhile, the Web Monetization standard remains in development, and it will likely introduce more changes. The next part in this series takes a look at a few.

The future of web monetization

Peter-Paul Koch — Tue, 13 Jul 2021 10:02:53 +0000

Part 1 of this series made clear why web monetization is a good thing. Part 2 described the Coil system at high level, while part 3 took a look at all those pesky details you need to know about.

In this article we’ll talk about the future. The immediate future mostly consists of a proper web monetization standard. For the more distant future the crucial question is how much interest there will be in web monetization, and whether the current model will remain intact or will change — and if so, how.

Standard

Coil is working on properly specifying web monetization, including the <meta> tag and API we discussed, with W3C. A draft standard is already available, but, as usual, these things take time.

The proposed draft is currently under discussion in the Web Platform Incubator Community Group, where proposals for new standards from unexpected corners can be discussed and, ideally, groomed for official W3C status.

What a WICG proposal needs most is practical implementation and usage data. Typically, this is easy to do for a browser vendor that can just include the proposal in its browser and see what happens next.

It’s harder for parties such as Coil who do not own a browser. That’s why uptake of the extension and creative use of the API, is so important: not only will user feedback improve the eventual specification, it will also convince other parties (read: browser vendors) that there is a serious use case for web monetization and a specification.

Eventually, web monetization should be supported natively, but that requires buy-in from the vendors. Right now only Puma implemented the proposal. Samsung Internet added the Coil add-on to the curated on-device list, which indicates a solid interest in web monetization — though without a Blink implementation it cannot proceed any further. The other browsers have not yet taken any steps.

Grant for the Web made a technical scholarship available that allowed a Firefox implementation to be written, although it has not yet been added to the browser. They are still looking for someone to port it to other engines.

New features

As soon as a proposal is implemented people start asking about new features, or updates of existing features. This is no different for Web Monetization.

One question is about RSS. If you monetize your blog, but you also offer the full content as an RSS feed, could you monetize that feed? It turns out that Atom already has a <link rel="monetization"> that could be used — provided RSS readers start doing something with this information, most likely transferring it to the page’s <meta> tag. As far as I know no RSS reader actually does so as yet.

Another interesting set of questions was asked around future functionality of the Web Monetization agent (currently the extension, but in the future the browsers). Would users be allowed to decide when they pay and how much? Either on a per-case basis or with block and allow lists?

And what if you have multiple extensions of different vendors installed. (That’s currently not an issue, since Coil is the only web monetization provider, but it might well become a problem in the future.)

What about donating a one-time sum to a specific page? That would be great for newspaper sites, who could decide to open their content to anyone who tips at least, I don’t know, $0.50 or so. One question is how long these users would retain access to that content, and if it’s for more than just the current session, where the fact that they have paid for the content will be stored. There are privacy issues here.

One question I have is if there should be a CSS way of showing extra content in addition to the JavaScript way. Something like this:

@media all and (monetization: monetized) {
    #extraContent {
        display: block;
    }
}

This sounds cool, but exactly when is a page monetized? When monetization has started (and the monetizationstart event fires in JavaScript)? That sounds reasonable, but it may take a few seconds, so it may take a little while before the extra content becomes visible, which could lead to a jagged user experience. On the other hand, the current extra content scripts that use monetizationstart have the same problem. A media query would not make things worse.

I’m not saying that this is the greatest idea ever. Instead, I want to encourage you to think about a broad range of topics in order to figure out whether monetization, or the tools we have at our disposal, can be extended even more, and in which ways. Creative thinking is very useful in this phase of the specification.

The future of web monetization

Still, new features are only part of the story. The other, and perhaps more exciting, part is how web monetization is going to develop in the future and how it will change the web.

Stephanie Rieger wrote a great paper about that future, and if you’re interested in web monetization beyond the details of the current implementation I recommend that you read it.

I won’t attempt to summarize it here, but Stephanie’s main focus is describing three possible futures for web monetization and using these as a a lens to discuss some problems we have to solve.

Will web monetization

allow the web to continue to work as it has in the past, just with more money for independent content creators? This is the most likely short-term outcome.
lead to one or two large monetizers that maintain payment streams from users to creators, leading to tiered access system akin to cable TV that concentrates on in-network content, however that may be defined — but the definition is being done by these large monetizers.
be extended to a complete virtual wallet system, where users may donate whatever they want, and monetization providers allow users to buy gift baskets with various tips. Also, there may be micro-subscriptions for a limited amount of time, or even donations for a specific image, phrase, or other bit of content — something you would retweet today.

Stephanie treats pros and cons of each model without extolling one over the others. It’s possible that one of her models is exactly on the mark, or that the future of monetization is found in a mix of these models.

Above all, reading this paper allows you to think ahead and decide what kind of future you would prefer, and why. And that, more than the details of the current system, is what’s most important in this exciting start-up phase of Web Monetization.

The Web Monetization meta tag and API

Peter-Paul Koch — Tue, 06 Jul 2021 10:00:33 +0000

Part 1 of this series made clear why web monetization is a good thing. Part 2 described the Coil system at high level. In this third article we're going to take a closer look at details: the <meta> tag and the JavaScript API.

The Coil developer site contains more information about technical topics, including a few example scripts.

The meta tag

During the sign-up process for Coil and Interledger you set up a wallet, which enables you to receive payments. You are given a payment pointer for that wallet in the form $url.of.server/someID. In order to monetize a page you should add a <meta> tag on that page that contains this pointer:

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

Right now you need tthe Coil extension to read out the <meta> tag — but in the future, when browsers support web monetization natively, they will do so themselves. If a page contains multiple monetization <meta>tags the extension uses the first one and ignores the others.

All this works without JavaScript. Neither the current extension nor the future standard are reliant on scripting for the initiation of a payment stream. If you want to get any information, though, or if you want to change the payment stream’s direction, you need JavaScript.

You can change the payment pointer by changing the <meta>tag. It's ugly, but it works:

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

function changePointer() {
    let meta = document.querySelector('#paymentPointer');
    meta.setProperty('content','$url.of.server/myOtherID');
}

The plugin will pick up on this change even in the middle of a session and divert all future payments to the new payment pointer.

One reason to do so is a collaborative article. If an article has, say, three authors, JavaScript could pick one of them at random and send the payment stream their way. Technically, you do this by switching the <meta>tag's content, as shown above. See this article for more information.

You could also use the Intersection Observer to figure out which page element is in view right now, and change the payment pointer based on that information. This could be useful if one page shows art by several creators, for instance. This article gives an overview and a code example.

Future: link

In the future specification the <meta> tag will likely change to a link tag, like this one:

<link rel="monetization" content="https://url.of.server/someID">

The reasons are complex and can be read here. The upcoming Firefox implementation uses this link, and not a <meta>.

That means that in the future any script that changes the payment pointer has to be rewritten, possibly changing the pointer in both the <meta> and the link tag. For that reason it would be nicer if the JavaScript API offered a direct, imperative way of setting the pointer, like:

document.monetization.pointer = '$url.of.server/someOtherID';

Right now the API doesn’t support this, although it is one of the many ideas under discussion.

JavaScript API

Since we’re on the topic anyway, let’s discuss the JavaScript API. It’s a light-weight, useful thing to have in your back pocket while messing about with payment streams. It consists of the document.monetization container, three events, and one property.

This API is part of the proposed standard, and if browsers start supporting web monetization natively they’ll take over this API as well. In that sense, current extension serves as a polyfill and scripts you write now will continue to work in the future.

document.monetization

document.monetization is the container for all API functionality, and its presence indicates that your current visitor supports monetization:

if (document.monetization) {
    // user may monetize you;
    // find out and do something
} else {
    // user is certain not to monetize you
}

document.monetization is a <div> DOM node that is not inserted into the document. Thus you can read document.monetization.nodeName and most other DOM properties, even though there is no practical reason to do so.

Making it a DOM node allows the firing of the custom monetization events we’ll treat in a moment. Without this trick it appears to be quite difficult to fire custom events from extensions, though specific information is surprisingly hard to find.

state

document.monetization.state contains information about the current monetization state. It can take three values:

started: a monetization stream has started and you will receive money. At least one valid Interledger package has been received.
pending: a monetization stream has not yet started, but the extension is trying to connect.
stopped: no monetization stream possible: the page has no <meta> tag, or the pointer is invalid.

If no <meta> tag is found the initial state is stopped. If a <meta> tag is present the initial state is pending.

If the <meta> tag contains no valid payment pointer the state becomes stopped. If a valid payment pointer is present the extension connects to the Interledger server and waits for the first package. Once that package arrives the state becomes started.

The state remains started even if the connection drops — the extension keeps track of the time spent on the site, after all.

If you change the payment pointer the extension first goes to pending and then to either started or stopped, depending on the validity of the new pointer.

So this snippet tells you if the user is currently paying you:

if (document.monetization && document.monetization.state === 'started') {
    // user is currently paying you
}

Events

document.monetization allows you to capture four events, three of which mirror the state property pretty closely:

monetizationpending: a monetization stream is being started up, but is not sending payments yet. Fires when the state is set to pending.
monetizationstart: a monetization stream has started. Fires when the state is set to started.
monetizationprogress: a new single payment has arrived. See below.
monetizationstop: a monetization stream has stopped. Fires when the state is set to stopped.

Typically, when a payer enters a payee’s page and a <meta> tag is present. the monetizationpending event will fire, followed by a monetizationstart event and an indeterminate amount of monetizationprogress events. If the payment pointer is invalid monetizationstop fires.

This is exactly the same sequence as with the state property, except that no event will fire if no <meta> tag is present. The sequence restarts at pending whenever you change the payment pointer.

The information the events deliver allows you to build a basic script to show/hide extra content:

if (document.monetization) {
    let extraContent = document.querySelector('#extraContent');
    document.monetization.addEventListener('monetizationstart',function() {
        extraContent.style.display = 'block'; 
        // or any other way of showing content
    });
    document.monetization.addEventListener('monetizationstop',function() {
        extraContent.style.display = 'none'; 
    });
}

Again, this script is fairly easy to hack, and won't work without JavaScript being enabled. It’s not suited for serious use, especially not in web development sites. Still, it serves as an example of using the monetization events.

monetizationprogress

The monetizartionprogress event fires whenever an Interledge package with a non-zero sum arrives from the Coil servers, which is generally every second or so. It contains information about the amount that's been paid so far, and you could use it to build a micropayment counter.

If the connection drops the payment stream also drops and the monetizationprogress event stops firing. If the connection is restored the event resumes after a new connection to the Interledger server has been made. As we saw before, the extension keeps track of the time the user has spent on your site, and the first payment after the restoration of the connection will pay for that entire time. Thus, you cannot assume that the payer stopped paying just because monetizationprogress stops firing.

Event properties

If you want to find out wha the current payment status is you can use the special properties of these events. All these are properties of event.detail.

amount is the amount contained in the current Interledger package, as an integer.
assetCode is a code for the currency, either a cryptocurrency or a real one.
assetScale is the number of places past the decimal for the amount. This serves to keep amount an integer.
paymentPointer is the payment pointer the extension read from the <meta> tag.
receipt is a proof of payment sent back to the payer.
requestID is a transient ID temporarily assigned to your payment stream.

For instance, this gives you the amount the last package delivered:

document.monetization.addEventListener('monetizationprogress',function(e){
    let amt = e.detail.amount;
    let scale = e.detail.assetScale;
    let code = e.detail.assetCode;
    let amount = amt * Math.pow(10,-scale);
    let printableAmount = code + ' ' + amount;
    // do something with amount or printableAmount
})

paymentPointer contains the same information as the <meta> tag. receipt and requestID contain values that are internal to the Interledger packages. You can use it to write a receipt verifyer if you like.

Reading out the amount of money an Interledger package contains requires the amount-related properties. For instance, if amount is 17 and assetScale is 3 you received 17*10^-3, or 0.017, of the currency indicated in assetCode.

That concludes our study of the <meta> tag and API. In the final part we’ll take a look at web monetization’s future, which includes a formal W3C standard.

How Coil works

Peter-Paul Koch — Tue, 29 Jun 2021 10:07:16 +0000

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.

Let's talk about money

Peter-Paul Koch — Tue, 22 Jun 2021 09:38:10 +0000

Let's talk about money!

Let's talk about how hard it is to pay small amounts online to people whose work you like and who could really use a bit of income. Let's talk about how Coil aims to change that.

Taking a subscription to a website is moderately easy, but the person you want to pay must have enabled them. Besides, do you want to purchase a full subscription in order to read one or two articles per month?

Sending a one-time donation is pretty easy as well, but, again, the site owner must have enabled them. And even then it just gives them ad-hoc amounts that they cannot depend on.

Then there's Patreon and Kickstarter and similar systems, but Patreon is essentially a subscription service while Kickstarter is essentially a one-time donation service, except that both keep part of the money you donate.

And then there’s ads ... Do we want small content creators to remain dependent on ads and thus support the entire ad ecosystem? I, personally, would like to get rid of them.

The problem today is that all non-ad-based systems require you to make conscious decisions to support someone — and even if you’re serious about supporting them you may forget to send in a monthly donation or to renew your subscription. It sort-of works, but the user experience can be improved rather dramatically.

That’s where Coil and the Web Monetization Standard come in.

Web Monetization

The idea behind Coil is that you pay for what you consume easily and automatically. It's not a subscription - you only pay for what you consume. It's not a one-time donation, either - you always pay when you consume.

Payments occur automatically when you visit a website that is also subscribed to Coil, and the amount you pay to a single site owner depends on the time you spend on the site. Coil does not retain any of your money, either — everything goes to the people you support.

In this series of four articles we'll take a closer look at the architecture of the current Coil implementation, how to work with it right now, the proposed standard, and what's going to happen in the future.

Overview

So how does Coil work right now?

Both the payer and the payee need a Coil account to send and receive money. The payee has to add a <meta> tag with a Coil payment pointer to all pages they want to monetize. The payer has to install the Coil extension in their browsers. You can see this extension as a polyfill. In the future web monetization will, I hope, be supported natively in all browsers.

Once that's done the process works pretty much automatically. The extension searches for the <meta> tag on any site the user visits. If it finds one it starts a payment stream from payer to payee that continues for as long as the payer stays on the site.

The payee can use the JavaScript API to interact with the monetization stream. For instance, they can show extra content to paying users, or keep track of how much a user paid so far. Unfortunately these functionalities require JavaScript, and the hiding of content is fairly easy to work around. Thus it is not yet suited for serious business purposes, especially in web development circles.

This is one example of how the current system is still a bit rough around the edges. You’ll find more examples in the subsequent articles. Until the time browsers support the standard natively and you can determine your visitors’ monetization status server-side these rough bits will continue to exist. For the moment we will have to work with the system we have.

This article series will discuss all topics we touched on in more detail.

Start now!

For too long we have accepted free content as our birthright, without considering the needs of the people who create it. This becomes even more curious for articles and documentation that are absolutely vital to our work as web developers.

Take a look at this list of currently-monetized web developer sites. Chances are you'll find a few people whose work you used in the past. Don't they deserve your direct support?

Free content is not a right, it's an entitlement. The sooner we internalize this, and start paying independent voices, the better for the web.

The only alternative is that all articles and documentation that we depend on will written by employees of large companies. And employees, no matter how well-meaning, will reflect the priorities and point of view of their employer in the long run.

So start now.

In order to support them you should invest a bit of time once and US$5 per month permanently. I mean, that’s not too much to ask, is it?

Set up a Coil account (which must include a wallet account). This article offers the best overview of the two-step process. Then install the Coil extension in your browsers. A Safari extension is not yet available.

Then read on about how Coil actually works. In part 2 we will present a high-level overview of how Coil works right now. Part 3 will describe all those pesky details you need to know, and in part 4 we’ll take a look at the future, which includes a formal W3C standard.

DEV Community: Peter-Paul Koch

WMS changes part 2: Background information

New events

Errors

Monetization as a state machine

pointers

Multiple pointers

media queries

WMS changes part 1: Breaking changes

<meta> to <link>

The old situation

Why <link>?

Changes to your pages

Setting the payment pointer

document to navigator

From document to navigator

Changes to your pages

The future of web monetization

Standard

New features

The future of web monetization

The Web Monetization meta tag and API

The meta tag

Future: link

JavaScript API

document.monetization

state

Events

monetizationprogress

Event properties

How Coil works

Step 1: Register with Coil

Step 2: Add meta tag

Step 3: Install extension

Step 4: Restrict content

Privacy

The payment stream

Let's talk about money

Web Monetization

Overview

Start now!

`<meta>` to `<link>`

Why `<link>`?