Follow

Android

This document guides you through the basic set up of a Pugpig for Magazines app on Android. It assumes access to development machine (Mac or PC) with Android Studio to build on, an Android device to test on, and an OPDS endpoint content feed along with any authorisation methods required.

Getting Started

Here are some step-by-step instructions to get started with Pugpig for Magazines on Android: 

  1. Download the latest Pugpig For Magazines v1.3.3 available here and unzip
  2. Run the provided SampleApp project in Android Studio - see section
  3. Configure your app - see section
  4. Theme your app - see section
  5. Update the copy - see section
  6. Update the assets - see section
  7. Extending your app (optional) - see section
  8. Include your Pugpig licence - see section
  9. Setup your app in the Amazon and Google Play stores - see section
  10. Submit, and you're done!

Android Studio

To build the SampleApp using Android Studio (v1.0+), choose Import Project (File menu) and select the SampleApp directory. Android Studio will then import the project. Wait for the Gradle plugin to sync. Accept any prompts presented.

To run the app, click the green triangle in the IDE toolbar, or select Run 'app' from the Run menu.

Note: To change the sample app's package Id, change the manifest's package attribute of SampleApp/app/src/main/AndroidManifest.xml from the current com.example.pugpigproducts.v1_3_3. You can change the application Id in SampleApp/app/build.gradle.

Configuring

Configure your Android application with the Config.plist xml file already supplied in the SampleApp/app/src/main/assets/ directory.

Important note about the plist files: Our property list files for configuration and theming are dictionaries. The plist filenames are case-sensitive.

All keys are specified by: <key>The key name</key>

The types used are:

  • string: <string>Some value</string>
  • boolean: <true/> or <false/>
  • integer: <integer>30</integer>
  • decimal: <real>26.0</real>

Unless otherwise specified, assume the type is string.

Below is a list of values you can set in the plist to configure your app including the content endpoint and authentication urls.

  • OPDS Feed URL: An array of dictionaries so you can setup multiple feeds. Only one content URL is required to get your app working. Try http://api.pugpig.com/feed/opds if you don't have one.

Payment and subscriptions integration settings

The keys in this section need to be set up specifically for your Android app and must not be copied unaltered from an iOS project.

  • Authorisation: An array of dictionaries, so you can setup multiple auth providers. There is one for each auth you want to use. Note that each provider has its own set of parameters. There are similarities but due to their varied nature they do differ.

Third-Party Auth Providers:

  • Store:you should use the value 'Pugpig' but if no value is specified this is assumed.
  • 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
  • Parameters: The parameters your auth proxy servers expect.
    • User ID
    • User Password
    • Token
    • Product ID

Google Play Store

    • Store: Mandatory - you must use the value 'Google'
    • Key: Mandatory - the Google Play authentication key unique to your app, provided in the Google Play admin site.
    • Endpoint: Mandatory - the URL of your Google Play receipt validator.
    • Single Purchase Prefix: Mandatory - the prefix for your editions uuid (e.g. com.pugpig if your editions id have the format com.pugpig.issue0001). Be careful with your prefixes - the provider won't be used if the prefix does not match the edition ID.
    • Subscriptions: An array of subscription dictionaries. (See below).

Amazon Store

To enable the Amazon Store API, your manifest must specify Amazon's ResponseReceiver. An example can be found in SampleApp/app/src/main/AndroidManifest.xml. To find out more, refer to Amazon's documentation: https://developer.amazon.com/public/apis/earn/in-app-purchasing/docs-v2/implementing-iap-2.0.

    • Store: Mandatory - you must use the value 'Amazon'
    • Endpoint: Mandatory - the URL of your Amazon receipt validator.
    • Single Purchase Prefix: Mandatory - the prefix for your editions uuid (e.g. com.pugpig if your editions id have the format com.pugpig.issue0001). Be careful with your prefixes - the provider won't be used if the prefix does not match the edition ID.
    • Amazon Store Subscriptions Parent: Amazon subscriptions have a parent id that you need to specify if you intend to sell subscriptions.
    • Subscriptions: An array of subscription dictionaries. (See below).

Subscriptions Dictionary

  • Name: The text shown to the user describing the subscription (e.g. "1 month")
  • Identifier: The product ID of the subscription. This must match the ID you specified in the store.
  • Duration: An integer of the number of days the subscription will be valid for.

