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="https://example.com/pay">

New monetization tag:

<link rel="monetization" href="https://example.com/pay">

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
}

New monetization feature detection :

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


if (link.relList.supports(“monetization”)) {
    // Monetization is supported
}

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
});

New monetization event:

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

link.addEventListener("monetization", function(event) {
    // Handle sent payment 
});

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.