Prerequisite knowledge
  • Subscription to Adobe Digital Publishing Suite (Pro or Enterprise)
  • Mobile provisioning profiles (Developer and Distribution) of the applications you want to migrate
  • Certificates for Apple Push Notifications (only if push is being used in the application)
  • Certificates for your developer account (Developer and Distribution) in p12 format (see the "Publishing Companion Guide for the iPad" on the DPS dashboard)

 

User level:
All
Additional required other products
  • Apple Xcode development environment installed (required to examine plist files and to upload the binary to Apple using Application Loader)
 
As a new DPS customer, you may already have existing applications in the App store, built with another platform. Or, you may be the client of an agency that has published DPS folios on your behalf. Using the steps provided in this article, you can migrate the applications over to the Adobe DPS platform under your DPS account. A very important requirement for migrating is to maintain your existing customers and not lose them during the migration.
 
The migration can be split into two parts: the application and the content. You will first prepare the content that you want your readers to be able to access after the migration. The actual application will be treated as an update to your current application. Users who already have installed the application will automatically be signaled to update the application. After updating the application, they can redownload the content to read. During a migration, entitlement to previous purchases can be maintained.
 

 
Migrating your content

Content for Adobe DPS is created using InDesign CS5 or higher. Your content has to be (re)created in InDesign and uploaded to your application account for the specific title that you want to migrate. If you have multiple titles to migrate, you have to create individual application accounts to group the content based on the title. Every edition will be its own folio.
 
Once you have (re)created the content (as folio files) and uploaded it to the Folio Producer, you can make the content available for distribution. Publish the content as either Free or Retail content (when the content was offered as In Application Purchases in your old application). When you publish the content, you have to specify a productId for each folio. These productIds much be unique for each folio. When you publish Retail content, make sure to use the same productIds as you have defined within your old application. This will ensure that readers will be entitled to the same content (now living on Adobe DPS) after they have updated their application.
 
When you have successfully published your content, the application can be created.
 

 
Migrating the application

Although you are creating a totally new application on a new platform (Adobe DPS), to the Apple app store and the user, it will look like an update of the existing application. As with any other application update on iOS, you will need to use the same mobile provisioning profile and same signing certificate.
 
Important: Don't create a new applicationId and mobile provisioning profile in the Apple developer portal! Otherwise, the application will be treated as a new application (instead of an update) and your existing readers won't be notified for an update!
 
Using Viewer Builder, build your application. Supply the credentials for the application account where the corresponding folios for this publication are uploaded. In the section for the mobile provisioning profile, point to your current provisioning profiles. After you have completed the build process, Viewer Builder will give you the option to download the application. At this stage, you don't want to do this yet.
 
 
Bumping the version number
To update an existing application, the version number of the new application must be higher than the current application. By default, Viewer Builder will start numbering new applications at 1.0.0. In case of a migration, the version number needs to be bumped to be higher than your current application. Find out the version number of your current application. Contact Adobe DPS Gold support and provide them the following information:
 
  • Application Name
  • BundleID
  • Current Version Number in Viewer Builder
  • Desired (new) Version Number in Viewer Builder. The version number must be in the form x.y.z; for example, 3.0.0.
When Adobe Gold support has confirmed that your version number has been bumped, download the viewer from Viewer Builder. In the Viewer Builder screen, it should show your new version number.
 
If your app only contains free content, you can continue to download the application [You can skip to the "testing" and "submitting" sections].
 
 
[Side bar] Finding the current version number
If you don't know the current version number of your application, you can use iTunes and XCode to look this up.
 
  1. In iTunes, go to your list of installed applications.
  2. Select the your application and choose Show in Finder.
  3. Copy the IPA file to a temporary location: for example, your desktop.
  4. Rename the IPA file to a ZIP file and double click the ZIP file. This will unzip the IPA file.
  5. Right-click the extracted application file (for example, Viewer.app) and choose Show package contents.
  6. Navigate to the file called Info.plist.
  7. Double click Info.plist to open it up in the plist-editor.
  8. Under "bundle Version," you will find the current version number.

 
Migrating retail content

You might have sold retail content in your current application that you want to migrate over to your new Adobe DPS application. It is a good user experience to provide access to content that your readers have purchased before after they have upgraded to the new application. To make this happen, you have to migrate the existing content using InDesign (see "Migrating your content") and publish the folios to the Adobe distribution environment using the Folio Producer web interface.
 