Please note: If you do not want to make use of any of this functionality do not leave any of the keys above in your plist file. They can lead to exceptions if some are present and others are missing.

  • Analytics: Optional, an array of dictionaries where you now setup your third party analytics or push providers. One dictionary for each provider. We already include Google Analytics so if you have a GA account & key setup (including custom dimensions) you should enable by adding:
    • 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
    • In <project_folder>/app/build.gradle ensure you have the following:
      dependencies {
            ...
            compile 'com.google.android.gms:play-services:6.1.+'
            ...
          }

      See the analytics section for more information or if you wish to use a different third party service

  • Filters: Optional, filters on your content. These are added to the edition selector and will filter your content feed. We currently support one filter on by default to show Downloaded Editions.

  • 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 true to enable.
    • Mode: determines app's UI and behaviour for content. Defaults to Magazines UI. If your app uses the continuous publishing mode, you must specify 'Continuous'.
    • Enable Reset: turns on reset of feed option in Settings
    • 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 Scrapbooking: turns on single scrapbook feature, where users can save pages from an edition to their scrapbook on a device.
    • Enable Search: turns on search inside an edition
    • 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

App Copy

The default copy displayed in the app is built into the AAR as res/values/strings.xml. You can override the values by editing the supplied SampleApp/app/src/main/res/values/strings.xml file or creating your own.

The strings.xml contains various text strings that are spread throughout the app, with the following format:

<stringname="pugpig_a_tag_name">Copy will appear in app.</string>

Keep the tag names as they are, and if for any reason you want to the text to be blank, leave an empty string in the XML element. Do not remove the tag, as this could cause an exception.

The about.html and help.html files are in the assets/ directory in the AAR. Create your own version in app/src/main/assets/.

Note: there is no need to style the html; a style tag will be inserted that applies properties that match those set in the theme.

Theming

Elements of your Pugpig for Magazines app can be themed using colours, logos, images and icons. To change colours and background start with the Theme.plist file file already supplied in the SampleApp project's app/src/main/assets/ directory. 

Theme.plist

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. The framework deals with the density pixels internally, multiplying 16 by the device’s pixel density but you should be able to achieve the desired effect if you want to increase or decrease a font size with this.

<key>Picker.EditionLabel.TextColor</key>
<string>#383737</string>
<key>Picker.EditionLabel.FontSize</key>
<real>16</real>
<key>Picker.EditionLabel.Font</key>
<string>fonts/OpenSans-Bold</string>

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).

Minimum theme properties to be set:

  • FontName
  • BoldFontName
  • PrimaryColor
  • SecondaryColor
  • PrimaryBackgroundColor
  • SecondaryBackgroundColor
  • SelectionBackgroundColor
  • ToolbarColor

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):

<key>Content Fonts</key>
<dict>
  <key>Didot</key>
  <string>Didot.ttf</string>
</dict>

Fonts

We support custom fonts on Android but they require rewrite rules to work with your CSS. Documentation will follow soon. In the meantime contact support@pugpig.com if you wish to use and embed fonts.

Assets

Logos, icons, launch images and app icons are classed as assets. All the assets are specified in the res/drawable-... directories built in the AAR library. Versions are specified for ldpi, mdpi, tvdpi, hdpi, xhdpi, xxhdpi and xxxhdpi. You can override the values by replacing the supplied SampleApp/app/src/main/res/drawable-* files or creating your own. Please refer to the 'Drawable Sizes' document in the SampleApp docs/ directory for more information

You must provide your own drawable-xxxhdpi versions of: icon (your application's icon) launch_image (the splash screen) * logo (your logo)

You should create a version specific to each DPI. They can be auto-generated by an imaging editing program like Photoshop, or using one the freely downloadable tools.

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 drawable folders. Similarly, for the toolbarlogo.

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:

  • BackgroundImage
    • Document.BackgroundImage
      • Scrapbook.BackgroundImage
    • Picker.BackgroundImage

e.g. - setting BackgroundImage with value gradient will set the image named gradient in your asset catalogue as the background image for the Picker, Document and Scrapbook).

Extending your app

Use our How To Guides to find ways to extend your app further. You can now override the following integration points, if you don't like what we provide you can build and plug in your own custom elements for:

  • Table of Contents
  • Analytics providers (due to licensing reasons we can't always embed the third party SDKs)
  • Push providers (due to licensing reasons we can't embed the third party SDKs)

Configuring a content provider

Sometimes you want to display content in an external application. For example, you might have PDF or DOC file included in your edition. You can configure Pugpig to open such content for you by configuring the built in content provider:

  <provider
      android:name="com.kaldorgroup.pugpig.sharing.FileProvider"
      android:authorities="${packageName}.sharing.provider"
      android:exported="false"
      android:grantUriPermissions="true">
    <meta-data android:name="allowedExtensions" android:value="pdf" />
  </provider>

Set the allowedExtensions value to include all of the file extensions you'd like Pugpig to try to open using an external application. By default, pdf files are enabled. You can add others as a comma-separated list.

Installing your Pugpig licence

Once you have your Pugpig.licence file place it in your project's app/src/main/assets/ directory. This will remove the initial Pugpig Evaluation Copy launch message.

Submission

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.

Support

Thank you for choosing Pugpig. We are constantly striving to improve our product and documentation, please contact us at support@pugpig.com if you have any questions, comments or feedback, we’d love to hear from you!

If you are having issues or difficulties 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.  

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk