Requirements

Prerequisite knowledge
Experience with creating and publishing content for Digital Publishing Suite, Professional or Enterprise Edition.
 
Other Requirements:
Access to DPS Application Account configuration
 
Original publication date: 04/15/2013
Modified: 09/29/2014 (Change log)
 
User level
All
Required products
Sample files
Note: The Adobe® Content Viewer for Web SDK was revised in R27 (July 2013) to make the API similar to the native tablet viewer's API. If you deployed an embedded web viewer using the R26 (May 2013) API, your embedded web viewer will cease to work when R28 is released. Please update your API usage as described in this revised article. If you have questions about this article, use the tutorial feedback link at the bottom of the article. Please don’t contact technical support with questions about Adobe Developer Connection articles.
 
Last year, Adobe enabled publishers to expand their readership by allowing their readers to share their content through social channels. In the case where the person being shared with was on a desktop, DPS introduced the Adobe® Content Viewer for Web (also called the web viewer), which was only available on contentviewer.adobe.com.  Now publishers can embed that same web viewer on their own website and integrate it into their brand experience.  This article will give you technical information about the embedded web viewer, information on which DPS customers can take advantage of this feature, the steps you need to take to embed the web viewer within your own site, and limitations that you will want to keep in mind.
 

 

What is the embedded web viewer?

The Adobe Content Viewer for Web is equivalent to a generic reader app on touch devices, but for the desktop.  You can find out more about the web viewer at in the article Integrated social sharing with Digital Publishing Suite. The embedded web viewer is that same viewer, but accessed through an iframe on a web page of your choosing. With the embedded web viewer, not only do you determine the URL, but you can also determine the appearance of the page around the web viewer and influence the user’s experience of reading your publications’ content on the web.
Figure 1. Example of an embedded web viewer
Figure 1. Example of an embedded web viewer
 
Availability of the embedded web viewer
For now, the embedded web viewer is available only for desktop platforms, although we expect to release a similar product for Mobile Safari on the iPad as well as other mobile browser platforms in the future.
The embedded web viewer with a Custom Library is available to both DPS Professional and Enterprise subscribers, while enabling Custom Store features in the Web Viewer is available only to Enterprise customers. For more information about enabling a Custom Store or a Custom Library in the embedded web viewer site, see the article “Getting started with the browser library API
 
How does the embedded web viewer work?
The Adobe Content Viewer for Web SDK consists of a Custom Store API and a Bridge API that manages the creation and destruction of the web viewer's iframe, qualifies that this page is permitted to display the publication's content, facilitates communication to/from the web viewer from your web page, and provides exception management. When you publish folios, all web appropriate articles (articles that meet the article criteria defined in the Configuring Your Account section below),  are uploaded to contentviewer.adobe.com. You can make JavaScript calls from your HTML page to the Bridge API to interact with the web viewer.
 
Using the Hosting URL that is associated with your publication (see Configuring Your Account below, for instructions on setting the Hosting URL), the Adobe Content Viewer for Web SDK takes several steps to ensure that only content that you have authorized to be published shows up on your website.  First, the magazine content has to be published using account IDs that your web page knows about. This means that you can choose to have the content for several publications under a single web masthead.  Second, the URL hosting the web viewer must match the publication’s Hosting URL, which allows you to choose the URL that can host your publications’ content. In addition, any readers that would have been directed to the generic contentviewer.adobe.com URL to see your content will automatically be redirected to your hosting URL. Once the hosting URL is updated, subsequent social sharing will direct users to that specific URL.
 
There is full backwards compatibility. If you have previously published content into the Adobe Content Viewer for Web, you can still embed the web viewer into your pages. Users who click “old” links to contentviewer.adobe.com will be redirected to your Hosting URL which can contain the web viewer with your branding instead.
 
How will readers discover your embedded web viewer?
One of the ways subscribers and non-subscribers alike can find their way to your embedded web viewer experience is when following a social sharing link.   The  embedded web viewer always starts by immersing the reader directly into the linked article, although the reader can choose to skim the other contents of the same issue.  If readers sign in and are already subscribers of your publication (via direct entitlement ONLY, not if they purchased an issue or subscription from an app store), then they will be able to view all of the issue’s articles.  However, if they aren't entitled, then the number of articles they can read depends on the paywall threshold and how many articles in that issue are marked as Free, Metered and Protected.  Once they reach the paywall threshold or attempt to access protected content, they are then given the opportunity to subscribe to your publication (or sign in if they already are subscribed).
 
Another way that readers might find their way to reading content in your embedded web viewer would be via links on your own website or via more traditional campaign vehicles.
 
