Prerequisite knowledge
 
Experience working with the Adobe Digital Publishing Suite (DPS), HTML and JavaScript is required. In addition, familiarity with the DPS Library/Store API is useful.
 
User level:
 
Beginner
 
Required Adobe products
 
Documentation
 
Sample files

welcome_screen.zip
 
By downloading software from the Adobe Web site you agree to the terms of our license agreement. Please read it before downloading.
Note: If you have questions about this article, use the comments feature at the bottom of the article. Please don’t contact technical support with questions about Adobe Developer Connection articles.
 

 
Introduction

With release 29 of DPS (December 2013) enterprise customers can include a welcome screen to display to users when the app first starts. This was previously available on the iPhone but is now available on the iPad as well. The welcome screen is a transparent webview that is displayed between the splash screen and library/store when the app first starts or is updated and has full access to the library/store api. The library api must be used to remove the welcome screen.
 
Some of the ways you could leverage the welcome screen include:
 
  • Let readers know their first issue is free (First Folio Free)
  • Automatically download and view an issue with article preview
  • Welcome new readers and display options for print, digital and subscriptions
  • Request reader contact information
In this article I will walk through a template to get you started with creating a welcome screen. If you have “Enable First Issue Entitlement“ enabled, the template will download the first retail folio. If it is not enabled the template will download the latest folio that has an image preview. If a previewable folio is not found, the template will download the latest free folio.
 
The template also displays buttons to purchase a subscription, login as a print subscriber, restore purchases as an existing digital subscriber or go to the store. In this article I will go over how to hide any of these buttons.
 
If you would like to easily customize the colors, fonts and images of this template you can use the configurator.
 

 
Template Overview

The template uses CSS media queries to display different images and layouts for iPad in landscape/portrait and iPhone in portrait. Different images are used for retina and non-retina for the iPad and iPhone. For the iPhone, the welcome screen only displays in portrait orientation.
 
The figures below show the various views of the welcome screen on the iPad in portrait.
 
Figure 1. The initial view of the welcome screen

Figure 1. The initial view of the welcome screen

 

Figure 2. The view while a folio is downloading.

Figure 2. The view while a folio is downloading.

 

Figure 3. The view after the folio has downloaded.

Figure 3. The view after the folio has downloaded.

 

Figure 4. The view after a user taps “I would like to subscribe”

Figure 4. The view after a user taps “I would like to subscribe”

 

Figure 5. The view after a user taps “I am a print subscriber”

Figure 5. The view after a user taps “I am a print subscriber”

 

Figure 6. The view after a user taps “I am a digital subscriber”

Figure 6. The view after a user taps “I am a digital subscriber”

 

 
Using the template

Begin by downloading the sample files that are provided at the beginning of this article.
 
 
Changing the images
To change the images, navigate to the images directory and replace the respective image. The following is a list of images with their dimensions. Keep in mind that the welcome screen displays the status bar so the image heights have been adjusted to accommodate.
 
Table 1. Image dimensions
 
ipad_landscape_retina.jpg 2048x1496
ipad_landscape.jpg 1024x748
ipad_portrait_retina.jpg 1536x2008
ipad_portrait.jpg 768x1004
iphone_portrait_retina_3.5inch.jpg 640x920
iphone_portrait_retina_4inch.jpg 640x1096
one_portrait.jpg 320x460
If you do not plan on supporting a certain dimension, you do not need to replace the image. The image is not displayed unless a user is able to view the respective dimension. For example, if you do not plan on supporting the iPhone, you do not need to replace the images since a user will not be able to see the welcome screen on an iPhone.
 
 
Hiding the buttons
The template defaults to display four buttons:
 
  1. “I would like to subscribe” – opens a subscribe dialog.
  2. “I am a print subscriber” – opens a login for print subscribers. This should only be displayed if you support third party entitlement.
  3. “I am a digital subscriber” – allows a user to restore purchases if they are an existing subscriber.
  4. “Go to store” – closes the welcome screen and opens the default view.
To remove any of these buttons, open js/Config.js and change the value of any of the following properties to false: IS_SHOW_SUBSCRIBE_BUTTON, IS_SHOW_PRINT_SUBSCRIBER_BUTTON, IS_SHOW_ITUNES_USER_BUTTON, IS_SHOW_STORE_BUTTON.
 
 
Entitlement options
If you choose to display “I am a print subscriber” and would like to allow users to create an account or retrieve their password you can enter a URL for CREATE_ACCOUNT_URL or FORGOT_PASSWORD_URL. If there is a value present for either of these fields a link will be displayed from the login dialog. In order for this dialog to work you need direct entitlement set up.
 
 
Auto open folio
If you would like the folio to auto open during the download, set the value for isAutoOpenDownloadedFolio to true. If you leave this value as false, the user will see the messaging as seen in figure 3.
 
 
App Builder
If you have no other changes to make, zip the contents of the folder at the file level not at the containing folder level.
 
Next open App Builder and add your zip to the first screen.
 
Figure 7. The form field to add your welcome screen ZIP.

Figure 7. The form field to add your welcome screen ZIP.

 

 
Development considerations

When developing your own welcome screen, keep in mind the following.
 
 
initializationComplete
In the same way that you must listen for adobeDPS.initializationComplete when creating a custom store/library, you also must wait for this event before using the api. An example of this is on line 17 of main.js, adobeDPS.initializationComplete.addOnce(checkIsUserOnline). This example waits for initializationComplete and then checks if the user is online.
 
 
Offline behavior
If a user is offline and launches the app for the first time the welcome screen is not displayed. However, if a user subsequently updates the app and is offline the welcome screen is displayed. For an example of how to handle network connectivity, the function checkIsUserOnline() on line 30 of main.js pings stats.adobe.com for network connectivity and if the user is offline a handler is added to adobeDPS.deviceService.updatedSignal() to look for network changes. When the user is online again another request to stats.adobe.com is made to verify connectivity. The reason why stats.adobe.com is used is because a change in network connectivity could mean a connection to a network but not necessarily to the internet.
 
 
updateLibrary()
Always call adobeDPS.libraryService.updateLibrary() after initializationComplete. This will ensure the library is up to date before proceeding any further. This is especially important if you have “Enable First Issue Entitlement” enabled. An example of this is on line 74 of main.js,
 
var transaction = adobeDPS.libraryService.updateLibrary();
transaction.completedSignal.add(updateLibraryHandler);
 
This example calls updateLibrary() and then waits for the transaction to complete before using the API.
 
 
Enable First Issue Entitlement
If you have “Enable First Issue Entitlement” enabled and you would like the user to be aware that a download is occurring you will need to loop through your folios to find the relevant folio. You can do this by looping through folioMap and looking for folio.entitlementType == adobeDPS.receiptService.entitlementTypes.PROMOTIONAL. If the folio is promotional, then this is the one that is automatically being downloaded by the viewer.
 
 
App Updates
Unfortunately the API does not allow us to figure out if an install is a new install or an update. This may or may not be a problem depending on what you would like your welcome screen to do. If you would like to distinguish between new installs and updates, one technique would be to use HTML5 localStorage although iOS can wipe this data at anytime. Another technique which I have implemented beginning on line 130 of main.js is to look at folio.state and check if any are INSTALLED. If a folio is installed we can safely assume the app is an update.
 

 
Where to go from here

If you would like to easily customize the colors, fonts and images of this template you can use the configurator.
 
If you would like more information about using the store/library API, check out the articles at the Custom storefronts and libraries page.
 
Comments are currently closed as we migrate to a new commenting system. In the interim, please provide any feedback using our feedback form. Thank you for your patience.