Documented below is an overview on the error handling and messaging in place across our SDK framework. This is designed to help you understand the messages your users may see in the app and the reasons for them as well as what the default copy is should you wish to change or replace with your own localisable strings (see Custom Error Messages).
Throughout the app we have error handling in these key areas:
- Network connectivity
- Authorisation via app store purchasing and third party subscriptions
And all of these areas may occur on first launch of the app and/or when users try to purchase and access content. We have listed the messaging in order of a typical user journey through app from start to finish.
For edition based user journeys you will pass through network connectivity checks onto authorisation checks and then onto the downloading phase.
1. Network Connectivity Checks (wifi or cellular) - it checks if it *thinks* the device is connected. This type of check can be fooled, it wouldn't know if you were on a Public Wi-Fi network — like those in coffee shops or hotels for instance, so it thinks your online and may proceed to 2. Authorisation Checks and an error message may occur at this stage or if successful proceeds to download.
Message: No Documents Available
Occurs: On first launch of application when the app needs to connect to the OPDS feed url to download and display content.
Reasons: Device can't connect to feed; problems with url, no documents in feed or no network connection on device. At the moment we do not distinguish between server-side issue and client-side issue here but this type of check isn't reliable and would only apply in first launch scenario so wouldn't help with subsequent app opens and use.
Message: Title - No Internet Connection / Copy - Please connect to wifi or mobile data network
Occurs: On start of an action requiring network e.g content download, when a user has tapped 'Download' button for an edition and it trys to begin a download or for authorisation calls.
Reasons: Device can't connect to internet
2. Authorisation Checks - it check if it *thinks* you are authorised to access this content, you may have purchased, have an active subscription etc. It occurs on checking third party or app store authorisation when logging in or buying or at the start of content download, when a user has tapped 'Download' button for an edition and it trys to begin a download. Various reasons for errors can include:
- Unknown error - malformed response receipt or 200 from auth token and it doesn't work error / message 'A server with the specified hostname could not be found' type problem
Message: Title - Authorisation Failed / Copy - There was a problem with the authorisation service.
Reference: "pugpig_title_authorisation_failed" "pugpig_autherror_unknown"
- Network failure - not necessarily a server-side issue but could include server 404s a response where underlying code throws exception any number of reasons client or server
Message: Copy - We were unable to connect to the network or No internet connection available. Please connect to a Wi-Fi or mobile data network.
Reference: "pugpig_autherror_networkfailure" or "pugpig_error_no_internet_connection"
If authorisation is successful the user will receive one of many allowed auth response e.g active subscription where access is granted or others like subscription has lapsed or details were not recognised. These include:
- Subscription Expired - Your subscription has expired
- Product Unavailable - This item is not yet available for purchase
- Access Expired - You do not have access to this item
- Purchasing Disabled - In-App purchasing has been disabled
3. Download Checks - it attempts to start and complete a file download. This will occur for any document download in Pugpig, across both continuous or edition based content and applications.
If the download onto device is successful there are no messages and the app should just work. The UI will display the ability to read the downloaded content to the user.
Message: Title - Download failed / Copy - There was an error while downloading.
Occurs: Before, during or at the end of a document download
Reasons: The download couldn't begin or was cancelled, stopped or halted but this could be down to a number of reasons, it could be a client-side device issue or a server-side issue. You will also see this message if a download was successful but the datasource is empty - for any reason.
Reference: "pugpig_title_download_failed" and "pugpig_error_download_error"
If the download fails the generic message above displayed is, we don't surface the specific errors to the end user however we are logging them so developers should refer to console logs to debug.
The download logs include:
- If unzip fails - we log this as "Unzip failed" + "<name of zip>"
- If a single file or asset fails "Asset:" <name of asset> + "<exception>" we don't know why server or app connection
- We can't find a html link in atom feed it doesn't resolve
- manifest no good malformed root url invalid etc
There are independent errors for cover images etc.
Our Pugpig SDK doesn't have more extensive error messaging for determining the exact cause in all auth or download cases than what has been mentioned above, particularly on Android. We could do more to propogate errors up and we plan to improve on this functionality in future releases where we surface app store auth codes. We do however log the particular download errors in the console for debugging purposes.