5) Bookshelf workflow - Single Sign-On (SSO)

VitalSource offers single sign-on (SSO) to our Bookshelf product line in multiple from/to configurations. This article covers how to successfully use SSO in your chosen configuration.

Bookshelf is a very flexible product that appears in two primary wrappers: as an app on a mobile or desktop device, or otherwise it can be accessed in a browser, on any device. No matter the configuration, all Bookshelf products use the same APIs to perform their tasks.

Single sign-on is a hugely powerful feature that allows you to achieve multiple goals in one step:

  • Log the user into VitalSource
  • Open the user's instance of Bookshelf
  • Launch directly into the content of any title for which the user holds a valid license

This is achieved by doing a POST authenticated redirect. Before we describe this functionality we will first cover the difference between the installed app versions of Bookshelf and the browser-based versions. 

  • Online: At https://bookshelf.vitalsource.com users can sign in to a full version of the product that is entirely within a browser.
    • Activation Link: With this targeted endpoint, you can send an email to an existing Bookshelf user thanking them for a recent purchase, along with a unique launch URL that will perform SSO.
  • LearnKit: VitalSource Bookshelf is available in component form as LearnKit. This JavaScript based set of methods allows customers of VitalSource to host their own fully customized versions of Bookshelf within their website. The LearnKit API underlies the production version of Bookshelf and is fully supported by VitalSource.
  • App: VitalSource Bookshelf is available as a downloadable native app for every mobile (iOS, Android, Kindle) and desktop OS (Windows, OSX, and Chromebook). The latest versions are in the native OS stores and also on our support site here

Once you have determined which form of Bookshelf you will be redirecting into you can now perform an authenticated redirect (SSO to Bookshelf). Below we will walk through the various structures:

 The Redirects API can be found at https://api.vitalsource.com/v3/redirects.xml

Online 

POST v3/redirects - SSO to Bookshelf eReader is described in full here

This endpoint generates one-time URLs that are valid for 120 seconds. When designing your integration with VitalSource make sure to use this endpoint only in real-time. If you need delayed access to Bookshelf accounts please use v4/activation_requests - Create.

SSO to the online version of Bookshelf is the most intuitive for developers as we will be accessing an existing site and passing params. To succeed you will need:

  • A valid API key
  • A validated access token for the user you wish to sign-on
  • In the body of your request
    • <destination> is the only required field. This should be as shown below in most cases.
      • destination can be modified for advanced use cases to allow
        • Opening the title page of a specific book. The user must hold a currently valid license for this title. If the user has the title and has already opened the book it will open to the last page used.
        • Using CFI you can specify location within a book and force the book to open at this location, regardless of prior reading. The user must hold a currently valid license for this title. If you wish to utilize this functionality please visit this section about the TOC response to the v4/products endpoint.
    • <brand> should also be passed. This also should be as shown in most cases.

 

curl -X POST \ https://api.vitalsource.com/v3/redirects.xml \
-H "X-VitalSource-API-Key: YOUR_VST_API_KEY_GOES_HERE"
-H "X-VitalSource-Access-Token: YOUR_VST_TOKEN_GOES_HERE"

<redirect>
<destination>https://bookshelf.vitalsource.com/#/books</destination>
<brand>bookshelf.vitalsource.com</brand>
</redirect>

In response you will receive:

    • Token code in the form of a URL
      • The code is only valid for two minutes
<?xml version="1.0"?>
<redirect auto-signin="https://jigsaw.vitalsource.com/auth/redirects/ZJGUGUPRPBSRGXYCEWYTXG2T3HAJRZGC488UNASJGFQS8V4J32" expires="2019-01-01 13:54:29 UTC"/>

Using this URL, you can now launch an new window for the user that will take them into their new book. Please be aware that SSO redirect tokens have very short expirations. This time of expiration is noted above.  

Activation Link

Third-party e-commerce stores find this endpoint very useful as a means to confirm sales with existing Bookshelf users. To succeed, you will need:

  • A valid API key
  • A validated access token for the user you wish to send an activation link to
  • In the body of your request
    • The the email address that is registered with the access token
    • You can also specify your store URL
    • Specify if you want VitalSource to send our default email, or if you prefer to parse the response for the activation link and send it yourself. 
curl -X POST \ https://api.vitalsource.com/v4/activation_requests \
-H 'accept: application/json' \
-H 'cache-control: no-cache' \
-H 'content-type: application/xml' \
-H "X-VitalSource-API-Key: YOUR_VST_API_KEY_GOES_HERE"
-H "X-VitalSource-Access-Token: YOUR_VST_TOKEN_GOES_HERE"

<activation_request>
<email>sales@store.com</email>
<brand_destination_url>https://bookshelf.vitalsource.com/#/</brand_destination_url>
 <send_email>false</send_email>
</activation_request>'

