WMS changes part 2: Background information

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:

1. document will change to navigator
2. 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
3. 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:

1. A simple boolean flag: a page is either monetized or not monetized. This is what the simple example code above does.
2. 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.