Advanced Paywall Configuration

The Unlock Paywall has a few knobs you can turn to customize the checkout experience

Collecting User Metadata

In some cases, it may be valuable to collect information from purchasers before they purchase a key. For example, you may want to know the email address of all key holders so that you can send updates to them. In that case, you will want to work with user-specific metadata.

To achieve this, add a property called metadataInputs to your configuration object:

metadataInputs: [ /* input fields */ ],

The members of this array should have the following shape:

name: string,
type: 'text' | 'date' | 'color' | 'email' | 'url',
required: boolean,
defaultValue?: 'string',
public?: true,

All fields are required except for public, which defaults to false and defaultValue. Metadata is considered protected by default, so the only people who can view it are the lock owner and the user associated with the metadata. If any metadata should be visible to everyone, mark the public field as true.

If any input has required: true, it will render on the form with a red asterisk next to it and the metadata form will not submit until it is filled appropriately.

Name fields should be unique; if they are not then there may be collisions when storing the data.

The type field maps to a certain subset of HTML <input> types, which influences how the form renders (see image).

In this example, first and last names are required and all other fields are optional.

After the user fills out the form and clicks the Continue button, they will be prompted to sign a message so the data can be verified as coming from then. After they sign, the key purchase will initiate.

Note: you can customize the callToAction value for the metadata form by adding a metadata value to this callToAction object.

Accepting card payments

To be announced soon...

Pessimistic Unlocking

One of the features of the paywall application is that it optimistically unlocks the page. This feature improves the customer experience by immediately emitting the unlocked event when a transaction is sent, as long as the transaction is likely enough to eventually succeed.

In some cases, your application may want to not unlock until the transaction is fully confirmed. For this you should add pessimistic: true to the paywall configuration.

When doing this, you should ensure that your application handles the events such as unlockProtocol.authenticated and unlockProtocol.transactionSent to show valuable feedback to the user. See the Handle Event section on this page.

Providing a custom web3 provider

To be announced...