The key to implementing the embedded web viewer for this type of usage is to remember that (1) the web viewer must always start by viewing an article and (2) the web viewer can display only the contents of a single folio at a time. That said, the article link could be the TOC or the cover of your publication, effectively making the issue available as if it were a magazine instead of a single article.  Therefore, if you really want to create a more comprehensive content portal type of experience, then you need to integrate the library into the page’s experience so that if an article isn’t specified, then the reader immediately sees an overview of your content on an issue-by-issue basis.  Using the custom library isn’t the focus of this article, but is covered in detail in another Devnet article, “Getting started with the browser library API”.
 
 

Configuring your account

The DPS delegate account that is associated with a magazine must be configured.  To do this, log in with an administration account to the Digital Publishing portal at http://digitalpublishing.acrobat.com and select the Account Administration tab.
Figure 2. DPS Account Administration tab
Figure 2. DPS Account Administration tab
 
Enable the web viewer
Select the delegate account that is associated with the publication and then click the Configure User button. As in the screenshot below, you will want to enable the web viewer and enter a hosting URL exactly as you would in the browser to bring up the embedded web viewer, including the http:// prefix.
 
You can also specify where the user is redirected should you ever elect to disable the web viewer at some point in the future.
Figure 3. Enabling the web viewer and hosting URL
Figure 3. Enabling the web viewer and hosting URL
 
Limiting the number of metered articles
In addition you may want to check out the paywall settings further down in that same page:
Figure 4. Paywall settings
Figure 4. Paywall settings
 
You will select this checkbox if you want to limit how many metered articles a reader can peruse before they are required to purchase your publication.  Publishers can limit the number of metered articles viewed by a user in each publication via the paywall settings. Check out the article, Integrated social sharing with Digital Publishing Suite. There are some limited options for customizing the paywall here, but there is a technique for customizing the paywall experience that we’ll explore in the next article in the series.

 

Offer some free or metered articles
You can now choose to publish your articles as Free, Metered or Protected in the digitalpublishing.acrobat.com portal by clicking on the Folio Producer tab on the left, selecting a folio and then clicking the Open button. You can then select each article individually by clicking its icon.
 
In the Article Properties panel for each article, you can change “Article Access” to Free, Metered, or Protected. Protected content can't be viewed unless the user is entitled. There are some cases where an article does not need to be protected.  For example, if you have implemented a cover image as an article, it can't be seen by non-entitled users if it's protected. Starting in R27, free articles can be viewed in the web viewer without any limitations – whereas metered articles are still constrained by the paywall threshold.  Therefore, in-line references (such as a custom table of contents) and advertisements can be viewed without any limitations, nor will accessing free articles reduce the number of metered articles that a reader can access.

 

Article Criteria
Articles that appear in the embedded web viewer should meet the following criteria:
  • Articles should be the same aspect ratio as its folio.
  • If landscape, the article must be 1024 x 748 or 1024 x 768.
  • If portrait, the article must be 768 x 1004 or 768 x 1024.
  • An article can be different than the above dimensions if its folio is marked as “Web Viewer Only”
Note the article’s xreference ID
Figure 5. Article’s x-reference ID in Folio Producer
Figure 5. Article’s x-reference ID in Folio Producer
 
In this example, the currently selected article is called ‘article1’.  Note that this appears only on the icon and not in the metadata in the right column. We’ll need to use this information soon.
 
 

Configuring your system

Many developers use their own development machine as a development server during initial development of a web page.  Doing so allows them to iterate more quickly, without risking the stability of their staging or production environments.  Windows users can use WAMP and Apple users can take advantage of the Apache server that is provided free with the Mac OS.
 
Verify that your local server is functioning correctly
In your browser, go the following URL: http://127.0.0.1
 
If you are on a Mac you should see: It works!  If you see nothing or you get an error, you may need to either enable your Apache server or disable your firewall.
 
Enabling local preview during development
During development, you will typically end up using local URLs, such as http://127.0.0.1/web_viewer_embedded/index.html. This won’t work particularly well because of the security checks that the web viewer embedding library performs to make sure that the content only appears where it’s supposed to appear.
 
To work around this issue, you will need to edit your system’s hosts file to make it believe that your system is the domain in question.  This is just a temporary solution and you will want to remember the back out your changes once you’ve tested your solution.
 
On a Mac, you would do this by following the steps listed below, which are necessary because the hosts file is stored in an unusual location and you need to edit the file with admin privileges:
  1. Use the Spotlight Search tool in the upper right corner of your Mac’s application bar and type in: Terminal and press ENTER.
Figure 6. Launching Terminal via OS X’s Spotlight
Figure 6. Launching Terminal via OS X’s Spotlight
 
This will launch one or more Terminal session windows.
  1. At the prompt type:
