Getting Started with Resources

The basic principles of Piano are:

  • Piano is a service that provides access control to a resource.
  • Access is granted when access has been purchased.
  • Access to the resource may be limited based on a period of time.

A resource can represent anything: an article, a movie, a blog post, a pdf, access to a forum, access to premium site content, etc. Piano does not place any restrictions on what is and what is not a resource. Resources are always defined by the publisher.

A resource can contain several attributes:

  • RID - A resource ID (or rid colloquially) is a unique string with a maximum length of 255 characters that does not contain any whitespace. The rid must be unique within each application. There is no restriction on the naming conventions used for creating RIDs. Some applications may use URLs, some may use local database reference keys, and others will have some entirely different approach. The resource ID will be used as a unique reference between Piano and the external system.
  • Name - A resource name is a string with a maximum length of 255 characters. This name is the user-friendly display name that corresponds to your resource. This name is what end-users will see when they view their account transaction history.

Resources

Since resources are entirely defined by the publisher, there is no convention for how resources are defined.

Perhaps you run a daily news site where you sell individual articles as well as access to an entire section of premium content.

In the first scenario, you could define the RID as:

  • RID = MySite-Article-2930 - where 2930 corresponds to the reference ID in your system.
  • Name = Working with Piano - user friendly article name.

In the second scenario, you could define the RID as:

  • RID = MySitePremiumAccess - in this case, the RID corresponds to general access to all premium content.
  • Name = Monthly Premium Access Pass - in this case, the RID corresponds to general access to all premium content.

RIDs are not generally exposed to the end-user. The end-user will see the more user-friendly 'name' field which is defined when creating a resource.

(To create a resource in the publisher dashboard, follow this link to dashboard basics).


The Importance of RIDs

Resource IDs (RIDs) are the link between you, your content, and the end-user's purchases. When a user completes a purchase, they have effectively bought access to that RID. Casually changing RIDs can have unintended consequences for your website and your users and should be avoided.

Let's say that you have a popular blog and you are selling access to a certain area of your site. In the first six months of your Piano deployment you use “LocalSportsPremiumAccess” as your RID. Now if you decide to change your RID to “AllSportsPremiumAccess”, all of a sudden all the users that currently have access will no longer have access. Currently active purchases will be denied. A simple solution would be to temporarily check access on both “LocalSportsPremiumAccess” and “AllSportsPremiumAccess” until all the old purchases have expired.


Access Control

In the world of Piano, we're all about access control. The Piano service tells you whether or not a user has access to a resource. The length of access can last forever or can be fixed for 24 hours, 30 days, 2 weeks, etc. Piano allows publishers to define access periods however they like, from the simple to the complex.

There are generally only two states to think about when integrating Piano. Either the user has access or they do not have access. When a user does not have access, it is up to the publisher to define the messaging that appears on the access denied landing page that the user will be directed to. Piano does not make any assumptions or requirements regarding how this page should be designed or displayed. The style and content of the access denied page is left entirely up to the publisher.

When access is granted, the publisher's server will show the content without interference from Piano. In this scenario, your website will look and feel as it always has.

When access is denied, you must redirect the user to a custom, access denied landing page. This page should contain at least the following information:

  • Inform the user that they do not have access to said content.
  • Include content related to the resource such as a blurb, teaser, or the first 5 seconds of a video.
  • Display an offer to subscribe.

Terms

Terms represent the means in which a user can get access to a resource. Piano provides multiple term types. Read more about creating and configuring terms here.

Applications

Each Piano request must be associated with a specific application. A publisher can create an unlimited number of applications. An application is a grouping mechanism in Piano that typically corresponds to a single domain.

Each application has a unique application ID (or aid colloquially), a private key used for encryption, and an API token used for secure communication between your servers and the Piano REST API. Both of these values can be retrieved from your publisher dashboard.