Made by Gustavo and Amin

What We built

During our research we had a recurring thought cross our mind: How do I test my project? How do I know my site is actually going to detect user's payments and do what it is supposed to?

Coil kindly offered a free trial to all the participants of this challenge. But we felt that this was not enough. There was no way to control how much money Coil will send, or how frequent it sends it. We pictured a tool for the developers to control how to trigger these events, so they could test all the different use cases they developed.

That's how we ended creating Web Monetization Simulator, a browser extension to simulate a web monetization payment provider. Give it a try:

• Chrome
• Firefox

Submission Category:

Foundational Technology

Demo

Here you can see the extension doing the standard flow on a site that has monetization:

Site with no monetization:

Link To Code

gustavogr / web-monetization-simulator

Chrome extension to test web monetization without the needs of setting up a provider

Web Monetization Simulator

A browser extension to test web monetization without the needs of setting up a provider.

Try it out:

• Firefox:
• Chrome:

Developing

Adding to browser

For Chrome do the following:

1. Go to chrome:extensions
2. Click on "Load Unpacked", browse your files, and select the folder containing this repo

For Firefox do the following:

1. Go to about:debugging
2. Click on "This Firefox"
3. Click on "Load Temporary Add-on", browse your files, go to this repo's folder, and select manifest.json

View on GitHub

How We Built It

What browser should we target?

First thing we had to decide was: Firefox or Chrome? We did a little digging and found out that although both implement basically the same API, Firefox does it using the browser namespace and Promises and Chrome uses the chrome namespace and callbacks. So which one to choose?

Firefox also implements these APIs under the chrome namespace using callbacks. This allows code written for Chrome to run largely unchanged in Firefox for the APIs documented here.

Thankfully the great people at Firefox implement also the chrome namespace API, so we chose to focus on Chrome and hope it just worked in Firefox, which it did 😄

The different JavaScript contexts

One thing we found out early on was that thanks to the isolation between the contexts of the extension and the actual page you are seeing, adding the document.monetization expando was not an easy task.

After some research we found out we needed to inject the site with our own JavaScript snippet that would handle the following things for the extension:

• Creating the document.monetization expando
• Modifying document.monetization.state
• Dispatching our monetization events

const script = `
    document.monetization = new EventTarget();
    document.monetization.state = "stopped";

    window.addEventListener("message", function(event) {
      // We only accept messages from ourselves
      if (event.source != window)
        return;

      if (event.data.type === "monetizationEvent") {
        const payload = event.data.event
        event = new CustomEvent(payload.type, { detail: payload.detail });
        document.monetization.dispatchEvent(event);
        return;
      }

      if (event.data.type === "monetizationStateChange") {
        document.monetization.state = event.data.state
        return;
      }
    }, false);
  `;

const scriptElement = document.createElement("script");
scriptElement.innerHTML = script;
(document.head || document.documentElement).appendChild(scriptElement);

An instance for each page

One requirement for our extension was the ability to check multiple pages at the same time because that's how we browse the web.

This presents a challenge because some of the extension's components (background and popup scripts) are "global", theres only one instance of them running. On the other hand, the content script runs an instance per page.

To handle this we made the content script keep all the state and business logic. The popup script would just send data or ask for it using the messaging API.

chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
  if (request.message === "popupFormSubmit") {
    data = request.data;
    data.active = true;
    changeMonetizationState("started");
    dispatchMonetizationStart({ paymentPointer, requestId: sessionId });
    dispatchMonetizationProgress({
      paymentPointer,
      requestId: sessionId,
      assetCode: data.currency,
      assetScale: data.scale,
      amount: data.amount,
    });

    intervalHandler = setInterval(() => {
      if (document.visibilityState === "visible")
        dispatchMonetizationProgress({
          paymentPointer,
          requestId: sessionId,
          assetCode: data.currency,
          assetScale: data.scale,
          amount: data.amount,
        });
    }, data.interval);
  }

  if (request.message === "popupGetValues") {
    sendResponse(data);
  }

  if (request.message === "popupStopPayments") {
    data.active = false;
    clearInterval(intervalHandler);
    changeMonetizationState("stopped");
    dispatchMonetizationStop({
      paymentPointer,
      requestId: sessionId,
      finalized: false,
    });
  }
});

Next Steps

We see a couple of things that we can do to further improve this extension. To name a few:

• Incorporate a bundler to the developing process.
• Add more timing strategies other than a fixed interval.
• Give the option to customize the currency to send.

Issues and contributions are all welcome 😁

Additional Resources/Info

• MDN Browser Extensions
• Chrome Extensions Guide
• Web Monetization Browser Behaviour

Comments

[Dave Foderick]

Cool. Can I use your extension on a badly written monetized site and fake it into thinking I am sending them real money?

Edit: This is actually a serious question, although I was smiling when I wrote it. It seems like a web site that does not do proper validation could get fooled.

[Gustavo Gutierrez]

The extension is configured to only be loaded on pages served on the local machine (localhost, 127.0.0.1, or file://). So technically, no, you can't use our extensions in a deployed site.

With that said, I think it's fairly easy for a technical user to trick a badly written monetized site. The Web Monetization Docs say that the developer has an optional step to verify the payment. But IMO, this shouldn't be marked as optional.

[Jan Z]

wow this is so helpful for those of us late to the game and didn't get a coil demo account. Thanks!