sudo /Applications/TextEdit.app/Contents/MacOS/TextEdit
 
This will ask you for your system’s password (required to edit this system file) and launch the standard Mac Text Editor.  You will want to select File | Open , press SHIFT-COMMAND-G to go to a system folder and then type in /etc and press Go.
Figure 7. Going to the /etc folder on OS X
Figure 7. Going to the /etc folder on OS X
 
Figure 8. Locating the hosts file in OS X
Figure 8. Locating the hosts file in OS X
 
Select the hosts file and press the Open button.  You should see something similar to:
 
## # Host Database # # localhost is used to configure the loopback interface # when the system is booting. Do not change this entry. ## 127.0.0.1 localhost 255.255.255.255 broadcasthost ::1 localhost fe80::1%lo0 localhost
  1. Add a new line to the file with the following text (or something similar) and save the file and then quit the TextEdit application. You can prefix a line with # if you want to comment out an entry

 

127.0.0.1 mysubdomain.mydomain.com
 
  1. Back in the Terminal window, type dscacheutil –flushcache – this is useful in case you had recently pointed your browser at the embedded web viewer URL to ensure that it’s pulling the content from your own server.
  2. Verify that this attempt to short-circuit the URL works.  If you had previously verified that your local server is working, you should see the same exactly content if you send your browser to mysubdomain.mydomain.com.
 

 

Creating the basic embedded viewer page

Download and uncompress the ewv_samples.zip that is referenced from this article.  If you’re using a Mac, you will probably want to place these files inside of your /Library/Documents directory – specifically you want to make sure that you copy over the jsdist and hostDemos directories.  In the embedded web viewer samples files that are attached to this article, you will want to navigate to bridge directory and open index.html in your favorite HTML editor.
 
Notice that the following files are referenced from this HTML file:
  1. css/styles.css – which can be changed to fit into the style of your site, and
  2. http://cdn-contentviewer.adobe.com/public/pepper/wvel/2/WVEmbed.min.js  – which is the Adobe® Content Viewer for Web SDK that invokes the web viewer via the iframe and communicates with it.

 

Placing div anchor

The key to the placement of the web viewer in your page is the strategic placement of a unique div tag with the id of “mainContainer” or other name of your choosing.  At runtime, the Adobe® Content Viewer for Web SDK will replace that div tag with the actual iFrame.

 

Create and invoke the web viewer

The JavaScript within the index.html page does the following:
  • Creates one side of a communication bridge with the soon-to-be-created web viewer using the bridge: protocol,
  • Determines if the web viewer is being directed to open a specific article by using a regular expression to parse and extract the article from a URL parameter string,
  • Instantiates the web viewer via an iframe and passes along an initialization structure containing information about:
    • whether or not the iframe should overtake any content in its periphery,
    • the id of the div anchor that you placed in your HTML as specified in the “Placing div anchor” section, above,
    • the names of wrapper classes,
    • the ID to associate with the iframe so that you can control it with your JavaScript,
    • the DPS account IDs to associate with this web page,
    • the parameter string (which can be overridden) that determines the article to display,
    • the iframe’s curtain style, which is displayed over the iframe in certain cases such as navigation,
    • several callback functions to allow you to handle events, errors, and redirects related to the web viewer content.

 

 

How to manually construct a web viewer parameter

The web viewer parameter is an article reference that can be passed to your custom web viewer page that uniquely identifies a specific article, what publication the article appears in, and the means by which to determine that the custom web viewer is the one sanctioned by the article's publisher (via the Hosting URL). With this parameter specified as a URL parameter in your hosting page URL, the Adobe® Content Viewer For Web SDK will display that article in the iframe. A web viewer parameter consists of:
Figure 9. Constructing a web view parameter
Figure 9. Constructing a web view parameter
 
Application Name
You can find the Application Name by gong to the DPS Dashboard and looking at the application account associated with the publication.
 
Figure 10. Looking up the Application Name in DPS Account Administration
Figure 10. Looking up the Application Name in DPS Account Administration
 
How to find your account ID
Before you can use the embedded web viewer, you need to know what your account ID is which is of the form of c35d22c83d5e4c499076b6cc1e246fc1.  You can find it by going to http://lighthouse.adobe.com/dps/entitlement/ and entering the email address and password of the delegate account associated with that publication.
Figure 11. Looking up your account ID using the online tool
Figure 11. Looking up your account ID using the online tool
 
If you want the content of more than one publication to appear at the same URL you will need to look up the account ID for each delegate account.
 
Once you’ve looked up your account ID, you will want to edit the HTML line that references it:
 
accountIDs : 'c35d22c83d5e4c499076b6cc1e246fc1',
 