In response, you will receive:

    • Activation URL in the body of the response
      • The URL is valid for a default of 45 days
{
    "id": "RZGYJEVEYFXFY4DPQYHHBYRESH2B4KH7",
"email": "sales@store.com",
    "send_email": false,
    "status": "Created",
    "brand_destination_url": "https://bookshelf.vitalsource.com/#/",
    "activation_url":  
"https://api.vitalsource.com/v4/activation_requests/RZGYJEVEYFXFY4DPQYHHBYRESH2B4KH7/activate",
    "expires_at": "Tue, 01 Jan 2019 13:10:59 +0000",
    "activated_at": null,
    "notification_sent_at": null
}


Sample Default Email 

Please note there is also a default email: 

TO: <email>
FROM: no-reply@vitalsource.com
Hi <first-name> <last-name>,
Thank you for your purchase! In order to access your digital content, please click on the link below and follow the steps to set up your account. If you’ve already set up your account, you’ll go straight to your digital content library.

[activation URL]

LearnKit

Adding LearnKit to your site is not that complex from a software development perspective. Non-customized versions can be running in just a few days. The advantage to LearnKit is that customers remain on your site and you can control branding and the user experience. To redirect to a LearnKit version of Bookshelf, you only have to change one element of the call from above.

 To succeed, you will need:

  • A valid API key
  • A validated access token for the user you wish to sign-on
  • In the body of your request
    • The VBID of the book you are launching, (BOOKSHELF-TUTORIAL is used as the example here)
    • Here you will specify your site URL as the "brand"
curl -X POST \https://api.vitalsource.com/v3/redirects.xml \
-H "X-VitalSource-API-Key: YOUR_VST_API_KEY_GOES_HERE"
-H "X-VitalSource-Access-Token: YOUR_VST_TOKEN_GOES_HERE"

<redirect>
<destination>https://online.vitalsource.com/books/BOOKSHELF-TUTORIAL</destination><brand>bookshelf.myEcommerceSite.com</brand> 
<brand>bookshelf.myEcommerceSite.com</brand>
</redirect>

Using this URL you can now launch an new window for the user that will take them into their new book.

In response you will receive:

    • Token code in the form of a URL
      • The code is only valid for two minutes
<?xml version="1.0"?>
<redirect auto-signin=
"https://sso.vitalsource.com/auth/redirects/ABCDE12FGH3IJKLMNO4PQRSTUV56W7XYZ890" expires="2017-01-00 00:00:00 UTC"/> 

App

When a users installs the Bookshelf app on a mobile device or computer a file type of vbk:/ is registered as belonging to Bookshelf. To switch between the online/LearnKit instances of Bookshelf and the app versions you change the destination as follows:

 curl -X POST \https://api.vitalsource.com/v3/redirects.xml \
-H "X-VitalSource-API-Key: YOUR_VST_API_KEY_GOES_HERE"
-H "X-VitalSource-Access-Token: YOUR_VST_TOKEN_GOES_HERE"

<redirect>
<destination>vbk:/BOOKSHELF-TUTORIAL</destination>
</redirect>

To succeed you will need:

    • A valid API key
    • A validated access token for the user you wish sign-on
    • In the body of your request
      • Brand is not required and need not be specified in an App SSO
      • The VBID of the book you are launching, (BOOKSHELF-TUTORIAL) is used as the example here.
      • The destination element of the body is the main change from the browser versions

As you will see from the response below, offline (app) SSO launch URL's are significantly longer than those above. These URL's are still designed to work from any browser and hence can be triggered from your e-commerce site. 

<?xml version="1.0"?>
<redirect auto-signin="vbk:/BOOKSHELF-TUTORIAL?t=eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkExMjhDQkMtSFM
yNTYifQ. Ksxu9hbjYU8CfKLo4NP4FCjf5A0EyvTn8y29Kei85aWHnbTA90wnUfIWYnEX5K59s99sZgQFfjBJti8WW4n_
4DrH18Kpj6KcTUETldwCi3NcfsNbpeO4XFPVtTQP2iclMoaNGma7fupoj7aNuun4WnodWZOjfA8gr4lrqQa2Q77DrvX9
33meETlznfTgNHP0tSxzLac7k1uMtwKrYYYIAIHBcZ9pYLgdr57xYYnusPyq1eR99kYPmmMH_ZvvzqHaLQ04_1QTUR
2XG2nY_TKR7HRp3l4tLaSV0n1bW0sHvv7" expires="2019-01-00 00:00:00 UTC/>

Further reading: Launching into the Bookshelf ecosystem goes beyond single sign-on. We also support many other types of launches.  (i.e. Launch with search or to a specific page.) It is even possible to specify both the start and end location of your launch. 

Go to this page to read more on this topic.

Next step Bookshelf workflow - Codes - Delete/Cancel/Refund

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.