Blog Post

Zombie knocked out by a money bag

JavaScript Monetization API: How to Fund your Human Resistance Cell after the Apocalypse – Part 4

Editor’s Note: Since this book was originally written Coil has stopped operations, which has put implementation of this on hold. That said, the content here should be accurate if/when another company takes up Coil’s mantle.

Continued from Part 3

Monetization States

There’s a new object in the Document Object Model (DOM) hanging off document called monetization. (If you’re unfamiliar with the DOM, objects or events, you can read up on them in JavaScript Basics: Flinging Event, Element, and Object Bombs at Zombie Heads) It’s exposed by the browser or a browser plug-in. And herein is a simple check for whether monetization is possible: if document.monetization is undefined, then the browser doesn’t support monetization. You can then show ads or keep monetized content secret or whatever you want to show to nonmonetized users. 

document.monetization does two fundamental things:

  1. It implements events so that you can react when someone pays you. 
  2. It holds the state of monetization in a read-only property called, you guessed it, state

document.monetization.state can only hold three values: pending, started, and stopped. 

Pending: This means that a monetization process is being attempted and, like the results of the zombie antidote trials, you just have to wait for it to be over. If your meta tag is recognized, pending is the initial value.

Started: It’s raining thousandths of cents on your human resistance cell. Micropayments are being sent to your pockets (well, your wallet/payment pointer).

Stopped: Payments are neither being sent, nor are they being attempted. Stopped will be the initial value until you add the meta tag.

Monetization Events

Because the JavaScript Monetization API implements events, you don’t have to keep checking what monetization state you’re in. There are events that will fire when the state changes. Each of the following events have at least two additional properties beyond the normal event properties: paymentPointer and requestId.

paymentPointer: This is the pointer from your meta tag. 

requestId: This is a unique session id, and it is the same as the monetization ID. RequestIds are alphanumeric and can include dashes.

monetizationpending: This fires when the monetization state changes to pending. You’ll then know that monetization is enabled. 

monetizationstart: This fires when a payment is active. 

monetizationstop: This fires when a payment has stopped. It also contains a property called finalized.

finalized is a Boolean value. If it’s false, then in a surprisingly obvious move by the obvious penguin, it means that the payment isn’t, well, finalized, and it might restart. If it’s true, then the obvious penguin does his job again, and the payment won’t restart. You can also be certain that either the monetization meta tag has been removed or the pointer has changed. 

monetizationprogress: This event object gives the current status of the payment stream. It also has properties for amountassetCode, assetScale, and receipt

amount – the numeric amount of the payment received. 

assetCode – the three-letter designator for the currency the payment is in (e.g., USD, EUR, XRP, etc.)

assetScale – This is how many decimal places are being used. If the currency is USD and the assetScale is 2, then we’re dealing with payments in cents. If the assetScale is 4, we’re dealing in hundredths of cents.

receipt – This holds the amount that was received in this interaction via a base-64 STREAM receipt. It’s generated by the receiver (your wallet payment pointer) and sent to the provider to confirm the amount received. 

Night of the Living Tip:

Base-64 is a way to encode information in an alphanumeric string. It can be used for a variety of things, including putting images in an HTML document.

The STREAM is part of the interledger protocol and contains the cumulative value transferred. (There may be multiple monetization streams per requestID, so this may not be a representation of all moneys sent.)

To Be Continued