This document guides you through the basic set up of a Pugpig for Magazines app on iOS. It assumes access to a Apple Mac development machine with Xcode to build on, an iOS device to test on, and an OPDS endpoint content feed along with any authorisation methods required.
Here are some step-by-step instructions to get started with Pugpig for Magazines on iOS:
- Download the latest Pugpig For Magazines version available here and run the installer
- Start a new Xcode project and select the PugpigForMagazines Application template*
- Configure your app - see section
- Theme your app - see section
- Update the copy - see section
- Update the assets - see section
- Extending your app (optional) - see section
- Include your Pugpig licence - see section
- Setup your app in the Apple App store - see section
- Submit, and you're done!
*Important note: If using Xcode 6 please ensure you have correctly installed v1.2.0 or higher. There is a known bug with older xcode templates which can led to data loss, more info here
You configure the iOS application with a Config.plist file found in your Xcode project directory.
This is the Config.plist:
- OPDS Feed URL: An array of dictionaries so you can setup multiple feeds. Only one content URL is required to get your app working.
- Authorisation: An array of dictionaries so you can setup multiple auth providers. Each containing:
- Endpoint: your auth proxy URL http://..
- Should POST: Boolean set to Yes or No if proxy accepts POST request - (we advise it should).
- Methods: The methods for your auth proxy, relative to your auth Endpoint.
- Sign In
- Renew Token (optional - remove if not supported by your server)
- Verify Subscription
- Edition Credentials
- User ID
- User Password
- Product ID
- App Store URL: Your iTunes receipt validator URL
- App Store Single Purchase Prefix: The prefix for your editions uuid (e.g. com.pugpig if your editions ID have the format com.pugpig.issue0001).
- App Store Subscriptions: This is an array of dictionaries, each containing a Name, Identifier and Duration (in days).
- Analytics: Optional, a dictionary where you now setup your third party analytics or push providers. See the analytics section.
We include Google Analytics in our installer so if you have a GA key you should enable by adding to the Analytics key:
- A new Dictionary item called "KGGoogleAnalytics"
- Inside this add a new String item called "Google Analytics Tracking ID"and add your GA key value to it
- Features: These provide the ability to customize some of the app's behaviour, turning some features on or off, or selecting a particular mode. Set the following to YES to enable.
- Enable Reset: turns on reset of feed option in Settings
- Enable Scrapbooking: turns on the scrapbook feature in toolbar and edition selector
- Enable Search: turns on the search in edition feature in toolbar
- Enable Text Resize: turns on text resize options in Settings. Three sizes are supported: 1x, 1.5x and 2x, based on the default font size of the content.
- Enable Night Mode: Requires CSS in your page templates to support the `pp-is-nightmode` class; when Night Mode is on, the app will inject the class on the HTML body
- Enable Wishlist: turns on the shopping wishlist feature in toolbar. The wishlist is for use alongside Pugpig Things and allows the users to add items/products to a wishlist. It requires shoppable content conforming to our Pugpig Things API to use.
- Enable Annotations: enables in page annotation note-taking feature.
- Prompt For Rating: turns on iRate if you want to prompt users to rate your app in the App Store. See the iRate section for more details.
- Toolbar Visibility: Set this to one of the following values `auto`, `autoTop` and `always`
- `Auto` toolbar vanishes when one scrolls down and reappears when flicking back up; it can also be toggled by bouncing the content at the top or double-tapping
- `AutoTop` is like `auto` but is always visible at the top
- `Always` means the toolbar is visible at all times and never hides or dismisses
There are some additional keys you can add to the Features part of your config.plist including:
- Storefront Style: set to 'Linear' - if you prefer a large cover carousel edition selector instead of the default grid design
Elements of your Pugpig for Magazines app can be themed using colours, logos, images and icons. Please view our PDF Design Guides for the app interface which helps demonstrate the theming flexibility. A full set of available theme keys you can use is also available here.
This design document is also available in Illustrator .ai format so your designers can skin the app and provide the right properties to your developers - contact email@example.com for a copy.
A minimum set of properties listed below are required for the app theme. These default properties and values will propagate through the app’s user interface, however most element's properties can be overridden using more specific keys. Colors can be specified as hex values (eg. #32FA56).
Element-specific fonts require both a Font and a FontSize property; in all cases make sure the font name is the full name or postscript name (e.g. Picker.FilterTabs.Font and Picker.FilterTabs.FontSize). Font sizes can be set with real values. As an example: enter 16 as a real value and assume units are pixels.
It's also possible to specify different values for phone and tablet, by adding ~phone or ~tablet to the key names (e.g. Document.BackgroundColor~phone).
This is the Theme.plist:
Minimum theme properties to be set:
Additionally, you can specify fonts that should be used within your content by using the Content Fonts key and providing a dictionary of font name (as key) and relative path to the font in the assets folder (as string).
More detail on all theming and localisable string elements can also be found here.
The copy is separated in three files, found in your Xcode project directory. Some defaults have been specified, but some of it will not be appropriate for your project; make sure you update this.
The localizable.strings contains various text strings that are spread throughout the app, with the following format:
"pugpig_a_tag_name" = "The copy that will appear in the app."
Keep the tag names as they are, and if you would like the text to be blank, leave an empty string ("") on the right-hand side. Do not remove the tag, as this may cause the tag to appear in the app.
Not all localizable strings are included in this file by default, but all the text can be overridden using the appropriate key, a complete list of which is available here.
The `settings_1.html` and `settings_2.html` contain the content of the Help and About sections in the settings. You can remove or add files using the same naming pattern to modify the number of sections. You can also do the same in Account by adding files named `account_1.html`, etc. Note that there is no need to style the html; a style tag will be inserted that applies properties that match those set in the Theming section.
PugpigForMagazines.xcassets contains all the assets for the document. This is where you can replace the various application icons and set your App Icon and Launch Images. In Xcode, you can simply drag your assets over the ones you would like to replace.
You can specify a logo to replace the text at the top of the table of contents (the text can also be modified) by adding a `tableofcontentslogo` item to the asset catalogue.
You can also add new assets to the catalogue to use as background images to the main application views - you will then need to specify them in the theme using the following keys (which fall back to their parent key if none is specified:
- Document.BackgroundImage -> BackgroundImage
- Scrapbook.BackgroundImage -> Document.BackgroundImage -> BackgroundImage
- Picker.BackgroundImage -> BackgroundImage
e.g. - setting `BackgroundImage` with value `gradient` in Theme.plist will set the image named `gradient` in your asset catalogue as the background image for the Picker, Document and Scrapbook).
Certain optional images can be specified by adding assets to the asset catalogue (PugpigForMagazines.xcassets).
- tableofcontentslogo - this replaces the text at the top of the table of contents with the specified image
- toolbarlogo - this replaces the section name in the toolbar with the specified image
You can also specify as many frames as you'd like for the playing animation, just follow the naming convention.
You can now override the following elements, if you don't like what we provide you can build and plug in your own for:
- Storefront (applicable to Pugpig for Magazines only)
- Table of Contents
- Analytics providers (due to licencing reasons we can't always embed the third party SDKs)
- Push providers (due to licencing reasons we can't embed the third party SDKs)
Contact us to request your licence. We will need App Name, Platform and Bundle ID. Once we have issued your Pugpig.licence file override the default file in your Xcode project's directory. If the bundle ID is correct this will remove the initial Pugpig Evaluation Copy launch message.
Prior or during the development of your app you will need to ensure you have the appropriate App Store developer accounts and app setup in place. Pugpig supports integration with iTunes, Amazon, Google Play, Windows and Blackberry App stores. Documentation on store setup and submission can be found on our Zendesk and on the relevant developer websites.
Thank you for choosing Pugpig. We are constantly striving to improve our product and documentation, please contact us at firstname.lastname@example.org if you have any questions, comments or feedback, we'd love to hear from you!
If you are having issues or diffculties with the product please let us know. We have a dedicated and knowledgable support team who are quick to respond. Email us with as much detail as possible about the issue, what you’re trying to achieve and any steps to reproduce and our support team will help you.