TinyPass Developer's Resources

Getting Started

The basic principles of Tinypass are:

  • Tinypass 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. Tinypass does not place any restrictions on what is and what is not a resource. Resources are always defined by the publisher.

Resources are defined dynamically at the time of request. Consistent with the dynamic nature of the web, resources only need to be defined when they are needed or requested. If the resource does not exist, it will automatically be created.

A resource can contain 3 attributes:

  • ID - A resource ID is a unique string with a maximum length of 255 characters that does not contain any whitespace. The “RID” will 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 Tinypass 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.
  • URL (optional) - This is the URL location where the resource can be found. This will be used by Tinypass to ensure that users have a method to get back to their content following a successful purchase.

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 Tinypass - 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 exposed to the end-user. The end-user will see the more user-friendly 'name' field which is defined when creating a resource.


The Importance of RIDs

Resource 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 disastrous consequences for your website and your users.

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

Be careful when changing RIDs!!!


Access Control

In the world of Tinypass, we're all about access control. The Tinypass 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. Tinypass allows publishers to define access periods however they like, from the simple to the complex Windowed Pricing.

There are only two states to think about when integrating Tinypass. 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. Tinypass 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 Tinypass. 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 a Tinypass button.

Sample Landing Page

My Website.com
Neosho madtom
Neosho madtoms are short-lived fish, only occasionally surviving more than three years. Little is known about the reproductive habits of the Neosho madtom. They are believed to spawn in June and July. In closely related species, eggs are laid under small stones, and the eggs and sometimes young fish are guarded by a parent. Adults will bury themselves in the gravel during the day and come out to feed at night. Larval, aquatic insects are the major food source of Neosho madtoms. The preferred habitat of adult Neosho madtoms is shallow riffles with loose, uncompacted gravel bottoms.....

To continue reading this Premium Article, click the button below to purchase


Basic Pricing

The most basic level of access control grants access to a resource for an unlimited period of time. In this case, once a user purchases a resource they have access to the resource forever.

Certain scenarios will require access be limited based on time, e.g. a 24-hour movie rental, 1 week access to an online magazine, etc. These requirements are controlled by specifying a time period when defining the Multiple Price Options.

For each resource, you can define up to N active price options. These price options provide the following info that is presented to the user:

  • amount - the price of the resource.
  • access period (optional) - period of time the resource is available once purchased.
  • option start time and end time (optional) - the period of time that an offer is available to a user.

The Button and The Ticket

When access is denied a Tinypass button must be displayed so that a user can make a purchase. Buttons are generated by the Tinypass libraries. Tinypass buttons look like the following:

The price on the button is determined by the price of the content you are selling. This occurs automatically when using the Tinypass libraries.

The Ticket

When a user clicks on a Tinypass button, an access ticket is presented to the end-user via a popup. The ticket contains all of the relevant information that was supplied when creating the button. As you can see below, the ticket contains the resource name, pricing, the access period, user information, and your company logo and messaging. You can also specify a short custom caption to appear.

The resource name is displayed in the top header as “Premium Article - 'The Life of Fish'”.

This access ticket contains 2 price options (maximum of 3 allowed):

  1. $1 USD for 24 hours of access
  2. $2 USD for 7 days of access

If a custom caption was set, it would appear above the access period.


Applications

Each Tinypass request must be associated with a specific application. A publisher can create an unlimited number of applications. An application is simply a grouping mechanism in Tinypass. A publisher could set up an application per each website that they administer or they could set up an application for specific areas of the same website.

Each application has a unique AID (application ID) and a unique secret key. Both of these values can be retrieved from the merchant dashboard.


User Reference

Every purchase request and hence every access (as a possible outcome of a purchase request) could be “tagged” with a user reference. User reference (or user_ref) could be a username, email or any other unique ID identifying that user in the merchant's world.

A merchant with its own user base, who requires its users to be logged in before they can purchase access, can tag every Tinypass purchase request with the user_ref string (for example username). The biggest benefit of doing that is that merchant can query Tinypass for user access information via REST API, revoke and modify access attributes.