The Interledger Community 🌱

Cover image for Developer guide to migrating the breaking changes in the latest Web Monetization draft
Santosh Viswanatham
Santosh Viswanatham

Posted on

Developer guide to migrating the breaking changes in the latest Web Monetization draft

The Web Monetization API allows websites to receive payments from visitors who have a wallet connected to their browser.

The most recent draft of the Web Monetization specification (2023-09-20) introduced changes to be more consistent with the design of other browser features. The working group tries to provide stability in the API design. However, backward-incompatible changes like this are possible during the draft stage.

Websites and tools that implemented an earlier draft of the Web Monetization specification used by Coil will need to update their code to be supported by the new Web Monetization providers launching later this year. This guide will walk you through the necessary changes to ensure a smooth transition.

Updating the monetization meta tag πŸ’»

The latest specification replaced the meta tag with a link tag. The name attribute changed to rel and content to href accordingly. Update your HTML codes:

Old monetization tag:

<meta name="monetization" content="">
Enter fullscreen mode Exit fullscreen mode

New monetization tag:

<link rel="monetization" href="">
Enter fullscreen mode Exit fullscreen mode

This change is the only one many websites will need to make to be compatible with the latest version of the Web Monetization specification.

Checking monetization support πŸ•΅οΈβ€β™‚οΈ

Previously, the specification recommended checking for monetization support using the presence of a document.monetization object. The latest specification recommends using the browser’s supports() functionality for feature detection. Update your JavaScript feature detection code::

Old monetization feature detection:

if (document.monetization) {
    // Monetization is supported
Enter fullscreen mode Exit fullscreen mode

New monetization feature detection :

const link = document.querySelector('link[rel="monetization"]') ||

if (link.relList.supports(β€œmonetization”)) {
    // Monetization is supported
Enter fullscreen mode Exit fullscreen mode

Handling monetization events

Previously, the specification considered payments as streams with start, progress, and stop events. The latest draft uses a single event for when the browser has sent a payment. Update your JavaScript event listeners:

Old monetization stream events:

document.monetization.addEventListener('monetizationstart', function(event) {
    // Handle monetization start

document.monetization.addEventListener('monetizationstop', function(event) {
    // Handle monetization stop

document.monetization.addEventListener('monetizationprogress', function(event) {
    // Handle monetization progress
Enter fullscreen mode Exit fullscreen mode

New monetization event:

const link = document.querySelector('link[rel="monetization"]');

link.addEventListener("monetization", function(event) {
    // Handle sent payment 
Enter fullscreen mode Exit fullscreen mode

By following this guide, you'll be well-equipped to adapt your application to the evolving landscape of Web Monetization.

How to test your code? πŸ§ͺ

With the retirement of the Coil extension, the new Web Monetization provider extension has taken the stage. While it's not officially published, you can access and test your code by cloning the extension from here. Follow the instructions in the README file for building and installing the extension. While the extension doesn't currently feature wallet integration, it provides an environment for observing Web Monetization events triggered by the extension.

This extension allows you to simulate test events, and verify the integration of your library with the latest specifications. Keep an eye on the repository for updates and improvements. 🌐

Contributing to Web Monetization 🀝

To further support the Web Monetization ecosystem, You can actively contribute in various ways:

  1. Contribute by porting existing libraries to ensure compatibility with the latest WM draft
  2. Build new libraries for other frontend frameworks to enhance the WM tooling ecosystem
  3. Actively participate in testing the Web Monetization Provider extension to identify and report the potential issues in the extension

Organize a Hackday! πŸš€

Take your contribution to the next level by organizing a Web Monetization Hackday! Bring developers together to collaborate on creating and enhancing libraries, porting existing ones, and testing WM provider extensions. Connect with me for any support to make this event even more impactful! Let's shape the future of Web Monetization together. πŸŒπŸ’Έ

By following this guide and actively participating with the Web Monetization community, you can make the Web a more monetarily inclusive space! πŸš€

Thank you @jeremiah and @laka for providing your valuable feedback and helping me in making this guide better.

Thank you for reading and share with us in the comments if you have any comments/feedback on this guide to make it better.

Top comments (4)

ericahargreave profile image
Erica Hargreave

Looking forward to experimenting with this once I've finished all my student marking, later this week!

vineel profile image
Vineel R. Pindi

Thank you for breaking it down, very helpful guide!

priya profile image
priya sharma

Amazing post. I appreciate your content.

chrislarry profile image
Chris Lawrence

Love this post!