Skip to main content

OAuth Web Monetization Script

Overview

The Web Monetization API allows web monetized sites to request a stream of very small payments from a user. To facilitate the stream, Coil Members must typically either use a browser that supports Web Monetization natively or install the Coil Extension.

The OAuth Web Monetization (OWM) script lets Web Monetization work in any browser without the need for the Coil Extension. This is especially helpful for users of desktop and mobile browsers that don't support the Coil Extension. When a Coil Member gives your site or app permission to access their account, they are assigned an access token. The token is passed to the script, then the script authenticates to Coil's Interledger connector and begins paying.

tip

If you use the OWM script on your site, we strongly recommend your site also be compatible with standard Web Monetization via Coil's Extension or other Web Monetization providers.

You’ll need to provide a way for Coil Members to authenticate with us. 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]. Once a Coil Member is authenticated, we can start streaming payments.

Before you begin

Before you can use the script, you must have permission to use Coil's OAuth API.

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>

Add init function to your site

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

Get a user's BTP token

When a Coil Member gives your site or app permission to access their account, you'll have access to their 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 /user/btp endpoint.
  3. A btpToken is provided in the User API 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.

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 a Coil Member 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 Member, they may still be web monetized! Check document.monetization.state to determine whether a member 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/main/packages/coil-oauth-scripts