NAV navbar
JavaScript

Introduction

Welcome to Coil Developer Docs!

Web Monetization

This section describes how to use Web Monetization on your website.

Web Monetization is an open standard. If you want to read the full specification, go to Interledger RFC 28.

In this document we say "Web Monetized" instead of "Coil enabled" but they mean almost the same thing.

If a user is Coil enabled, they are Web Monetized. But a user can be Web Monetized without using Coil. They could be running open source software to support the Web Monetized sites they visit via a crypto wallet (in which case they rely on no companies), or they could be using a future competitor of Coil. We think this is really important to keep the ecosystem healthy.

Meta Tag (Required)

Example Meta Tag:

<meta 
  name="monetization" 
  content="$twitter.xrptipbot.com/Interledger">

In order to Web-Monetize your site, you need to insert a special HTML tag that tells the Coil how to pay you. We call this the Web Monetization Meta Tag.

The tag's name is always monetization.

Including Your Payment Pointer

The tag's content is your Payment Pointer. The Payment Pointer is an identifier you can get from any wallet that supports Interledger. To use Web Monetization, your wallet must support Interledger.

You can think of the Payment Pointer as your routing number for Web Monetization.

Generating a Web Monetization Meta Tag

You don't need to write this tag yourself.

You can copy the Web Monetization Meta Tag from the Creator Settings page of coil.com into your own site's <head>.

Example Site:

<!doctype html>
<html>
  <head>
    <title>Web Monetized Site</title>
    <meta 
      name="monetization" 
      content="$twitter.xrptipbot.com/Interledger">
  </head>
</html>

After adding the <meta> tag your sites <head> setion should look similar to the example site.

Javascript API

If a user visits your page and has Web Monetization enabled, your site can detect that Web Monetization is enabled.

You can access Web Monetization-related events and state through a Javascript API on document.monetization.

This Javascript API is injected by any browser or extension that supports Web Monetization. You don't need to include any files to use this Javascript API.

Monetization State

Check the value of document.monetization.state to see if the user visiting your page is Web Monetized.

There are 3 possible states for Web Monetization.

No Web Monetization

document.monetization === undefined

No Web Monetization

The user does not support Web Monetization, or there is no Web Monetization Meta Tag on the page.

Pending

document.monetization && document.monetization.state === 'pending'

Pending

The user is capable of Web Monetization. Coil is starting to send a streaming payment with Interledger.

If the user is Web Monetized, the document.monetization.state will always begin in this state.

Started

document.monetization && document.monetization.state === 'started'

Started

The user is Web Monetized and Coil is actively streaming payments to your site with Interledger.

It can take a couple of seconds for document.monetization.state to go from pending to started. The events described below can be used to listen for a change in document.monetization.state.

Browser Start

monetizationstart

function startEventHandler (event) {
  console.log(event)
}

document
  .monetization
  .addEventListener('monetizationstart', startEventHandler)

Example event object

{ 
  detail: {
    paymentPointer: "$twitter.xrptipbot.com/Interledger",
    requestId: "ec4f9dec-0ba4-4029-8f6a-29dc21f2e0ce" 
  }
}

The monetizationstart event can be listened to determine when Web Monetization has started. To use it add an event listener to document.monetization.

Event Object

Field Value
paymentPointer String
requestId String

Browser Progress

monetizationprogress

function progressEventHandler (event) {
  console.log(event)
}

document
  .monetization
  .addEventListener('monetizationprogress', progressEventHandler)

Example event object

{ 
  detail: {
    amount: "75673",
    assetCode: "XRP",
    assetScale: 9
  }
}

The monetizationprogress event can be listened to show the current status of the STREAMing payment. To use it add an event listener to document.monetization.

Event Object

Field Value
amount String
assetCode String
assetScale Number

React

The NPM Package react-web-monetization can be used to easily Web Monetize your React App.