document.monetization vs global

[adrianhopebailie]

From web-monetization created by marcoscaceres: adrianhopebailie/web-monetization#23

Wondering what the rationale was for attaching monetization to the Document object? It doesn't really feel like the right place to attach this, as monetization doesn't itself affect the document or have anything specifically to do with the document interface. We should consider maybe having monetization either on Navigator or its own Monetization namespace.

[adrianhopebailie]

The decision about where to put this was not strongly sided either way. If it's better as a stand-alone global then let's make it a global.

[adrianhopebailie]

@marcoscaceres
Curious as to why that is.
Is that just the prevailing convention, or you have a rationale? or both?? :)

[adrianhopebailie]

Yes, putting something in the global namespace would be my preference.

[adrianhopebailie]

And here:
interledger/rfcs#500 (comment)
And:
interledger/rfcs#500 (comment)

To quote @justmoon from comments above:

To give some context: This made more sense to me because Web Monetization is now triggered by a meta-tag and meta-tags describe the document. So whereas previously it was a feature of the JavaScript environment (hence existing on window, it's now a feature of the HTML document.

[adrianhopebailie]

Yeah, I'm not sure. I wasn't really around for the beginnings of the spec, but I do recall reading some discussion when starting up. Tracked it down to here: interledger/rfcs#500 (comment)

[adrianhopebailie]

Thanks again for the info :)

[adrianhopebailie]

Is that just the prevailing convention, or you have a rationale? or both?? :)

Bit of both... we generally like to put things on the document that directly affect the Document. You can see what I mean by looking at the interface definition:

https://html.spec.whatwg.org/#the-document-object

In most cases, the methods and attributes affect the Document directly in some meaningful way. Monetization doesn't affect the Document or reflect some sate of the document, so should probably not be hung on that interface.

[adrianhopebailie]

PROPOSAL

Based on the discussion so far we should move the Monetization interface off of document and make it a global.

We can leave the existing document.monetization interface for backwards compatibility but mark it as deprecated.

This would also allow us to define a new API shape that takes into account the various other suggestions such as:

• changing the event names to conform to standard practice
• merging the event types and not use CustomEvent ( Merge MonetizationStartEvent and MonetizationProgressEvent? #23 )
• adding a ReadableStream that can be used to consume payments ( ReadableStream vs progress Event vs both #27 and monetization "stopped" state and monetizationstop / monetizationpending events #25 )
• using the existing PaymentAmountCurrency interface ( Use 'PaymentCurrencyAmount' Dictionary #16 )

Please respond to this proposal with either an 👍 or a 👎

If you are 👎 on this proposal please provide rationale below

[sublimator]

End of the day tired, but I'm in favor of this:

I can't imagine doing the donkey work of getting this working being that hard.
We just need to decide to move in this direction.

For:

1. Making whatever we see as enduring changes as soon as possible would mean less
   changes later.
2. We wouldn't have to change the meaning of pending on
   document.monetization, which is a subtly breaking change.

Against:

1. I can't really see any downside, except that it's not exactly an ongoing release/versioning strategy so much as a one time opportunity.

Generally, the end users (i.e. extension users) are going to have the most up-to-date extension released due to automatic updates.

Integrators are going to have a less easy time of it. Putting some thought into release management/explicit api versioning might help us (document.monetization ~= v2, window.monetization ~= v3 is only implied)

e.g.

// the first thing that comes to mind, but an illustration of what I mean
window.monetization.draft1.monetizationStream(...) 

[sharafian]

I have a preference for holding off these renaming-type changes for the last minute so that we can group them all together

[adrianhopebailie]

CONCLUSION: Move monetization to global

[sublimator]

sidvishnoi/gecko-webmonetization@517b8ce#commitcomment-46412865

[marcoscaceres]

it still feels safer to put it on Navigator, tbh (to avoid any potential collisions with existing user-land code). I think there is also W3C TAG guidance around this... though I can't remember where.

Sorry also about not responding above. There were other issues too, with Document... like a page can have/create multiple Documents (e.g., via document.implementation.createDocument()).

Anyway, the point in kinda mute if we are willing to shift it elsewhere.

[mankins]

Navigator makes sense to me.

I do wonder if monetization is actually too broad and it should be webmon or something more specific instead? There are multiple different ways to monetize a site (and multiple ways to spell monetise) ...

[huijing]

Resolved by #193