Developers     Developer center

Developer center

under hero banner

NOTE: We’ve recently updated our service. Learn more

Click here to see the Current Storefront Hookup Tutorial

Storefront Hookup (Legacy)

This tutorial explains the use of tokens and how to integrate your media storefront server with ExpressPlay.

Requirements

  • A Content Key
  • A Content ID
  • The Content Location (URL)
  • Your Customer Authenticator

ExpressPlay REST APIs make integrating ExpressPlay with a web storefront or other content management system easy. This tutorial explains the ExpressPlay token lifecycle and the processes necessary to integrate your media storefront back-end with ExpressPlay.

Marlin BB tokens work much the same way as MS3 tokens; however, MS3 tokens are in the form of a “compound url” which can be used to both locate the playable content and its corresponding license. BB tokens are provided as an XML response which must be processed separately from the content url. BB tokens also allow some additional playback options.


STEP 1 – Understanding the Token Lifecycle

ExpressPlay tokens are at the center of the ExpressPlay service. You can think of tokens as a ticket to play a piece of content. Tokens are generated by ExpressPlay upon request by a content service, and they can be generated as many times as you like, but generating a token does not consume usage credits. Token usage is counted only when a token is redeemed for playback by an app using the SDK or a Marlin-enabled device.

An ExpressPlay enabled player must receive a token to play content. In the case of Marlin MS3 tokens, the MS3 compound URL contains the URL of the content as well as the encoded token data. In the case of Marlin BB tokens, the BB token is an XML snippet which may be passed to the app to be processed by the ExpressPlay SDK. In either case, when the player processes a token it communicates with ExpressPlay to redeem the token and obtain a valid license. At this point, a usage credit is consumed and secure playback is enabled. It is important to note that in the case of Marlin BB tokens, a single token can be used multiple times but only for the same content or set of content.


STEP 2 – Generating Tokens

This tutorial focuses on the MS3 Token Request API described here. This API requires your “production customer authenticator”, found here at admin.expressplay.com, the content key used to encrypt the piece of content, the content Name used when packaging the content, and the content’s hosting location in URL form. This information is then formatted into a POST or GET request demonstrated below.

Here is an example of the ExpressPlay Admin dashboard where you can find your Customer Authenticator (Legacy).


Note: The token request API example below uses the production service API which requires that you use the production customer authenticator (a.k.a. API key) in the customerAuthenticator parameter. The test customer authenticator will not work with the production service API. Please make sure that you are using the correct authenticator. Please refer to the Test Token Generation Tutorial for details on the test customer authenticator and its usage.

https://ms3-gen.service.expressplay.com/hms/ms3/token?customerAuthenticator=793,adf05681cff44bc58ab24fadd7876e42&contentId.urn:marlin:kid:1234123412341234&contentKey.0=12341234123412341234123412341234&contentURL=www.test.com/testfolder/testfolder/testmedia.mp4

A properly formatted request yields an MS3 token similar to the one shown below.

https://ms3-gen.service.expressplay.com/hms/ms3/rights/?b=ABEAAgAAAasAB3dzYnRlc3TdegAQDLbmkEfjJkSomDh93keD5wBwyfioFCWirNIQFUb9AWlxykSbR13rFUI729zbNIhorCN-Sn1RsPvz1kRuF5_FiIC1HznCcR3e-cecZ988xrea6PtJJy3AYSkyvjmEBT4-9pRI3zgYK2nZ1U1HlRvK-OxkLKfbCDCy7avt1t7SgZ0xswAAABTVHKJ5d3tvRR4ceR7R_pZEkz1e6g#http%3A%2F%2Fcontent.intertrust.com%2Fexpress%2Fdash%2Fmpd.xml

When a client application is ready to play a piece of content, a corresponding token must be generated and handed off to the client. This means that the content key, content id, authenticator and file location must be stored for each piece of content available on the service.


STEP 3 – Token Handling

Tokens are then passed to the end user’s ExpressPlay enabled player. The player reads the token and uses the information to locate the license server and the content server. The player contacts the license server for a content key, a redemption credit is consumed, and the player begins content playback.

Each token can be redeemed as many times as desired by the player. With an ‘expirationTime’ parameter, it is possible to force a Token to expire at a certain time. If ‘Token Expiration Time’ is left blank, the token will be available for thirty days.