OAuth Web Monetization

Overview

Web Monetization is a proposed API standard that enables a stream of very small payments to be transferred from a sender to a receiver. Coil uses Web Monetization so that its creators can receive payments when Coil members visit their content. To facilitate the payment stream, Coil members must use a browser that supports Web Monetization, either natively or through an extension.

OAuth Web Monetization (OWM) script lets you add Web Monetization to your site without requiring your users install an extension. The script is available for any site that uses Coil's OAuth.

Coil members sign in to your site using their Coil credentials. Once authenticated, Coil can start streaming payments to you on their behalf.

As a best practice, sites that use the OWM script should still be compatible with standard Web Monetization (via Coil's extension or other Web Monetization providers).

Get a user's BTP token

For the script to work you must have the Coil member's BTP token.

The OAuth API assigns the member an access_token. The access_token is then included in a request to the User API and a btpToken is provided in the response.

The BTP token should be fetched without exposing the access_token to the user's browser.

Add code snippet to include OWM on your site

Add the following code to the <head> section of each page you are monetizing. The code snippet initializes your page's Web Monetization state, then loads in the OWM script. The script is large so the loading is deferred.

The script is in beta. It may still change, so be careful where you use it.

<script>
if (document.monetization) {
document.monetizationExtensionInstalled = true
} else {
document.monetization = document.createElement('div')
document.monetization.state = 'stopped'
}
</script>
<script src="https://cdn.coil.com/coil-oauth-wm.v5.beta.js" deferred>
</script>

Begin Web Monetization with a BTP token

Add the following code to the <body> section of each page you are monetizing.

<script>
document.coilMonetizationPolyfill.init({ btpToken: 'USERS_TOKEN_HERE' })
</script>

The init function allows the OWM script to authenticate to Coil's Interledger connector and begin paying. You'll have to call this on every page load where you want Web Monetization enabled.

The OWM script looks for a <meta> tag in each page's <head> to get the address of where to send payments. You MUST use the standard Web Monetization <meta> tag for this. If there's no Web Monetization tag, we can't send payments. See Webmonetization.org for more details.

The OWM script watches for an inserted meta tag and begins payment once one exists.

Refresh the BTP token used by OWM

Calling the refreshBtpToken function sets a new BTP token for the OWM script.

document
.coilMonetizationPolyfill
.refreshBtpToken('users-token-here')

BTP tokens last about 30 minutes, so if you expect your users to be on a page for longer than that, you should set a timeout and fetch a new BTP token from your backend.

BTP tokens are standard JWTs so you can also inspect them on the client side to determine the token's expiry.

Check monetization state

After you've initialized the OWM script, use the standard Web Monetization JavaScript API to check the monetization state.

Even if you can't get the BTP token for a user, they may still be web monetized! Make sure to check document.monetization.state to determine whether the user is monetized.

Example index.html

<html>
<head>
<meta name="monetization" content="$wallet.example.com/~alice">
<script>
if (document.monetization) {
document.monetizationExtensionInstalled = true
} else {
document.monetization = document.createElement('div')
document.monetization.state = 'stopped'
}
</script>
<script src="https://cdn.coil.com/coil-oauth-wm.v5.beta.js" deferred>
</script>
</head>
<body>
<p>Testing web monetization via coil polyfill using btp token.</p>
<script>
document.coilMonetizationPolyfill.init({ btpToken: 'e0y1...' })
</script>
</body>
</html>