Requirements

Prerequisite knowledge

  • Digital Publishing Suite Enterprise edition
  • Knowledge about store customization and direct entitlement

User level

All

 
Note: If you have questions about this article, use the DPS forum. Please don’t contact technical support with questions about Adobe Developer Connection articles.
 
Restricted distribution is the term used to describe when a publisher wants to distribute content to a small group of readers, based on their user profiles or credentials. By default, a limited set of publications are presented to the user. Only after the user has signed into the app will additional publications be shown. The list of selected publications to be shown is based on the user's authorizations.
 

 
Restricted distribution vs. enterprise/private distribution

The various options for distribution can get confusing. Before diving into restricted distribution, I'll explain the difference between restricted distribution and enterprise/private distribution.
 
When you build an application for the iOS platform, you can distribute the app in two ways:
 
  1. Publicly through the app store
  2. Privately, either by using ad hoc distribution methods (to a maximum of 100 iPads) or by using an Apple Enterprise certificate
With private distribution, the application won't be available on the app store, but only to a limited set of users. When the application is signed with an Apple Enterprise certificate, the application may be distributed within a corporation. (Distribution restriction is implied by the terms and conditions for the Apple Enterprise Developer program.) This means that anyone in the enterprise who installs the application can access all the content provided. To limit the user's access to content within the application, you can publish your content using restricted distribution.
 
In summary: Private distribution is about how you distribute the application to the user, whereas restricted distribution will define what content a user (that has installed the app) can access.
 

 
Use cases

Restricted distribution is good for many uses. I will provide two different use cases here:
 
  1. Moto Corp is an automotive association and wants distribute to content only to its members. The publications of Moto Corp are not available for sale in the app and may only be downloaded with a valid membership to the association.
The application from Moto Corp will be distributed through the iTunes App Store and can be downloaded for free. After members have signed into the app with their membership credentials, they will see the content and can download the publications.
 
Note: For Apple app-store approval, you might need to provide at least one free folio that is available to every user.
 
  1. ACME is a corporation that wants to distribute maintenance documentation to its engineers. The maintenance manuals won't be available for sale. ACME has hundreds of engineers, who all have specific expertise for various machines. Each engineer only gets to see the maintenance manuals that are applicable to their area of expertise.
Because the application will only be available for ACME employees, ACME will use a Enterprise Distribution provisioning profile to sign the application and distribute the application wirelessly through its internal corporate network. After installation, ACME service engineers will sign in with their individual corporate credentials and get access to the content for which they are authorized.
 

 
Restricted distribution with Viewer Builder 1.8

Viewer Builder 1.8 (Release 18) is the first Enterprise version of DPS that will support restricted distribution. Within this version, restricted distribution will be done using FREE folios.
 
Complete the following steps to build an app for restricted distribution:
 
 
Prepare content
  1. Create your content using Adobe InDesign and the Folio Builder.
  2. Publish the folios through the Folio Producer (web interface) as "FREE" content. Publish each individual folio with a unique productId; for example com.acme.1, com.acme.2 etc. make sure your productIds are easy to remember / derive.
 
Set up a direct entitlement server
  1. Implement a direct entitlement server (see the article Leveraging Direct Entitlement) for user authentication. The direct entitlement server is responsible for telling the viewer which folios may be shown to the user. The response to the entitlements call will only list the productIds that may be shown to the user.
 
Implement a custom storefront
  1. Because the viewer will show all FREE folios by default in the Library view, you will need to implement a custom storefront. This custom storefront will contain the logic to show only the folios that are returned in the entitlements call from the direct entitlement server. As a starting point, you can use the code from the article Build a custom storefront. Using JavaScript, you can call the direct entitlement server to get the list of folios that may be shown and render only these folios in an HTML view.
 
Build the viewer using Viewer Builder
  1. In Viewer Builder, choose the viewer type "Multi-Issue with Direct Entitlement."
  2. In the screen Navigation Toolbar, add the Custom Store as one of the buttons in the Toolbar. Check "Hide free folios" and "Hide Buy Buttons." See Figure 1.
Figure 1. Viewer Builder settings

Figure 1. Viewer Builder settings

 

 
Alternative approach: using productIds to differentiate
When you want to differentiate between public and private content, you can also use a different approach. You will use the direct entitlement server only to do authentication. When you publish the folios as "FREE," you'll define which folios will be available publicly and which will only be visible when signed in. For example, all free folios will be published as com.acme.free.1, com.acme.free.2, and so on. All folios that may only be seen when signed in will be published as com.acme.restricted.1, com.acme.restricted.2...you get the idea.
 
In the custom store, only the productIds with the word "free" in the productId will be shown. After the user has successfully signed in, the custom store can render all the folios.
 
The overall process to build a viewer to support restricted distribution is not straightforward. Especially, the construction of the custom storefront can be complex and time-consuming. With Viewer v19 (Viewer Builder 1.9) this process can be made a little bit easier.
 

 
Restricted distribution with Viewer Builder 1.9

Viewer Builder 1.9 (Release 19) supports restricted distribution without a custom store. The folios will be published as "Retail" instead of "Free." Direct entitlement will determine which folios will be displayed to the user. Only these entitled folios will be shown in the Library as downloadable. All other folios will be hidden.
 
Complete the following steps to build an app for restricted distribution:
 
 
Prepare content
  1. Create your content using InDesign and the Folio Builder.
  2. Publish the folios through the Folio Producer (web interface) as "Retail" content. Publish each individual with an unique productId; for example, com.acme.1, com.acme.2, and so on. Make sure your productIds are easy to remember and/or derive.
 
Set up a direct entitlement server
  1. Implement a direct entitlement server (see the article Leveraging Direct Entitlement) for user authentication. The direct entitlement server is responsible for telling the viewer which folios may be shown to the user. The response to the entitlements call will list only the productIds that may be shown to the user. If you do not prefer to use authentication based on username and password, you could also set up authentication using a membership code or coupon.
 
Build the viewer using Viewer Builder
  1. In Viewer Builder, choose the viewer type "Multi-Issue with Direct Entitlement." Complete the details for your direct entitlement server and leave the settings for the "Navigation options" untouched.

 
Where to go from here

After successfully implementing the direct entitlement server and/or custom store, you can distribute the application internally (using an Apple Enterprise Distribution Provisioning Profile) or through the Apple app store.
 
The process for Android is much the same; the only difference is that there is no requirement for a different certificate to do internal distribution. The resulting .apk file can be installed by anyone who received it from you, either directly or through the Google Android Market.
 
As an enterprise, you might want to link your direct entitlement server to a corporate LDAP server. In this way, the authentication is done against LDAP. Libraries are available for LDAP integration for different programming languages like PHP, .NET, Java and Ruby on Rails.