How To Use Pugpig Promos

A promo slot can be displayed in your edition selector and used to promote or advertise virtually anything, as well as up-sell content inside your app.

Note: Pugpig Promos are available to use as a native module for Pugpig SDK (iOS v2.3+ | Android) and included in Pugpig for Magazines (iOS v1.1+ | Android) applications. Our server products including our Drupal Connector (v7.x-1.14+) also supports them. Web support coming soon.

A promo is a server-driven image (of any aspect ratio) served to your app container to trigger an external URL to open in an embedded webview, or actions in the app like a subscription purchase. The information is provided by a JSON file specified at the OPDS feed root level. The JSON file tells your container how/when to display the Promo Slot and what functionally to give it.

If you use a static endpoint, you can add a promo slot to your app container by doing two things:

  1. Create a JSON files with all the details of your Promo Slot(s)
  2. Add a link to you OPDS feed to the JSON

The root level of the JSON must be a dictionary. To add a Promo Slot to the JSON a new child dictionary needs to be added to the root dictionary. Here are the required and optional attributes to be specified within the child dictionary for the Promo Slot:


  • type [string] - e.g "PPfMPromoSlot"
    This is the Things type and is currently not used but is required by our Pugpig Things spec for future implementation.
  • promo_type [string] - e.g "generic"
    This is used to decide when a Promo Slot should be displayed for example if the user is logged in, don't show a subscription promo. The rules and logic are pre-defined in Pugpig for Magazines. Available types: "generic" *default if nothing is set*, "subscription", "login". Future support planned for single issue purchases and downloads.


  • platforms (optional) [array] - e.g "ios-phone"
    An array of platforms identifier strings that limit the Promo Slot to be displayed only on the specified platforms in the array. Available options: "ios-phone", "ios-tablet", "android-phone" and "android-tablet".
  • placement (optional) [string] -  e.g "hero"
    This is to let the app know where to place this Promo Slot in the edition selector. Pugpig for Magazines recognizes “hero” for primary placement of a promo before the most recent edition cover. See Promo Placement
  • spacing (optional) [string] - e.g "2"
    Inter-item spacing. For situations where multiple slots might be inserted in the document picker or elsewhere, a suggestion of distance between itself and other promos. In PPfM the spacing is interpreted as number of covers e.g "5" for 5 covers gap. You can also specifiy column spacing e.g "2c" for 2 columns of covers gap
  • layout (optional) [string] - e.g "2x1"
    width x height: desired size in grid units. Appropriate for situations such as PPfM where promos are inserted the document picker grid. If one dimension isn’t specified, it is inferred based on the image aspect ratio. If neither is given major dimension is matched and aspect ratio is maintained. The following is intended but unimplemented: h or v could be used to limit this promo slot to horizontal or vertical scrolling edition selectors eg: h:2x, v:1x2, :x2

Image promos:

A promo is a server-driven image (of any aspect ratio) served to your app container to trigger an external URL to open in an embedded webview, or actions in the app like a subscription purchase.


  • class (optional) should be "KGPromoSlotImage"
  • images.url (required) [array] - e.g ""
    Image URLs, multi-value. Also requires images.dimensions in order to select most appropriate image. Must be absolute URL.
  • images.dimensions (required) [array] - e.g "30x100"
    This sets the width x height: resolution in pixels; used to pick appropriate image for phone vs. pad, retina, etc.One entry is required for each images.url, with matching index.
  • link (required) - e.g ""
    This defines the action performed when user taps on the Promo Slot.Available options: "pugpig://subscribe", "pugpig://login", "http(s)://". Future support planned for “pugpig://download?editionId".
{ "promoslot/hero/0001" : 
"type" : "PPfMPromoSlot",
"promo_type" : "generic",
"placement" : "hero",
"platforms" : [ "ios-tablet" ],
"title" : "Promo slot 1",
"summary" : "This is a summary",
"link" : "pugpig://login",
"images.url" : [ "", "" ], "images.dimensions" : [ "30x100", "60x200" ],

DFP promos:

DFP promos are supported on iOS if you link in the Kaldor DFP module and the Google Mobile Ads framework for iOS. 

  • class (required) should be "KGPromoSlotDFP"
  • size (required) – e.g "320x50"
    This sets the width x height: resolution in points of the ad. Size must be one of the supported sizes listed here.
{ "promoslot/googlemobileads/0001" : 
"class" : "KGPromoSlotDFP",
"type" : "PPfMPromoSlot",
"promo_type" : "generic",
"title" : "Promo slot 1",
"summary" : "This is a summary",
"size": "320x50",


In the OPDS feed add the following link to your json file:

<link type="application/json" href="promoslots.json" rel="" dcterms:modified="2014-07-21T13:25:12+01:00"/>

If you use one of our Pugpig Connectors see the Server How To Guides for Wordpress or Drupal on how to add a promo image via your CMS.

DFP Promos in Pugpig currently only support the Banner Sizes specified here. Smart banner and custom ad sizes listed on that page aren't supported at the moment.

In features, add:



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


Powered by Zendesk