When you publish a folio, you have to assign the corresponding productId for that folio. For example, when your April edition in your current application has productId "com.company.issues.2012.04," you would upload a folio containing the April content to Adobe DPS. Using the Folio Producer, you can publish the content and provide the same "com.company.issues.2012.04" productId. Instead of publishing this content as Free, you would publish the folio as Public/Retail. Within iTunes Connect, you already have defined the productIds and pricing; nothing would need to change here.
 

 
Testing your application

After the version number of your new DPS application has been bumped, download the Developer IPA file from Viewer Builder. When you drag the IPA file into iTunes, iTunes will warn you that an application already exists. You can overwrite the existing application and sync with your iPad.
 
When you open up the application on your iPad, it will ask if you want to restore purchases. If you have provided retail content in your previous app, you want to select Yes. The application will restore any receipts from past transactions and, based on the productIds tied to those receipts, entitle the reader to content previously purchased.
 
Test the various functions of your new application before you submit the distribution viewer to Apple. You should test download of your existing folios and purchasing of new folios using a Sandbox account. These procedures are described in the "Publishing Companion Guide for the iPad" on the Digital Publishing Dashboard.
 

 
Migrating Apple subscriptions

When your current application offers Apple subscriptions, you want to migrate those as well. If you don't do this, your existing readers may lose entitlement to their existing downloaded publications. In Viewer Builder, you have to set up the same subscription products that you offer in your current application.
 
When you publish your (retail) folios using the Folio Producer, you have to set a correct publication date. For example, if the publication date of an edition within your current application is on April 12, 2012, you have to set the same publication date in the Folio Producer. Your new application will use this publication date to determine what folios will be entitled to the reader. For example, if a reader bought a three-month subscription on November 1, 2011, that would mean that the subscription would end on January 31, 2012. When this reader starts up his updated application, he will be asked to restore purchases. The application will find a receipt for a three-month subscription and will automatically entitle every retail folio that was published during his subscription period.
 
This is a great way to make sure that your existing readers will migrate to your new application without losing access to their products that they previously purchased.
 

 
WoodWing subscription server and content migration

Migrating from the WoodWing Reader application to Adobe DPS will be a fairly simple process. Existing content does not have to be recreated using Adobe InDesign. WoodWing has developed together with Adobe a method to migrate the existing (ofip) content directly to folio files. From within the WoodWing CDS environment an existing WoodWing customer can initiate this conversion and start the upload of the created folios to the Adobe DPS distribution servers.
 
When the WoodWing Reader app provided subscriptions through the WoodWing subscription server, there is no need to re-implement this functionality using the Adobe Direct Entitlement API. Adobe and WoodWing have developed a "bridge" that will translate calls from the Adobe Direct Entitlement API to the WoodWing subscription server. If you are currently using the WoodWing subscription server, you can request the needed "integratorid" and necessary URLs from Adobe Gold support.
 

 
From Agency to Pro/Enterprise

Some customers have started their journey with Adobe DPS as a client of an agency. The agency published the folios on behalf of their customers. who themselves did not have a subscription to Adobe DPS. After some period of time, such customers may want to get a subscription to Adobe DPS on their own and want to migrate the application. Is this possible without losing their readership base? Yes it is, depending on how the initial application was signed.
 
When the agency created the application, they have probably used their customer's developer account to sign the application. This can be verified by looking at the application details in the iTunes App store. When the name of the customer is listed as the publisher of the app, the application can be migrated without issues.
 
If the name of the agency is used as the publisher, things can be more complicated. In this case, the application is published by the agency (officially) and not by the customer. The customer does not have access to the developer certificates from the agency to sign the new application. The only thing that can be done in this case is to revoke the old application from the app store and publish a new application, signed by the customer.
 
If the application can be migrated, the procedure is almost the same as the procedure described above. The only difference is that the customer might already have the content in InDesign.
 
Generally the steps to take are as follows:
 
  1. The customer will get his own Adobe DPS license.
  2. Within this license, an application account has to be created, which will hold all the content. It is not possible to migrate the existing uploaded folio content from the agency-owned account to the new customer account.
  3. The customer has to recreate all the folios and upload them to their own account. While uploading, the same structure has to be recreated (follow the same procedure as described above when migrating from a different platform).
  4. Within the Viewer Builder of the customer, the application will be recreated. In the account details for the application, the application account for the new account that holds the folios has to be provided. Sign the new application with the existing mobile provisioning file. The existing application probably already has a higher version number. Using the procedure described above, the version number can be bumped, so the application will be accepted as an update to the existing application.

 
Where to go from here

This article has provided an overview on how to migrate applications from other platforms, or from agency arrangements, to your new DPS account. For more articles and resources, visit the Digital Publishing Suite Developer Center.
 
 
This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License. Permissions beyond the scope of this license, pertaining to the examples of code included within this work are available at Adobe.