The CGP Store is the interface for retailers. Usual tasks are managing users and registering transaction content. A detailed description of the API can be found in Store API.
This section describes the high level workflow of the minimum required steps to make a book available for your customer. There are a number of optional features provided via the store API, but only three steps are required.
As a prerequisite you need the CCID of a protected book. If you package the books yourself via the Back Office API you will receive the CCID from the callback, or from the get status call. If a content distributor does the packaging for you, you will need to access the CCID in some other way, as well as some metadata of the content and the protected content itself.
- Register user
- Generate auth token for device registration
- Register transaction (buy, lend)
Registering a user
Registering a user is done with the API operation Register User. Registering at URMS enables you to register book transaction for this user. The only thing required is a user ID that is unique to your store. The user ID can be the value you are using to identify the customer in your store. If you do not want to share any personal data it can also be a hash value of this ID. You only need to register a user one time.
Generate auth token
This step is required. Every device that contacts the CGP server must be verified as a legitimate device. The app installed on a device will need this token, so an interface must be in place between your store and the reader app that supports exchanging this token. After the app contacts your store to get this token the store must authenticate the user (if this has not been done already) and then the store requests the auth token at the CGP server using the operation Generate AuthToken. This token must be forwarded to the app, so that the app can complete its registration at the CGP server.
Registering a transaction
In this step your software tells the CGP server that a user is allowed to read a certain book. It is done with the operation Buy Book or Lend Store Book. The operation takes the user ID you provided to us during the registration and the CCID (see prerequisites). After successfully executing this operation the user’s app will be able to fetch a license and display the book.
In order to start testing our Store API we need to set up the store account for you on our servers. After the setup we will provide you with the access credentials.
You will need this information:
- Store API endpoint
- API Access Key, or the Store Secret, an encrypted character string that serves as a password to authenticate a store to the CGP Server
- Store ID, a unique code used to identify teh store or library to URMS
The local system administrator will set up your store in the URMS system. Several configuration parameters that can be customized for your store:
|device limit:||A store can place an arbitrary limit on the number of devices that a user can register for a single account. This can be used as a security precaution, so that a user cannot be associated with an excessive number of devices. For example, a store might set a limit of six mobile devices per user, and if a user decides to add a seventh device to an account, that user would be required to deactivate another first. This limit prevents a user from registering dozens or even hundreds of devices for a single account with a store, and thus broadly sharing e-Book content with many other people. If a user reaches the limit he or she must de-register an existing device in Device Management before that user can register a new one.|
|web reading:||Web reading is a the feature to query user rights details via the entitlement API and in a future phase retrieve decryption keys for content. This feature is considered to be less secure for your content than reading via reader apps. For this reason web reading is turned off by default; this will deny all requests to the entitlement API. If you would like to use this feature you need to request turning it on for your store.|
|callbacks:||If you are also uploading content for encryption there is the possibility for callbacks if you use Back Office-API v3 or later. To use callbacks, the endpoint and the callback itself must be configured.|
As only optional feature for user management there is the deleting of an account. The result is that the CGP server will deny all requests from the deleted users.
Detailed documentation on the API can be found at User Management API.
A retailer can revoke a transaction, meaning that the retailer can invalidate a buy or lend transaction of a user. This will make the book unavailable for the user. If the user shared the book with a group, or lent the title to a friend, the transaction will be reverted. Note that if the book was already given or sold to another user, it is not possible to revoke the transaction.
Detailed documentation on the API can be found at Revoke Transaction.
Devices are registered with CGP when creating profiles using the SDK-API. They can also be deleted via the SDK-API. However, if an application is deleted from a device, or if the device itself is lost, the device cannot be deleted using the SDK-API. This can be a problem if the store restrics the number of devices allowed per users. See Store Setup above.
The device management feature of the Store API can be used to list, rename or delete all devices registered for a user account.
Detailed documentation on the API can be found here Device API.
User groups can be used to allow sharing of books, such as for book clubs or college classes. If a user creates a group, that user becomes the group administrator. That user can then add other other users to the group and share any book he or she owns with this group. Any member of a group can read any book shared with the group at the same time; members do not need to wait their turn to read a single copy of a title.
Detailed documentation on this API can be found at User Group API.
Friend to Friend transactions
Some web stores allow users to deal directly with other users. Friend to friend transactions allow the transfer of book rights from one user to another. A user can:
- Lend a book to another user
- Return a borrowed book
- Receive a borrowed book back again
- Give a book to another user
- Sell a used book to another user
Detailed documentation on the API can be found for User to User transactions under Book Transaction API, including Lend Book, Gift Book, Sell Book, and other transactions.
Distributor Managed Content
Distributor managed content involves transactions that can only be completed by the distributor, or the store that provided the content. This is configured for each title during the packaging of the product. If the distributor managed flag is set, then you need to buy or lend the book using the the content distributor’s API. The content distributor will then complete the Buy on Behalf Of or Lend on Behalf Of transaction at the CGP Store API. This will register the transaction on the URMS System. If you try complete a buy or lend transaction for an eBook that is defined as Distributor Managed Content, the URMS System will send you an Access Denied error message.
If you are working with a content distributor that requires all transactions be routed through their distributor API, your store must be configured properly to allow for “On Behalf of” transactions. Setting up this kind of authorization is a manual task and must be completed by a local system administrator.
The Web Reading feature is being released in several phases. In the first phase the Entitlement API has been put in place. This API allows retrieving information about the available books for a user. This information can then be used to decide if a user is allow to read a book online.
Detailed documentation on the API can be found at Entitlement API.
The next phase will include decryption of the protected content and transmitting the content to the client in a secured way.