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

Web apps

If you are using a Content-Security-Policy configuration in your web app, the first thing to do is to update all relevant HTTP headers or <meta> elements to allow communication with the Colibrio License Server.

HTML

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

If you are not using a Content-Security-Policy, then you don’t need to add any extra headers.

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

Providing License Configuration

When configuring the Colibrio ReadingSystemEngine, you need to provide a licenseApiKey. For native apps you also need to provide a licenseApiSecret. Every time you load a Publication, you need to provide ReadingSessionOptions consisting of a userToken and a publicationToken.

Web

TYPESCRIPT

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

    let readingSessionOptions = {
        // must be a unique token representing a unique user in your system
        userToken: 'unique-user-token', 
        // publicationToken: must be a unique token representing a unique publication in your system
        publicationToken: 'unique-publication-token',
    };
    
    let readerPublication = await readingSystemEngine.loadPublication(
         epubPublication, 
         publicationOptions, 
         readingSessionOptions
    );

Android

Provide the License configuration in your custom Application class.

KOTLIN

class ReaderApp : Application() {
    override fun onCreate() {
        super.onCreate()
        
        ColibrioReaderFramework.setLicenseOptions(
            "your-license-api-key",
            "your-license-api-secret"
        )
    }
}

Provide ReadingSessionOptions when loading a Publication:

KOTLIN

readingSystemEngine.loadEpub(EpubRandomAccessDataSourceLoadConfig(
    publicationDataSource = dataSource, 
    readingSessionOptions = ReadingSessionOptions(
        publicationToken = "unique-publication-token",
        userToken = "unique-user-token"
    )
))

iOS

Provide your License configuration before instantiating the ColibrioReadingSystemView, for example when your application is created in UIApplicationDelegate.application(_:didFinishLaunchingWithOptions:)

SWIFT

try ColibrioReaderFramework.shared.setLicenseOptions(
    licenseApiKey: "your-license-api-key", 
    licenseApiSecret: "your-license-api-secret"
)

Provide ReadingSessionOptions when loading a Publication:

SWIFT

let readingSessionOptions = ReadingSessionOptions(
    publicationToken: "unique-publication-token",
    userToken: "unique-user-token"
)
await readingSystemEngine.loadEpub(
    config: EpubRandomAccessDataSourceLoadConfig(
        publicationDataSource: fileChannelDataSource,
        readingSessionOptions: readingSessionOptions
    )
)

Reading Session

A Reading Session consists of a user token, a publication token, and an origin. It starts after a period of active use, as defined in the License Agreement.

Reading Session Engine Events

For full transparency, the framework always emits Engine Events when the Colibrio License Server evaluates Reading Session data.

The web framework emits these EngineEvents:

licenseReadingSessionStarted
licenseReadingSessionContinued
licenseReadingSessionBlocked

In Android and iOS frameworks, use ColibrioReaderFramework.addOnLicenseEventListener to receive license-related events.

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 by the Licensee to Colibrio that uniquely represents a user license in the Colibrio License Server system.

Publication Token ²

A sequence of alphanumeric characters provided by the Licensee to 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:

CODE

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:

CODE

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.