License Setup

The Colibrio Cloud License

In many cases you will have chosen to sign a "pay per use" Cloud License Agreement with Colibrio. With this type of agreement you are billed a periodical fee based on the number of so called Reading Sessions that have been registered by the Colibrio Reader Framework and subsequently sent to the Colibrio License Server.

This Colibrio License Server is an application hosted on a web server operated by Colibrio. The application exposes a web API through which it receives so called License Reading Session data that is sent from all client applications that uses the Cloud Framework distribution.

The License Server is responsible for keeping track of reading system usage. This data is then aggregated to serve as the basis for billing.

Setting up the Reading System code

The first thing to make sure is that you update all relevant CSP headers to allow communication with the Colibrio License Server.

<meta http-equiv="Content-Security-Policy"
          content="...; connect-src https://license.colibrio.com; ..."/>

For more information about the ins and outs of CSP please refer to the MDN documentation https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP

The data described above are represented by in the SDK by the ILicenseOptions type. An object of this type must passed as a parameter to the Reading System Engine's loadPublication method, thus allowing the system to register License Session data when the user starts interacting with the publication.

    
    let readingSystemOptions = {licenseApiKey: 'your-license-api-key'};
    let readingSystemEngine = new ReadingSystemEngine(readingSystemOptions);
    
    let publicationOptions: IEpubReaderPublicationOptions = {
        ...
    };

    // The licenseOptions parameter is only required when you use a Cloud Framework SDK distribution.
    // When evaluating Colibrio you can just fill in any value in these fields.
    // Please refer to the "License Setup" documents in the Developer Documentation for more information.
    let licenseOptions = {
        userToken: 'unique-user-token', // must be a unique token representing a unique user in your system
        publicationToken: 'unique-publication-token' // publicationToken: must be a unique token representing a unique publication in your system
    };
    
    let readerPublication = await engine.loadPublication(epubPublication, publicationOptions, licenseOptions);

Reading Session

A Reading Session is a unit of data comprised of a user token, a publication token and an origin. A Reading Session is started after a period of active use, defined in the License Agreement.

Reading Session Engine Events

To offer complete transparency the framework will always emit Engine Events when the Colibrio License Server has evaluated the Reading Session data.

The following EngineEvents are emitted by the framework:

• licenseReadingSessionStarted

• licenseReadingSessionContinued

• licenseReadingSessionBlocked

License Reading Session Data

The data that is sent to the Colibrio License Server is composed of the following required data fields:

Date/Time stamp ¹

The date and time when the session was registered.

HTTP Request Origin ¹

The origin (protocol, host and port) of the application serving the Product in which the Framework Redistributables are integrated.

Device Token ¹

A generated, randomised token that uniquely represents the specific Product’s installation on a user’s device.

Publication Signature ¹

The publication hash signature. This data is obfuscated by the framework in order to prevent identification.

License Key ²

A sequence of alphanumeric characters provided to the Licensee by Colibrio that uniquely represents this license in the Colibrio License Server system.

User Token ²

A sequence of alphanumeric characters provided to the Licensee by Colibrio that uniquely represents this license in the Colibrio License Server system.

Publication Token ²

A sequence of alphanumeric characters provided to the Licensee by Colibrio to uniquely represent a specific Publication in the Colibrio License Server system.

API Secret ³

A cryptographically secure token provided by Colibrio after the signing of this License Agreement. Only to be used when the Framework Redistributables are embedded in native apps.

¹ Information provided by Framework Redistributables

² Information provided by Licensee

³ Information provided by Licensee when the Framework Redistributables are used in native apps.

Grouping Requests using subdomain

The License Server groups reading system usage by origin by default. This is convenient if you differentiate between clients using domain components such as:

https://nevermoreacademy.jericho.vermont.com/

In the example above request data from Nevermore Academy would be grouped.

Using wildcards

You can also choose to use a combination of specific subdomains and wildcards:

https://vermont.com
https://*.vermont.com
https://jericho.vermont.com
https://*.jericho.vermont.com
https://nevermoreacademy.jericho.vermont.com

Using the above configuration the license server will group as follows:

• All requests to domain vermont.com will be grouped.

• All requests to subdomains of vermont.com will be grouped, except for jericho.vermont.com which will have its own group.

• All requests to subdomains of jericho.vermont.com will be grouped , except for nevermoreacademy.jericho.vermont.com which will have its own group.

Unknown Origin Requests

There are two different ways requests from unknown origins are handled, based on the license configuration. Please contact Colibrio if you wish to change the configuration.

Automatically Block Unknown Origins

With this configuration, all requests from unknown origins will be blocked. You will not be billed for these requests.

Manually Block Unknown Origins

If the Colibrio License Server detects a previously unknown combination of HTTP Request Origin and License Token, Colibrio will send a notification to you. After this you have 15 days to take action and request Colibrio to add the request origin to the Licensee’s list of valid HTTP Request Origins or block any further activity from the origin. After the end of this 15 day period Colibrio assume the origin is valid and add it to the your list of valid HTTP Request Origins and charge for its accumulated usage activity.