OAuth Web Monetization Script

Web Monetization is a proposed API standard that enables a stream of very small payments to be transferred from a sender to a receiver. Visit webmonetization.org for more information about the standard.

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.

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

tip

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).

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

tip

We prefer you use one of our branded Sign in with Coil buttons. If you'd rather use a button of your own design, please run the design by us first. You can contact us at [email protected].

Get a user's BTP token

After a user has linked their partner and Coil accounts, you'll have access to the user's btpToken. The btpToken is required for the script to work.

  1. The OAuth API's /oauth/token endpoint assigns the user an access_token.
  2. The access_token is included in a request to the User API's /user/btp endpoint.
  3. A btpToken is provided in the User API's response.

The token is passed to the script to allow Web Monetization to work on your site without the user installing the Coil Extension. This is key to offering a seamless flow for users to sign up for a Coil Membership and then immediately provide perks, such as removing ads from your site, via Web Monetization.

danger

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

Include the script 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 script. The script is large so the loading is deferred.

danger

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.v7.beta.js" defer>
</script>

Begin Web Monetization using the BTP token

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

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

The init function allows the 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 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.

The script watches for the meta tag and begins payment once one exists.

Refresh the BTP token used by the script

Call the refreshBtpToken function to set a new BTP token for the script.

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

BTP tokens last about 30 minutes, so if you expect Coil 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 script, use the standard Web Monetization JavaScript API to check the monetization state.

info

Even if you can't get a BTP token for a Coil user, they may still be web monetized! Make sure to check document.monetization.state to determine whether a 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.v7.beta.js" defer>
</script>
</head>
<body>
<p>Testing web monetization via coil polyfill using btp token.</p>
<script>
document.coilMonetizationPolyfill.init({ btpToken: 'e0y1...' })
</script>
</body>
</html>

GitHub repo

The script is open sourced at: https://github.com/coilhq/web-monetization-projects/tree/master/packages/coil-oauth-scripts