An overview of where we stand with the spec. It is supposed to help Marcos and Alex take decisions during their California get-together.
The following things are certain (right?):
navigator.monetization
<link> tag
amount,
assetCode,
assetScaleThese three properties are exactly the ones that web developers will use most.
I assume all of the following.
rel="monetization" for the <link> tag. The current one does. I assume the spec will require this rel value as well. YES
allow="monetization" will share in the parent page's monetization stream. The ratio of sharing is an implementation detail. Nested iframes will also share, provided allow is set on all of them. YES
I have the following open questions:
navigator.monetization.pointer? Discussion NO
state, and if so do we define two or three states? Yes/no or Yes/possible/no? Lengthy discussion that cleared my mind and made me opt for the three-tiered variant. NO STATE (and no statechange event)
batched property or another way of declaring that batched payments are taking place? Discussion
receipt, requestID and url properties. Do we still need them? Discussion
As a test Nick added pointer to the preview extension.
The pointer property contains the URL to the payment end-point; i.e. the Interledger server that is to receive the user's payment. It has the same value as the <link href> attribute.
pointer can be changed programmatically. In that case the payment end-point is redefined and the payment stream will be redirected there.
navigator.monetization.pointer = 'https://my.monetization.com/userID';
Setting the pointer in this way changes the contents of the <link> tag.
There is discussion here. Marcos feels it's a bad idea, and sees the link tag as the sole source of truth. I disagree and think pointer should be added because it's the most important bit of web monetization and cannot be left out of the API. I see the API as the sole source of truth.
Marcos asked for an example of another API that changes a link tag. Although we couldn't find one, Nick suggested document.title: it changes the contents of an HTML tag. Whether this counts as a fully-fledged API or just as an old-fashioned Level 0 DOM mapping that's only retained for historical reasons is an open question.
Issue.
Dec 1: No state
What are we going to do with monetization state? Remove, use a two-tiered yes/no state, or a more fine-grained yes/possible/no state?
I understood from Nick that some implementors like trying/pending because it allows them to show premium content right from the start and assume a monetization stream will start. (If it doesn't start within a set time they could always hide the premium content again.)
I find myself drawn to that three-tiered option because it gives web developers the opportunity to decide for themselves what premium content they want to show at what time.
A possible/trying state does expose part of the protocol, but I'm starting to feel it's a part of the protocol that web developers can use. At first I didn't like it, but I changed my mind.
The ability to show or hide premium content depends on being able to read the current state of monetization.
The real problem appears to be batched payments. They would cause considerable confusion in a three-tiered state machine OR they need a totally different set of rules. Right now I'm unsure how they work exactly, so I cannot yet comment on this problem.
One way around the problem that web developers can implement on their own is determining how much has been paid and how long that payment remains valid. So a $2 tip might give you an hour, or even a day, of browsing time. The spec does not have to define this mechanism, since it's already implicit in the progress event. It does mean significantly more work on the part of web developers, though. Also, I'm not totally sure if this solves the issue of batched payments messing up state.
Sketch of state changes in a three-tiered system:
idle
trying if the browser finds a monetization link AND the user has an extension AND is logged in with Coil. (Right now the state onload is idle.)
idle to trying here?
idle
idle
idle? Or trying?
idle. If un-backgrounded -> trying
idle. If the page regains connection -> trying
trying
trying: set to active
This model makes extensive use of trying to denote an intermediate state where monetization could happen but is not currently happening.
state changes to trying when the page starts up, is un-backgrounded, regains a connection, or a pointer is changed, and active only when the first payment after that actually arrives.
That use of the state allows for the following type of logic, where web developers decide for themselves if, and how long, they want to wait for the first payment.
let waitingPeriod = 3000; // in ms
navigator.monetization.addEventListener('statechange',function() {
let timeout;
switch (navigator.monetization.state) {
case: 'idle':
hideContent();
break;
case: 'active':
if (timeout) {
clearTimeout(timeout);
}
showContent();
break;
case: 'trying':
showContent();
timeout = setTimeout(hideContent,waitingPeriod);
}
})
Still, what if nothing happens after state is set to trying. Should the browser/extension reset it to idle after, I don't know, 20 seconds or so?
This does not really take batched payments into account, mostly because I'm not sure how they work and whether they would break the three-tiered state machine. In his comment Ben admits that state only works well with a continuous stream.
The exact opposite would be not exposing state at all. In its most extreme form this would make WM a simple declarative API that says "Here's how you can monetize this site" and leave it at that, without any monitoring or exposing state. That would make the API a lot simpler.
However, this removes the possibility for premium content, since web developers have no way of knowing if their site is actually being monetized by the current visitor.
A possible solution would be a method such as isCurrentlyMonetized(), but that really allows state to sneak in by the back door, since this method will report the state of monetization. Also, if we go this route we'd really have to re-instate the statechange event, since web developers will want to know if the monetization changes.
The intermediate solution would be a binary state: site monetized or site not monetized. If we want to get rid of the state property, this new binary state should be immutable: at load time the extension (and in the future browsers) decide whether a site is monetized or not. However, that means that changes in monetization will not be recorded and exposed. In fact, the extension/browsers are forced to guess on whether a monetization stream actually starts or not; they cannot afford to wait for the actual stream to start, since the state has to be determined onload.
We could also retain state and the statechange event but make it a simple yes/no flag. But then we really don't change anything except removing the intermediate trying state.
And once we do that we're back to a situation where the extension/browsers must do one of two things:
active/started, and accept that this means it could happen premium content becomes visible only after a few seconds.
Do we need a batched property to indicate batched payments? The problem is that I do not fully understand how batched payments work.
Three properties are unclear.
If we implement pointer, event.detail.url is the same as navigator.monetization.pointer. In that case, do we need the url?
Do we still need requestID? Nick doubted it, and Alex is going to check if the wallets do anything with it. Issue.
Will receipts survive? Issue.
Dec 1: No media query
The media query depends on the API (or at least monetization) having state. If state=yes the media query fires, if state=no it does not.
The Web Monetization specification defines a monetization media query.
@media all and (monetization: webmonetization) {
// page is web-monetized
}
@media all and (monetization: none) {
// page is not monetized
}
For now it has two values:
none: The page is not monetized.
webmonetization: The page is web-monetized. But how is that defined?
It is possible that the media query will see future use in other monetization schemes, such as subscription- or ad-based ones. If that happens more values beyond webmonetization can be added for these schemes.
How do we define 'web-monetized'? state active or trying? We should pick the option that changes least, so that stroboscopic content is avoided. Right now it seems to me that active and trying should both map to webmonetization, while idle maps to none. This is the least intrusive option. However, if we ditch state altogether we cannot implement the media query either — it would not make sense to expose state in CSS but not in JavaScript.