If you want to show the content for multiple publications, then list all of the account ID’s as an array, similar to:
 
accountIDs : ['c35d22c83d5e4c499076b6cc1e246fc1', ' b6cc1e246fc1c35d22c83d5e4c499076'],
 
Folio Name
You can also find the folio name in the DPS Dashboard, in the Folder Producer : Organizer panel.
Figure 12. Looking up Folio Name in Folio Producer: Organizer panel
Figure 12. Looking up Folio Name in Folio Producer: Organizer panel
 

Article Name

The article name can be found in the panel, after you’ve opened the specific folio that contains the matching Publication Name.

Figure 13. Looking up Article Name in Folio Producer: Editor
Figure 13. Looking up Article Name in Folio Producer: Editor
 
Viewing the article in the embedded web viewer
Now that you are able to manually construct a web viewer parameter string, modify the hard-coded parameter that is in the index.html file, save your index.html file and then open http://mysubdomain.mydomain.com/hostDemos/basic/index.html in your browser.
 
Deploy to your server
Once you are able to validate that the page works as expected on your local machine, you can deploy to your server at the pre-designated URL – and you must restore the hosts file to its original configuration – otherwise you won't be testing against the live server.
 
 

Handling the edge cases

It might seem ironic that an article on the web viewer would have a section on properly handling social sharing interactions with touch devices – but once a custom hosting URL is associated with a publication, all of the users that follow a web viewer link will end up at your URL, so you will want to validate that iOS users, for example, have a similar experience once directed to your site – so that for example, they are prompted to either launch or get your app to view the article in question.
 
Alternatively, since the web viewer is currently only supported on a desktop or laptop browser, you can choose to deliver the article content in an alternative format that is appropriate for the device that is connecting.
 
Detecting a non-supported device
If the web viewer detects that the system is not a desktop, then it will broadcast a 700 error code.  This will usually (but not always) mean that the reader is using a touch device.
 
function eventCallback (message) { console.log('Message', message); if(foundUnsupported && message.eventType === 'metadata') { console.log('METADATA: ', message.metadata); renderCustomContent(message.metadata.articleTitle, message.metadata.coverImage, message.metadata.publicationName); } } function errorCallback (message) { console.log(message); if(message.errorCode === '700') { foundUnsupported = true; } return true; }
Launching the App
The key is to inspect the metadata event that will follow the error.  That event will contain all of the information about the article.  In particular, when the user clicks on Launch App button, you will want to link to the strApplicationLaunchUrl metadata or the strItunesStoreUrl metadata in order to launch or get the application.  The full metadata object is:
 
{ 'coverImage' : { 'portrait' : '{string}', 'landscape' : '{string}' }, 'publicationName': '{string}', 'articleTitle': '{string}', 'articleDescription': '{string}', 'publicationDate' : '{string}', 'strPaywallUrl' : '{string}', 'strItunesStoreUrl': '{string}', 'strApplicationLaunchUrl' : '{string}' }
Figure 14. Non-supported device example
Figure 14. Non-supported device example
 
 

Limitations

There are several limitations that you will want to keep in mind.
  • The embedded web viewer is only supported on the most recent and previous versions of the more common browsers (e.g., Safari, Firefox and Chrome on Mac; IE, Firefox and Chrome on PC) today, although support for other device types are on the roadmap. There is limited support for Internet Explorer 8 as well as Safari on Windows.
  • Be wary when copy/pasting the embedded web viewer URL, as the URL in the browser doesn’t change as the reader switches between articles.
  • Only one iframe per instance of the library is supported (you should only have one web viewer open on your page).
  • Full-screen video is not supported in this release.
  • Some Overlays (such as panoramas) are not currently supported in the web viewer.
  • Only Direct Entitlement credentials are recognized by the web viewer, not Apple nor Google Play Subscriptions nor any other app store.
 

 

Where to go from here

Refer to Digital Publishing Suite Help: Creating custom viewer apps for the iPad and iPhone for information on creating the web viewer’s counterpart on touch devices.
Read the Documentation.txt file provided in the sample files for more detailed information about interacting with the web viewer via the bridge.
See the article Getting started with the browser library API to learn how display a library view of folios in a web page using a new store/library API.
Check out the next two articles in this series, which will show you how to create context-sensitive embedded web viewers, allowing you to tailor surrounding content around the articles being read and how to create a micro-portal that contains information from all of your publications.
 
Change log
09/29/2014 - Changed “publication name” references to “folio name"
03/20/2014 - Updated the article to remove the reference to “https://“ in a hosting URL. This is not supported.
Updated to reflect the changes to the embedded web viewer API in the R27 (July 2013) DPS release.