iOS App Fulfillment Issue Explained

iOS App Fulfillment Issue Explained

UPDATE: On June 9, 2017, Adobe released a new version of Adobe Digital Editions for iOS that incorporates a fix for books failing to fulfill where accentuated characters exist.


Apple recently pushed out iOS 10.3, which included several great enhancements, such as Apple File System (APFS). The intent was to replace the existing aging Hierarchical File System Plus (HFS+) that all Apple devices have been using since 1998. With a replacement as extensive as this, certain features or standards that developers have developed for their applications might be subject to change. Among these changes is Unicode normalization that was a core part of HFS+; however, APFS does not support Unicode normalization as part of the filesystem. APFS treats all bytes equal, and treats everything equally whether or not the Unicode has been normalized.

One casualty of this change in functionality was Adobe Reader Mobile SDK-enabled applications. Every app handles the error a little bit differently, but it all results in your book not being fulfilled once the ACSM file has been ingested.

Unicode is a tricky thing to wrap your head around. Visually, you could have two accentuated strings or characters appear on the screen. They would both read the same and look the same by the human eye, but they are very much not the same. An example would be ‘héllo’. Depending on how it’s encoded, this could be interpreted by the reading app as either ‘he%CC%81llo’ or ‘h%C3%A9llo’. In other words, if you were to enter ‘é’ at the keyboard, the encoding would be C3/A9; however, the encoding normalization that would have been done by HFS+ would have been CC/81. In short, the eReader loses track of the book on the file system when accentuated characters are in play.

How do you fix this in your application? Well the solution to the problem depends on how your application is written and there isn’t a one size fits all here. Many developers became used to the file system normalizing Unicode automatically. Now the onus is on the developer to do that in the application layer. One example is that you may want to avoid the implicit conversion that ‘fileURLWithPath’ does to canonical UTF-8. If your application uses this, you might instead choose to use ‘[NSURL alloc] initWithFileSystemRepresentation…]’ to avoid the conversion. Generally, NSString might have to be replaced across the board by NSURL when it comes to dealing with filenames and the file system. This was the gist of the required change in our eReading app, Bookvia.

Apple’s own recommendation, while light, has been to use high-level APIs such as NSFileManager and NSURL, with the fileSystemRepresentation properly of NSURL.

We understand that modifying an application is not an instant process and requires different levels of certification, and that you also have a business to maintain. So, what kind of workaround is there in the meantime? Fortunately, a workaround does exist if you also host the fulfilling Adobe Content Server. Since the issue stems from accentuated characters being present in the title and metadata, you must remove the accentuated characters. Once this is done, that particular title will again be able to fulfill in the iOS app.

For additional reading on the Unicode normalization issue, these articles are helpful:

We would like to take an opportunity to thank our friends at Mantano and Bluefire for working with us to identify the cause and be able to provide very helpful suggestions for app developers.

If you have any additional questions regarding this issue, comment below or contact us.

Leave a Reply

Your email address will not be published. Required fields are marked *