Follow

Android

This document guides you through the basic set up of a Pugpig for Continuous Publishing 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 on Android: 

  1. Download the latest .aar file from our website here
  2. Create a new Android Studio (Gradle) project; minimum SDK 14 (Android 4.0 - ICS)
  3. Reference the AAR - see section
  4. Update the Gradle build file - see section
  5. Your AndroidManifest.xml file - see section
  6. Configure your app - see section
  7. Theme your app - see section
  8. Update the copy - see section
  9. Update the assets - see section
  10. Integrate your analytics framework (optional) - see section
  11. Include your Pugpig licence - see section
  12. Setup your app in the Amazon and Google Play stores - see section
  13. Submit, and you're done!

Reference the AAR

You need to place the pugpigproducts.aar library in your project's app/libs directory (create the directory if it does not already exist).

Update the Gradle build file

You need to modify the app/build.gradle file to add the AAR as a reference.

Recommended defaults are:

android {
  compileSdkVersion 19 // Android 4.4 KitKat
  buildToolsVersion "19.1.0"

  defaultConfig {
    applicationId "{{your package name goes here}}"
    minSdkVersion 14 // Android 4
    targetSdkVersion 19 // Android 4.4 KitKat
    versionCode 1 // Your app's version code
    versionName "1.0" // Your app's version number
  }
  ...
}

First by allowing a local directory to be a repository:

repositories {
  // ... anything already defined here
  flatDir {
    dirs 'libs' // Where pugpigproducts.aar is
  }
}

Secondly,by referencing the dependency:

dependencies {
  // ... anything already defined here
  compile(name:'pugpigproducts', ext:'aar')
}

 

Your AndroidManifest.xml file

Then you need to amend your app/src/main/AndroidManifest.xml file:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="{{your package name goes here}}">

    <application>

        <!-- Needed so Android Studio knows which activity to launch: -->
        <activity android:name="com.kaldorgroup.pugpig.products.StartViewController">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

        <!-- Needed to share images (e.g. for sharing to email): -->
        <provider
            android:name="com.kaldorgroup.pugpig.sharing.FileSharingProvider"
            android:authorities="${packageName}.pugpig.products.FileSharingProvider"
            android:exported="true"
            android:grantUriPermissions="true">
        </provider>

    </application></manifest>

Configuring

You configure the Android application with a Config.plist xml file. Download Sample Config.plist file and place in your project's app/src/main/assets/ directory.

Important note about the plist files: Our property list files for configuration and theming are dictionaries.

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

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

    • 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, 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.
    • Mode: determines app's UI and behaviour for content and uses Magazines by default. As you plan to use the continuous publishing mode, you must set it to '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
    • 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

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.

App Copy

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

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

<stringname="ppfm_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 app can be themed using colours, logos, images and icons with a simple Theme.plist file. Download Sample Theme.plist file and place in your 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).

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 in the AAR. Versions are specified for ldpi, mdpi, tvdpi, hdpi, xhdpi, xxhdpi and xxxhdpi. Please refer to the 'Drawable Sizes' document.

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

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

Analytics

Pugpig Products comes with our default Google Analytics implementation. Just add your GA key to the Config.plist to enable it.

If you wish to integrate with another third party analytics service e.g Omniture, Flurry please contact support@pugpig.com.

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

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

Comments

Powered by Zendesk