Shop manual 3.1.4 Issued: 2018-03-27, Axiell Media AB, [email protected]
This document describes how to create an integrated shop using Axiell Media’s platform. Part of the text is technical and is intended for the persons performing the system integration work.
We have made every effort to avoid errors in this manual. Faults or omissions are unintentional and we appreciate if you let us know if you find any. This manual is also available at https://webservices.elib.se/shop/
The manual is not to be redistributed and is only intended for the specific use of integrating with Axiell Media, all other uses are reserved by Axiell Media.
Shop manual 3.1.3 © Axiell Media AB. page 1 Contents Shop manual 3.1.4 ...... 1 Revision history ...... 5 Changes to the Shop API ...... 5 Introduction ...... 6 Background ...... 6 Using this manual ...... 6 Information from Axiell Media ...... 7 Resources ...... 7 Integration process ...... 8 Before you begin the API integration ...... 8 Overview – work flow ...... 8 Importing product information ...... 8 Interpret the product information ...... 8 Completing an order...... 9 Deliver using a digital book shelf (download area) ...... 9 Streaming ...... 9 Digital watermarking ...... 9 Orders for test purposes ...... 10 Launch of the service ...... 10 Audio book formats ...... 11 Audio book samples ...... 11 Ebook formats ...... 12 Ebook samples ...... 13 Web services ...... 13 API consisting of web services ...... 13 List of web service operations ...... 15 Web services used to deliver books ...... 15 Web services used for administration ...... 19 Appendix A - Streaming ...... 20 Flash streaming ...... 20 The Flash player ...... 20 An example of the XML response ...... 20 Http Streaming ...... 22
Shop manual 3.1.3 © Axiell Media AB. page 2 Http Streaming ...... 22 Building an smart phone application...... 22 Work flow ...... 22 Encrypted stream ...... 22 Android streaming module ...... 24 GetStreamingSettings ...... 24 SetStreamingSettings ...... 24 GetBookmarks ...... 26 CreateBookmarks ...... 26 Appendix B – Example of book information ...... 27 Appendix C – Export types ...... 31 Identifiers ...... 31 Book types ...... 31 Languages ...... 31 Date/DateTime ...... 31 Formats ...... 31 Distribution region ...... 31 Book price ...... 33 Promotions – promotional pricing ...... 33 Book list ...... 34 Book availability status and lifecycle ...... 35 Relations – related products ...... 36 Book length ...... 36 Contributor types ...... 37 Categories ...... 37 Supplements ...... 37 Chapter information ...... 38 Error codes ...... 38 Appendix D - Watermarks ...... 39 English ...... 39 Text for customer acknowledgment ...... 39 Information on watermarking technology ...... 39 Swedish ...... 40 Text for customer acknowledgment ...... 40
Shop manual 3.1.3 © Axiell Media AB. page 3 Information on watermarking technology ...... 40 Danish ...... 41 Text for customer acknowledgment ...... 41 Information on watermarking technology ...... 41
Shop manual 3.1.3 © Axiell Media AB. page 4 Revision history Current version is 3.1
Changes to the Shop API Version Date Changes 3.1.4 Added format 404 Streaming http ts (HLS of MP3 wrapped in TS container). 3.1.3 2016-09-06 Removed formats 305 MP3 short files high bitrate, 307 AAC single file, 310 MP3 single file high bitrate, 355 MP3 short files. 3.1.2 2016-02-23 Added “sequenceNumberInSeries” as a relation type and thema as a new category type. 3.1.1 2015-01-23 Added information about the android streaming module 3.1 2013-09-05 Added online and high quality formats. Added GetProduct-calls. Added current price and current status, updated documentation, corrected typos. Reintroduced possibility to download a part of a book, using new format 355 for use in apps. Removed formats mobipocket as well as the 30-minutes mp3 and aac versions. Added epub 3 formats, population starts in near future. 3.0.1 2013-02-19 Fixed typos formatlist etc, added examples and explanations. Md5 summing or not, promotions etc. Populated fields such as future prices, teasers/epub and relations. New BookLength and PublishedDate. Updated documentation for format 402. Added example for create order group checksum generation. 3.0 2012-05-30 Major revision, not backwards compatible. Books in the export have a publication status such as active or inactive, so not all are directly available. Multiple books per call supported. Support for SOAP/REST. Daily differential updates supported. Several other small changes. 2.4 2011-04-29 Added format 13, 17 and 18. 2.3 2010-07-01 Added getShopOrderURL, to be used for existing orders. Several minor functions added. 2.2 2010-06-07 Added format 200. 2.1 2010-05-10 Several minor changes. 2.0 2010-05-05 Initial revision.
Shop manual 3.1.3 © Axiell Media AB. page 5 Introduction
Background
API 1.x Distribution of digital books to shops is one of Axiell Media’s core businesses. The earliest platforms provided a hosted solution where Axiell Media supplied a full web shop with integrated payment functionality.
With growing demand for increased customer control over design and other modifications Axiell Media created an API based solution. We call this an integrated shop.
These first few versions are grouped as API 1.x and are still in use, but rely on download pages hosted by Axiell Media. This service is discontinued.
API 2.x The second version was introduced 2010-05-05 and built on the previous iterations. It delivered support for some new book formats and allowed for a pure API solution without the need for web pages hosted by Axiell Media. This service is being discontinued.
API 3.x The Shop API branch 3.x is a completely reworked solution that allows several new technical advantages, but mainly a host of new business possibilities. (See the revision history.)
By integrating Axiell Media’s Shop API with a web shop you can create a commercial solution and sell digital books to end users.
Axiell Media works closely with web shop providers to allow them to provide our Shop API as a feature to their customers, this can be an alternative to implementing the API on one’s own.
Using this manual This manual is an integration guide that explains how to connect your web solution with Axiell Media’s distribution system for digital books.
The information is intended as a guide, and should not be taken as binding and committing, and can be changed without notice. We have made every effort to maintain an updated and correct document, but if you encounter any errors or omissions, please do contact us citing the document name at [email protected].
"Product" and "book" are used interchangeably in the document.
The API supports both digital audio books and ebooks. Each book is available in one or more formats, such as streaming or downloadable file. Shops obtain information on all titles and available formats via Axiell Media's web services.
The shop maintains customer registers and handles payments for subscriptions. Offline usage is reported to Axiell Media by the shop and online usage is recorded by Axiell Media. This allows for synchronized reading. Axiell Media collects and creates billing information according to the business model. Axiell Media handles payments to the publishers and the Shop receives usage based bills.
Shop manual 3.1.3 © Axiell Media AB. page 6 Information from Axiell Media When the contract is signed, the shop is created in Axiell Media’s systems and you receive login and authentication information to the administrative pages. On the administrative site https://admin.elib.se you will find the service ID and service key, which are needed to access the web services on https://webservices.elib.se/shop/.
Only the services described are supplied; for example, the bandwidth used for the download or streaming is not covered by Axiell Media and customers should be aware that streaming on some platforms may be costly.
Resources Initial documentation – basic information, normally an email describing the service Contract – essential to gain access to the Axiell Media API and the administrative pages Subscription shop manual and API – this document, which gives an overview and includes the web service specification, available with the API on https://webservices.elib.se/shop Administrative site – shop administration with access keys on https://admin.elib.se.
Shop manual 3.1.3 © Axiell Media AB. page 7 Integration process
Before you begin the API integration ✓ Signed contract ✓ Access codes - Use login provided to find service ID and a service key on https://admin.elib.se ✓ List of server IP addresses - All server IPs used to access the API must be reported to Axiell Media for security reasons.
Overview – work flow There are four main functions in the API and some supporting functionality. The main areas are:
• Import and interpret product information - retrieves information about all available books • Completing and delivering an order – create/retrieve an order with links for delivery to the end user.
Importing product information Axiell Media recommends storing all product information in a local database. Book information must be updated at least every 24 hours.
A function for retrieving changed products is available. This change/differential/delta function allows for partial updates by listing all titles that have been added, removed or updated after the specified date. Axiell Media recommends at least one update sometime between 01:00 and 05:00 GMT+1. The web service will always return the most up-to-date information.
Appendix B – Example of book information contains an example export.
Interpret the product information Product information consists of many key parts that together determine if, how and when the book can be made available. Pay particular attention to productID, status and formats.
Details on interpretation and definitions of the types used in enumerations in the export are given in Appendix C – Export types. Much of this information should also be available in the service schemas.
Shop manual 3.1.3 © Axiell Media AB. page 8 Completing an order When you are familiar with the book information and have it imported to a local database, the next step is to make sure you can create orders. You can use this user process as a guide:
1. The user selects a book from the shop’s web site. Available formats are displayed, and if applicable one format group is chosen. (See also the specific chapters on formats below.) 2. Customer payment etc is completed in the web shop, independent of Axiell Media. 3. A call to Axiell Media’s API is made and information is relayed to and registered by Axiell Media. Price at the time of purchase is registered in Axiell Media’s systems. 4. The API returns content information to the shop with one or several links (or other means of accessing the content) that should be placed in the customer’s purchase history in the shop’s system. 5. The customer is then directed to the download area where the links from the purchase history are displayed to allow the user to download the book. The purchase history should be refreshed by calls to GetOrderGroup for up to date information. Normally such updates are made at the beginning of each session.
Deliver using a digital book shelf (download area) All delivery should be done using a download area that provides links to content for the customer only, normally accessed using login.
The time available to download the books is normally not time limited, but Axiell Media recommends that books are downloaded within three months of the order date.
Books no longer available for sale can often still be available for downloads of existing orders.
The number of downloads is not limited, but excessive downloads are not allowed.
DRM formats may have additional limits, such as time limits or a limit on the number of devices, number of downloads etc.
Streaming Streaming is described in the Appendix A – Streaming. Streaming is normally always available for audio books, the formats for online streaming of ebooks is being populated in the near future.
To synchronize position in a book etc, and to make transition between different formats appear seamless to the user, the bookmarks functionality will be extended in the near future as streamed ebook formats are populated.
Digital watermarking Digital watermarks are a way to mark files with information so that they can be individually traced. It can be used to deter infringements on copyrights. When downloading watermarked files from Axiell Media the files are branded with unique information that can be reproduced from the files. The watermark consists of inaudible/undisruptive information of the order number. Watermarking does not affect the file format and does not obstruct download or use. The watermark is intended as a deterrent to illegal copying and distribution of the material. Text material normally has a visible watermark as well as a hidden one.
The shop is obliged to inform their customers that the files are watermarked. A suitable text is available in Appendix A – Watermarks.
Shop manual 3.1.3 © Axiell Media AB. page 9 Orders for test purposes During the setup the shop is allowed to make orders to verify that the access between Axiell Media and the shop is working. The shop is responsible for canceling all such orders the same day as they are made. This is done via the shop administration on https://admin.elib.se. Orders that are not canceled will be charged in full. No web service is available for canceling orders at the moment.
Launch of the service The shop notifies Axiell Media at which date the shop goes public and which URL the shop uses to that Axiell Media can link to it. Preferably the shop should also allow for dynamic linking to a specific book, based on the book or product id. For example http://www.yourshopname.com/isbn/9789100130787
When the shop is made public, cancelation of orders can only be done if the order can be seen as failed due to technical or other issues.
Do not hesitate in contacting Axiell Media to receive further information and help with the integration.
Shop manual 3.1.3 © Axiell Media AB. page 10 Audio book formats Each audio book can be published in a number of formats. Orders are always placed on a format group ID which grants access to one or more formats for the customer. The format group to use for audio books is generally format group 300, which groups all normal audio book formats.
Axiell Media recommends, but the publisher decides, in which formats each book should be produced. This is normally governed by suitability and rights. Book downloads are made available by time limited links, which can be renewed by web service calls. Commonly used formats are watermarked downloads and streaming. All formats have the same content, though it may be accessed or subdivided differently depending on the format.
Format group Format Description Format IDs included group ID All audio book 300 All normal formats for audio books that Axiell 302, 303, 401, 402, 403 formats Media supply for distribution to shops.
Format Format Description ID Mp3, zipped 302 Audio book available for download as mp3, normally divided into several files. Delivered as a link to short files a single zip file. Mp3, single 303 Audio book available for download as mp3. Delivered as a single mp3 file. Recommended format. file Streaming 401 Streaming using Flash. The shop links to a signed flash-player from Axiell Media on its site. The Flash format works on Windows, Mac and Linux operating systems. As for all formats the bandwidth used for the download or streaming is not covered by Axiell Media and customer should be aware that streaming on some platforms are costly, this solution is intended for streaming to computers. Streaming 402 Streaming using http. Streaming to devices supporting Apple HTTP Live Streaming, for example http iPhones, iPads and iPods. This format is recommended when streaming to an iOS device. Use of this format requires a retailer-specific client/app for the above mentioned platforms. Axiell Media does not supply any services for client construction at this moment, but will assist in supplying test streams, web services etc. necessary for integration. More information on this streaming technology can be found at: http://developer.apple.com/iphone/library/documentation/networkinginternet/conceptual/strea mingmediaguide/introduction/introduction.html Online 403 Streaming using an Html5-based player provided by Axiell Media. streaming http Streaming 404 Streaming using http. Streaming to devices supporting Apple HTTP Live Streaming, for example http ts android devices. This format is recommended when streaming to an Android device. Use of this format requires a retailer-specific client/app for the above mentioned platforms. Axiell Media does not supply any services for client construction at this moment, but will assist in supplying test streams, web services etc. necessary for integration. More information on this streaming technology can be found at: http://developer.apple.com/iphone/library/documentation/networkinginternet/conceptual/strea mingmediaguide/introduction/introduction.html
Audio book samples
Teasers Each audio book normally has a portion of the book available as a teaser for the content. Teasers are available as links to mp3 files.
Shop manual 3.1.3 © Axiell Media AB. page 11
Ebook formats Each text-based ebook can be published in a number of formats. Orders are always placed on a format group ID which grants access to one or more formats for the customer. The format group to use for ebooks is generally format group 100, it groups all normal ebook formats.
Axiell Media recommends, but the publisher decides, in which formats each book should be produced. This is normally governed by suitability and rights. Books are made available by time limited links, that are renewed by web service calls. Watermarking technology is used to allow greater freedom for the user. Copy protected formats are used with specific software on specific platforms and impose certain technical limitations on the user.
Most books are created in epub format, though books with rich illustrations may be better suited by the pdf format. Books with mainly text can be made available in most formats. Ebooks can be read on many platforms such as computers, tablets, smart phones and ebook readers.
Format group Format group ID Description Format IDs included
All ebook formats 100 All text based ebook formats that 101, 102, 103, 104, 105, 106,
can exist and be sold for a shop. 107, 110, 114, 115, 116, 1101, 1102
Format Format ID Description PDF without DRM 101 PDF distributed without drm. Works on any device that can read pdf files. Can be read
using free software such as acrobat reader. Software is included on many ebook readers. PDF with 102 Pdf distributed with watermark. Can be read using free software such as acrobat reader.
Watermark Works on any device that can read pdf files. Software is included on many ebook readers. PDF distributed with license encryption. Must be read using Adobe Digital Editions or PDF with Adobe 103 Encryption compatible software. Epub without DRM 104 Epub distributed without drm. Can be read on any device which support epub files.
Software for reading the files range from web browsers to specific software included on ebook readers. Epub distributed with watermark. Can be read on any device which can read epub files. Epub with 105 Watermark Software for reading the files range from web browsers to specific software included on ebook readers. Recommended format. Epub with Adobe 106 Epub distributed with license encryption. Must be read using Adobe Digital Editions or
Encryption compatible software. Enhanced Epub 107 Enhanced EPUB contains rich media – for example audio or video. Software suitable for
with Watermark reading enhanced EPUB is specified for each book title. Epub 3 without 114 Epub 3 distributed without drm. Can be read on any device which support epub files.
DRM Software for reading the files range from web browsers to specific software included on ebook readers. Epub 3 distributed with watermark. Can be read on any device which can read epub files. Epub 3 with 115 Watermark Software for reading the files range from web browsers to specific software included on ebook readers. Epub 3 with Adobe 116 Epub3 distributed with license encryption. Must be read using Adobe Digital Editions or
Encryption compatible software. Epub streamable 1101 Streaming using an Html5-based player provided by Axiell Media. Epub based.
Pdf streamable 1102 Streaming using an Html5-based player provided by Axiell Media. Pdf based.
Shop manual 3.1.3 © Axiell Media AB. page 12 Ebook samples
Teasers Each ebook normally has a portion of the book available as a teaser for the content. There are a number of formats that the teasers can be in.
• a link to the teaser including a player/viewer, or a file for download • the text content itself • sometimes split in html and css
Some books have a downloadable epub with approximately 10% of the content. These will be delivered as a link to the epub-file that you can link to or redistribute to your customers.
Example:
Web services
API consisting of web services The API has been developed to allow shops to integrate Axiell Media’s distribution platform closely with an existing web shop. Not all parts of the API are necessary for all types of use, e.g. a shop that only sells audio books naturally will not need the ebook features.
The main feature of the API is the web services, which can be used to create a functional solution. Documentation is also a central part. Controlled and legal distribution of files and information is the main goal of the API.
All web services are available at https://webservices.elib.se/shop. Detailed documentation for each web service is available there with examples. This document in its most updated form can also be found there. Most of the API should be self-explanatory; the following is to make give an overview.
Each web service contains a security validation of usage. A service ID and a service key from Axiell Media are required to use each web service. The service key is used to create an MD5 checksum to authenticate the request made by the shop.
For each service operation the manual specifies:
• Description Contains a short description of the web service and its purpose. • Parameters The web services can be called using post requests, for example SOAP. • Example A basic example is included as part of the web service for each service, partly on the service page.
Schema: Only basic schemas are available at the moment. See for example https://webservices.elib.se/shop/v3.1/soap12
Shop manual 3.1.3 © Axiell Media AB. page 13 Error message: The status in the response is particularly important and status 0 is OK. Other codes represents errors or warnings and should be handled by you system. Some possible responses are listed in Appendix C under Error codes.
Shop manual 3.1.3 © Axiell Media AB. page 14 List of web service operations If you are using SOAP, the WSDL is located at https://webservices.elib.se/shop/v3.1/soap12. The urls that follow each operation is the REST path.
Web services used to deliver books
GetProducts GET https://webservices.elib.se/shop/v3.1/products
Description Retrieves a list of products. Can be used for nightly imports to a local database. A full import can be done by requesting all books from 2000-01-01. A full import can be done or a differential update for example all changes since last import. A full or incremental update must be done at least every 24hours.
Parameters ServiceID Integer Unique ID identifying the shop provided by Axiell Media. ServiceKey String Unique code for the shop provided by Axiell Media (encoded as MD5- sum). From Datetime Start of the period for product export. Based on when the book was added to the shop range or when book or its metadata changed. To Datetime End of the period. If this is null, todays date is used. Observe that products that change multiple times are only listed for the period containing the latest change.
Example https://webservices.elib.se/Shop/v3.1/xml/metadata?op=GetProducts
The returned xml contains bookid, title, description and all available formats as well as other information about each book. Every book typically also has links to cover images that can be fetched to a local web server. They are normally of size 600x800, 500x500, 200x200 or 100x100. Links to teasers/trailers can also be found for most books.
Appendix B – xml export format contains an example response.
GetProduct GET https://webservices.elib.se/shop/v3.1/products/{ProductID}
Description Retrieves the product specified.
Parameters ServiceID Integer Unique ID identifying the shop provided by Axiell Media. ServiceKey String Unique code for the shop provided by Axiell Media (encoded as MD5- sum). ProductID Integer Unique ID identifying the product.
Shop manual 3.1.3 © Axiell Media AB. page 15 CreateOrderGroup POST https://webservices.elib.se/shop/v3.1/ordergroups
Description Creates an order group, consisting of one or more orders/products. A call is considered a buy-order between the shop and Axiell Media at the price listed in Axiell Media’s product export. Each format group used to create the orders delivers results specific to the formats in the format group. Reuse of an OrderGroupID will return a warning, the existing order group is also returned.
Parameters ServiceID Integer The unique ID identifying the shop. ServiceKey String The unique code for the shop (encoded as MD5 checksum). OrderGroupID String The shop’s own ID for the complete order. Products Array Array of products (described below). Checksum String MD5 of the following: ServiceID + OrderGroupID + ([ProductID + FormatGroupID] for each product in the Products array) + ServiceKey (the original value of your key)
A product is an object that contains the following properties ProductID Integer Axiell Media’s ID for the product. FormatGroupID Integer Axiell Media’s ID for the format group. * ShopOrderID String Optional ID for the specific product in the group. * PromotionID Integer Optional campaign ID (prefix) which will pick the corresponding manual promotion price for the product. * ActivationKey String Optional for all but format groups containing books in Mobipocket format, in which case it needs to contain the customer’s PID. Example https://webservices.elib.se/Shop/v3.1/xml/metadata?op=CreateOrderGroup
Example of building the checksum: Given ServiceID 9999, ServiceKey abcdef, OrderGroupID 12345, ProductID 1002445 and FormatGroupID 100, the checksum string would be:
9999123451002445100abcdef
And the md5sum of that would be:
c76f88a65ba5b095f4741812b2c95174
Shop manual 3.1.3 © Axiell Media AB. page 16 GetOrderGroup GET https://webservices.elib.se/shop/v3.1/ordergroups
Description Retrieves an existing order group using the same ID as when it was placed, or the ID designated by Axiell Media in the create response.
Parameters ServiceID Integer The unique ID identifying the shop. ServiceKey String The unique code for the shop (encoded as MD5-sum). OrderGroupID String The shop’s own ID for the complete order. IsElibID Boolean Specifies if the supplied OrderGroupID is an ElibID or not.
Example https://webservices.elib.se/Shop/v3.1/xml/metadata?op=GetOrderGroup
Shop manual 3.1.3 © Axiell Media AB. page 17 GetFormats GET https://webservices.elib.se/shop/v3.1/formats
Description Retrieves a list of format groups and formats.
Parameters This request requires no parameters.
Example
https://webservices.elib.se/Shop/v3.1/xml/metadata?op=GetFormats
GetCategories GET https://webservices.elib.se/shop/v3.1/categories
Description Retrieves a list of categories with category types and descriptions.
Parameters This request requires no parameters.
Example https://webservices.elib.se/Shop/v3.1/xml/metadata?op=GetCategories
Shop manual 3.1.3 © Axiell Media AB. page 18 Web services used for administration The services are intended as a supplement for those that do not use the administrative functions on admin.elib.se, and that do wish to automate the use of the business information that they can supply.
GetBillingList GET https://webservices.elib.se/shop/v3.1/billings
Description Retrieves a list of billing IDs for use with the GetBilling-operation shown below.
Parameters ServiceID Integer The unique ID identifying the shop. ServiceKey String The unique code for the shop (encoded as MD5-sum). Start Datetime Start of the period for the billing list. End Datetime End of the period.
Example https://webservices.elib.se/Shop/v3.1/xml/metadata?op=GetBillingList
GetBilling GET https://webservices.elib.se/shop/v3.1/billings/{BillingID}
Description Retrieves the chosen billing.
Parameters ServiceID Integer The unique ID identifying the shop. ServiceKey String The unique code for the shop (encoded as MD5-sum). BillingID String ID of the billing.
Example https://webservices.elib.se/Shop/v3.1/xml/metadata?op=GetBilling
GetSalesStatistics GET https://webservices.elib.se/shop/v3.1/sales
Description Retrieves sales statistics for given period.
Parameters ServiceID Integer The unique ID identifying the shop. ServiceKey String The unique code for the shop (encoded as MD5-sum). Start Datetime Start of the period for the statistics. End Datetime End of the period.
Example https://webservices.elib.se/Shop/v3.1/xml/metadata?op=GetSalesStatistics
Shop manual 3.1.3 © Axiell Media AB. page 19 Appendix A - Streaming
Flash streaming
The Flash player A Flash player is used for streaming. The player is provided by Axiell Media, a generic Elib Flash Player.
The web service createShopOrder returns the following for format 401: • url • code (html for integration)
This can be integrated on a web page to stream the audio book in the player. It is written in Adobe Flash and presents the user with an easy to use interface for listening to, and navigating within, the audio book. It can be popped up in a separate window, opened in a new tab, or integrated into a web page.
The player size is 388x164 and it looks like this:
A modified player, with a new skin, can be developed to suite the shop further for a fee.
An example of the XML response
Shop manual 3.1.3 © Axiell Media AB. page 21 Http Streaming
Http Streaming Http streaming demands more in terms of development from the shop as they have to build the receiving software or app.
The main use is for Android and IOS devices, as well as other platforms that do not have support Flash.
For some players we have found that it is better to wrap the chunk in a TS container. Especially with some of the JavaScript- and Android players available.
We recommend using format 402 for iOS and format 404 for Android.
The http stream is a HTTP Live streaming stream with AES-128 Media Encryption.
Building an smart phone application For information on the client side integration see for example: http://developer.apple.com/iphone/library/documentation/networkinginternet/conceptual/streami ngmediaguide/introduction/introduction.html
Work flow Normally the following steps are made when using the http-streaming:
1. Available titles are the ones with format 402. 2. CreateShopOrderGroup or GetShopOrderGroup has the link in the node for format 402. 3. Application specific actions are taken. Such as: • Generating m3u8 links (Encryption parameters are added see section Encrypted Stream). • Downloading playlist files. • etc. 4. GetStreamSettings is called to determine the position in the book 5. SetStreamsettings is called at intervals of for example 30 seconds during play to store and update position in the book.
Encrypted stream To play an encrypted stream you need to add extra parameters to the links that you receive in the responses. The parameters are:
GMT: current time in GMT/UTC-tid, in the format YYYYMMDDHHMM, for example 201009141200 Checksum: MD5-checksum of ServiceID + ProductID + FormatID + GMT-parameter above + ServiceKey ServiceKey: The unique code for the shop (encoded as MD5-sum).
An example of a complete link would be:
Shop manual 3.1.3 © Axiell Media AB. page 22 http://delivery- 4.elib.se:1935/api3shop_AES_ext/_definst_/ISBN9164232514/mp3_single_file/mp3:hundraaringen_ som_klev_ut_genom_fonstret_och_forsvann.mp3/playlist.m3u8?ServiceID=919&ProductID=100654 0&FormatID=402&ServiceKey=fb375889f2ff96c3b18408133ad9a96b&GMT=20130219100&Checksu m=c54ad1b4630a42cc99d19bfb1a11efe3
Shop manual 3.1.3 © Axiell Media AB. page 23 Android streaming module While streaming on Android is not as easy as it is on IOS, Axiell Media has a streaming module for Android that makes streaming HLS easier. For more information about the module and how to acquire it, contact [email protected]
GetStreamingSettings GET https://webservices.elib.se/shop/v3.1/streamingsettings
Description Fetches a user’s (order’s) position within a book, volume setting and rating. Parameters ActivationID: ID for settings Example HTTP + XML response
HTTP/1.1 200 OK Content-Type: application/xml Content-Length: length
101
SetStreamingSettings POST https://webservices.elib.se/shop/v3.1/streamingsettings
Description Sets a user’s (order’s) position within a book, volume setting and rating. Parameters ActivationID: Checksum; Position; ProductID; Rating; Volume; ServiceID; ServiceKey; Example HTTP + XML response HTTP/1.1 200 OK Content-Type: application/xml Content-Length: length
Shop manual 3.1.3 © Axiell Media AB. page 24 101
Shop manual 3.1.3 © Axiell Media AB. page 25 GetBookmarks GET https://webservices.elib.se/shop/v3.1/bookmarks
Description Retrieves a list of bookmarks. Parameters ActivationID: ProductID; ServiceID; ServiceKey; Example HTTP + XML response HTTP/1.1 200 OK Content-Type: application/xml Content-Length: length
101
CreateBookmarks POST https://webservices.elib.se/shop/v3.1/bookmarks
Description Creates a user specific bookmark for a product. Also returns the actual bookmark data. Parameters ActivationID: Checksum; Description; Position; ProductID; ServiceID; ServiceKey; Example HTTP + XML response HTTP/1.1 200 OK Content-Type: application/xml Content-Length: length
101
Shop manual 3.1.3 © Axiell Media AB. page 26 Appendix B – Example of book information All available information on the products (books) are delivered via the web service GetProducts. Here is an example of the exported metadata in xml format.
The example contains two products, one audio book and one ebook.
0
Shop manual 3.1.3 © Axiell Media AB. page 27
Shop manual 3.1.3 © Axiell Media AB. page 28
Shop manual 3.1.3 © Axiell Media AB. page 29
Shop manual 3.1.3 © Axiell Media AB. page 30 Appendix C – Export types
Identifiers To maintain data integrity and ensure that product updates are applied to the correct product, all data processing should be made using the products id provided by Axiell Media. Each product is also supplied with at least one public identifier, normally an ISBN. There can be multiple public identifiers, but normally not and they are normally only applicable in specific contexts. The public identifier/identifiers that you use (ISBN) should be the identifier used for all purposes, except for data synchronization and placement of orders with Axiell Media, in which product id should be used. The created and updated dates supplied with the product id signifies changes to the product, either the metadata or the data.
Book types Product type ID Name, English Name, Swedish 1 E-book Ebok 2 Audiobook Ljudbok
Languages The language of the content in the product is described using language codes from the standard ISO 639-1. Books in Swedish are marked as “sv”.
Date/DateTime Dates are normally given in ISO 8601. For example 2001-02-03T04:05 for a date with time and 2001- 02-03 for a date. When dates are included in checksums they are always represented with time for example 2001-02-03T04:05.
Formats Each book has a list of available formats that are used to inform the customer prior to purchase. The orders are placed on format groups and they state which of the availiable formats the customer actually bought and will gain access to. They are often identical.
See the detailed descriptions in the Audio book formats and Ebook formats sections.
See also the web service GetFormatList which retrieves a list of format groups and formats with names and descriptions for format and format groups in Swedish and English.
Distribution region Books can have regional limits on distribution. The list of allowed regions that the book can be sold to is included with the exported information. The shop is obliged to enforce such regional limits. Valid regions are: • Sweden • Norway • Finland • Denmark
Shop manual 3.1.3 © Axiell Media AB. page 31 • Nordic countries, distribution to Sweden, Norway, Finland, Denmark and Iceland • EU, distribution to the European Union allowed • Default, worldwide distribution allowed
A book can have multiple allowed distribution regions.
Shop manual 3.1.3 © Axiell Media AB. page 32 Book price Current price excluding taxes will always be available per book in the exported information. Upcoming price changes will be available as extra information stating a start date and the new price. Price updates will be available as soon as we have them, but we request changes from publishers with notice to allow for the updates, giving you a window to change the price when you fetch the information updates. Price changes will generally occur at midnight. The following show current as well as some future prices. You need to update the information daily as it may change. Example:
Current price To facilitate the current price at the time of the export a CurrentPrice node is made available. It calculates the lowest current price available applying any automatic promotions. Example of current price:
To find the price you need first decide if you are using a manual promotion, for example if you have a page using promotional coupons.
If it is not a manual promotion find the lowest of any automatic promotion or the standard price for the current time. This is the price that will be used on the order if you do not apply a manual promotion ID.
Shop manual 3.1.3 © Axiell Media AB. page 33
Book list The full set of products available to the shop is determined by the groups that the shop is subscribed to. Available sets are: • SE-range - typical set for a shop targeting the Swedish market • FI-range - typical set for a shop targeting the Finnish market • NO-range - typical set for a shop targeting the Norwegian market • I - International market - typical set for a shop targeting the international market • List of publishers - giving access to all present and future books from the specified publishers • List of books - static book list All sets that comply with the criteria are updated dynamically when new books are added, except for the static book list. Each shop can subscribe to several sets. Which lists Axiell Media can make available to a specific shop is determined by the publishers. The sets can overlap and are in part determined by the publishers.
To allow for books to belong to particular subscription ranges (and potential different payment schemes), for example “detective stories” or “children’s books”, range groups are added to all books. Initially, they will only be populated with “base”-range which includes all books. Example of range group:
Shop manual 3.1.3 © Axiell Media AB. page 34 Book availability status and lifecycle Book information will be available for both deliverable books and non-deliverable books. Books can have only one current status but several instances of both upcoming and historical statuses. To allow for this a time period is given for each status. Periods do not overlap, but the first and last can be open ended. Each status type can occur multiple times.
Information is made available by Axiell Media’s web service and the shop is responsible for keeping this information up-to-date.
• active, the product is available for sale • inactive, the product is not available for sale but can be downloaded by customers with existing orders (those who already bought it) o the book is considered upcoming, if the book has a set publication date. It will then appear with status inactive, but also active status with a later date. o otherwise the title is considered not available, (the book has no activation date) • deleted, the product is no longer available, not for sale and not for existing orders
At all times the current information will be delivered, but a best known information on future price changes and coming titles will also be made available.
Statuses and the dates provided can be interpreted as release dates, which are different from the product change date which describes metadata or data changes that are made to the product; this is independent from statuses and not considered a new release date. (However a status change will trigger a new change date on the product.)
Current status To facilitate the current status at the time of the export, a CurrentStatus node is made available. Example of current status:
Publication date As a convenience, the first date on which the book was/will be published to subscription shops is included separately. This date however should not be taken as a guarantee that the product can be delivered, use it only for information purposes. Example:
The date the book first was published digitally for single copy delivery:
Shop manual 3.1.3 © Axiell Media AB. page 35 Relations – related products Some relations for the product are included. A relation is a typed connection between the product and another product. The connection is typically made on product ID, but can also be on ISBN or other IDtype. Relation types are: Relation type Description correspondingPaperBook Normally the digital book is made based on a printed one. A relation based on ISBN is sometimes available to that book. correspondingEbook If the audio book has an ebook with the same content this is normally referred to using product ID. correspondingAudiobook If the ebook has an audio book with the same content this is normally referred to using product ID. nextInSeries If the book is part of a series the next book in the series can be referred to here. previousInSeries If the book is part of a series the previous book in the series can be referred to here. partOfSeries If the book is part of a series this refers to the name, or possibly object, that describes the series. sequenceNumberInSeries If the book is a part of a series this is the order in the series, if such exists.
The products relations might not cover all relations imaginable. Several relations of the same type are allowed but do normally not exist.
Example:
Book length For audiobooks normally seconds and for ebooks ”pages”. Examples:
The length in seconds should be rounded to minutes, or possibly even rounded to nearest ten minutes.
An approximation might be available for the digital book given in pages even though pages might not be relevant for the format distributed.
Shop manual 3.1.3 © Axiell Media AB. page 36 Contributor types This is a dynamic list, so expect additions. Additions are however rare.
ID English Swedish 1 author författare 2 co-author medförfattare 3 translator översättare 4 illustrator illustratör 5 narrator uppläsare 6 photographer fotograf 7 editor redaktör 8 co-editor medredaktör 9 cover omslag 10 music musik 11 song sång 12 sound effects ljudeffekter 13 adapter bearbetare 14 designer designer
Categories Several category types are allowed in the exported information. The category type and a category value are given for each entry. See webservice GetCategoryList which retrieves a list of category codes. The populated subject category is typed as Elib. Subject category types BIC and SAB are planned. A category for age groups is also planned, but not yet populated, the Age group type. Axiell Media recommends that you implement the categories you wish to use and ignore the rest. Axiell Media will introduce new category types and this should preferably not break your implementation, so make sure to allow but ignore type you do not wish to have.
Category type ID Category type 1 Elib 2 BIC 3 SAB 4 Age group 5 SubjectWords 7 Thema Supplements To each book supporting material can be included in the delivery. This is material normally only available to customers who have bought the book and it can/could be individualized/watermarked. (In contrast cover images and teaser are considered advertisements for the book and they are available prior to purchase.)
An audio book could for example include an image, a text document or a zip-file with various materials. Such supplements will be available in the supplements part of the order response. Some compressed/zipped formats will supply these files as part of the package, but Axiell Media recommends that the specific link or links to supplements are made available separately as well.
For each supplement a link and a name is supplied.
Shop manual 3.1.3 © Axiell Media AB. page 37
Chapter information In the exported info some books have a table of content (TOC) which lists chapters in the book. This is information typically only used in conjunction with streaming of the book. Each chapter is supplied with a name, start, sequence number, type (chapter or not, that is if sequence number is relevant).
Error codes Response codes Description 0 RequestOk 50 OrderGroupExists 101 ServiceKeyMissing 102 ServiceKeyNotValid 103 PeriodNotValid 104 BillingIDMissing 105 ProductFormatMismatch 106 ChecksumNotValid 107 ErrorSavingOrders 108 ServiceNotRetailer 109 InactiveFormats 110 ShopCannotSell 111 ProductInactive 112 OrderGroupDoesNotExist 113 OrderIsInactive 114 OrderGroupIDNotInt 115 ErrorSavingStreamingSettings 116 StreamingSettingsDoesNotExist 117 ErrorSavingStreamingBookmark 123 InvalidIDType 124 ErrorNoBookForID 125 InvalidISBN13 129 PriceMissing 130 InvalidPromotionID 900 CriticalExceptionThrown
Shop manual 3.1.3 © Axiell Media AB. page 38 Appendix D - Watermarks When distributing watermarked files the shop is (as for all orders) responsible for storing information about the customer. The shop is also obliged to inform their customers that the files are watermarked. Suitable texts in some languages are included. Two texts are provided, one which the customer acknowledges and one with information about the technology.
English
Text for customer acknowledgment Digital watermark This website uses digital watermarks. Please read and approve the information about digital watermarks here, before you proceed to checkout. I have read the information and accept that the book is watermarked.
Information on watermarking technology • Specific text for ebooks. This book is watermarked! Digital watermark is a way to protect copyrighted material. Downloaded ebooks will be watermarked with information containing your order number. Watermarks do not affect the file format and do not obstruct download or use of the book. The watermark validates that the book you download belongs to you. All copyrights are reserved except for personal use, and further distribution is prohibited. You are personally responsible for assuring that the book is not spread to other users. If the book is found elsewhere, for example on a file sharing site, it is possible for us to decode the watermark information in the file and trace it back to your order number. Watermark remains on copies of the book. • Specific text for audio books. This book is watermarked! Digital watermark is a way to protect copyrighted material. Downloaded audio books will be watermarked with information containing your order number. The watermark consists of inaudiable information in the sound, containing you ordernumber. Watermarks do not affect the file format and do not obstruct download or use of the audiofiles. The watermark validates that the audio files you download belongs to you. All copyrights are reserved except for personal use, and further distribution is prohibited. You are personally responsible for assuring that the book is not spread to other users. If your audiofilkes are found elsewhere, for example on a file sharing site, it is possible for us to decode the watermark information in the file and trace it back to your order number. The watermark remains even if the audiofiles are moved from one device to another.
Shop manual 3.1.3 © Axiell Media AB. page 39 Swedish
Text for customer acknowledgment Digital vattenmärkning
Denna webbplats använder digital vattenmärkning. Innan du går vidare med ditt köp behöver du ta del av och godkänna informationen om digital vattenmärkning här. Jag har läst informationen och accepterar att min bok vattenmärks.
Information on watermarking technology • Specific text for ebooks. Denna bok är vattenmärkt! Digital vattenmärkning är ett sätt skydda upphovsrättsligt material. Vid nedladdning av e-bok med vattenmärke kommer filen att förses med information innehållande ditt ordernummer. Vattenmärkningen påverkar inte filformatet och försvårar varken nedladdning eller användning av filen. Vattenmärket visar att e-boken som du laddar ned tillhör dig. All kopiering, utöver för ditt privata bruk, och otillbörlig vidarespridning är förbjuden. Du är själv ansvarig för att e-boken inte sprids vidare till annan användare. Om din e-bok hamnar på avvägar, t ex på en fildelningssajt, kan vi med hjälp av en avkodare få fram ditt ordernummer. Vattenmärkningen kvarstår vid kopiering av e-boken. • Specific text for audio books. Denna bok är vattenmärkt! Digital vattenmärkning är ett sätt skydda upphovsrättsligt material. Vid nedladdning av denna MP3-bok kommer ljudfilerna att stämplas med ett digitalt vattenmärke. Vattenmärket består av ej hörbar information i ljudet, innehållande ditt ordernummer. Vattenmärkningen påverkar inte filformatet och försvårar varken nedladdning eller användning av ljudfilerna. Vattenmärket visar att ljudfilerna som du laddar ned tillhör dig. All kopiering, utöver för ditt privata bruk, och otillbörlig vidarespridning är förbjuden. Du är själv ansvarig för att ljudfilerna inte sprids vidare till annan användare. Om dina ljudfiler hamnar på avvägar, t ex på en fildelningssajt, kan vi med hjälp av en avkodare få fram ditt ordernummer. Vattenmärkningen kvarstår även om ljudet spelas över från en enhet till en annan.
Shop manual 3.1.3 © Axiell Media AB. page 40 Danish
Text for customer acknowledgment Digital vandmærkning
Denne hjemmeside anvender digital vandmærkning. Inden du går videre med dit køb skal du læse og godkende informationen om digital vandmærkning her. Jeg har læst informationen og accepterer at min bog vandmærkes.
Information on watermarking technology • Specific text for ebooks. Vandmærkning af e-bøger Digital vandmærkning er en måde at beskytte ophavsretligt materiale på. Når du køber og downloader e-bøger bliver filerne stemplet med et digitalt vandmærke. Vandmærket består af information i filerne, indeholdende dit ordrenummer. Vandmærkningen påvirker ikke filformatet og besværliggør hverken download eller anvendelse af lydfilerne. Vandmærket dokumenterer at de filer du downloader tilhører dig. Al kopiering, udover til dit private brug, og yderligere uretmæssig spredning er forbudt. Du er selv ansvarlig for at lydfilerne ikke spredes videre til andre brugere. Hvis dine lydfiler kommer på afveje, og fx havner på et fildelingssite, kan vi ved hjælp af en dekoder, finde frem til dit ordrenummer. Vandmærkningen fortsætter selvom lyden overspilles fra en enhed til en anden.
• Specific text for audio books. Vandmærkning af mp3 lydbøger Digital vandmærkning er en måde at beskytte ophavsretligt materiale på. Når du køber og downloader mp3 lydbøger bliver lydfilerne stemplet med et digitalt vandmærke. Vandmærket består af ikke-hørbar information i lyden, indeholdende dit ordrenummer. Vandmærkningen påvirker ikke filformatet og besværliggør hverken download eller anvendelse af lydfilerne. Vandmærket dokumenterer at de lydfiler du downloader tilhører dig. Al kopiering, udover til dit private brug, og yderligere uretmæssig spredning er forbudt. Du er selv ansvarlig for at lydfilerne ikke spredes videre til andre brugere. Hvis dine lydfiler kommer på afveje, og fx havner på et fildelingssite, kan vi ved hjælp af en dekoder, finde frem til dit ordrenummer. Vandmærkningen fortsætter selvom lyden overspilles fra en enhed til en anden.
Shop manual 3.1.3 © Axiell Media AB. page 41