pocketmedia-native-ads-library

About the package

This repository contains the code for the JavaScript library that powers Pocket Media Native Ads on websites and Phonegap/Cordova applications.

The native ads library interprets native ad configurations created in the Pocket Media dashboard and inserts them on a webpage or phonegap/cordova application on the locations that you've specified in the configuration.

A simple way to describe its flow can be:

1. The library loads the configuration for the current page/url (a configuration consists of a container reference, and markup code)
2. The library looks for the container(s) in the current context (page/url)
3. The library injects the ads, with the specified markup, after applying the replacement macros (to add ad title, URL, images, etc)

In the web version, the library downloads the ads configurations from the server, and applies the corresponding layout to the current webpage. Alternatively, the configuration can be defined client-side, allowing any kind of markup or logic.

Requirements

For more information on what this library is for and how to use it, sign up for the Pocket Media Native Ads platform to start monetizing your mobile website or Phonegap application on our website This library takes care of the insertion of native ads, based on the native ads configuration created through the Pocket Media User dashboard / Native ad builder.

Using the native ads library

There are multiple ways to include the native ads library on your website.

Through a <script> tag (simple)

The easiest way to start displaying native ads on your website on phonegap application, is by including a <script> tag of the bundled version of the native ads library from our CDN on your website, like so:

<script type="text/javascript" src="https://s3.eu-central-1.amazonaws.com/pmnativeads/library/current/pm-native.min.js" data-application-id="123" async></script>

You need to specify the application ID which can be seen in the Pocket Media dashboard in the data-application-id attribute to specify to the native ads library which native ad configurations it should use.

Using the npm module (advanced)

Installing the module

Run npm install pocketmedia-native-ads-library --save to install the native ads library as a dependency

Using the module with configurations created with the Native Ad Builder

After creating native ad configurations for your website: from the simplest integration through the automatic configuration via our dashboard, to the completely customizable method that allows you to specify manually any parameter.

var NativeAds = require('pocketmedia-native-ads-library');
var nativeAdsManager = new NativeAds.Manager(NativeAds.environments.browser, { applicationId: 1 });

nativeAdsManager.init(); //This will insert the ads on the current page

The native ads library will automatically retrieve the native ad configurations you've created through the Pocket Media dashboard and insert them on the correct positions based on the given applicationId.

Using the module with custom native ad configurations.

Instead of using the native ad builder, it is also possible to create your own custom native ad configurations. You can pass these custom configurations to the native ads library, and it will insert native ads based on your custom configuration on the current page.

var NativeAds = require('pocketmedia-native-ads-library');
var featuredAdUnit = require('../adunits/featured');
var nativeAdsManager = new NativeAds.Manager(NativeAds.environments.browser, { applicationId: 1 });

nativeAdsManager.loadAds([featuredAdUnit]); //The native ads library will insert native ads based on the configuration of the featuredAdUnit

Refer to the documentation to learn how to write custom native ad configurations.

API

The native ads library has a small API that allows you to interact with the library and the ads displayed on your page.

When the library is included through a script tag, a global pocket_native_ads will become available which allows you to use the API.

When loading the library as a module, the API functions are available on the nativeAdsManager, the instance of the Native Ads Manager

refresh

Removes all the current ads displayed and inserts all the new ads that should run on the current page

example

pocket_native_ads.refresh();

reload

Reloads the entire native ads library.

example

pocket_native_ads.reload();

removeAdUnits

Removes ad units with the given names from the page.

parameters

| Type | name | description | | -------- | ----------- | ----------------------------------- | | string[] | adUnitNames | The names of the ad units to remove |

example

pocket_native_ads.removeAdUnits(['featuredArticles']);

removeAllAds

Removes all the ads currently inserted

example

pocket_native_ads.removeAllAds();

loadAdUnits Loads the given custom ad units

parameters

| Type | name | description | | -------- | ----------- | -------------------------------------------------- | | object[] | adUnits | Array containing the details of ad units to insert |

example

pocket_native_ads.loadAdUnits([
  {
    name: 'medialist',
    urlPatterns: ['/'],
    containers: [{
      xPath: '//div[@class="mediaList"]',
      startIndex: 0,
      interval: 2,
    }],
    htmlTemplate: '<div><h1>##campaign_name##</h1><a href="##click_url##">##campaign_description##</a>',
  }]);

events

The events API allows you to add listeners to certain events that occur in the native ads library. This allows you to execute custom logic after certain operations.

The following events are current available:

|event name |Description| | |----------------|--------------------------------------------------------------------| |afterAdsInserted|Fires when the ad library has inserted all ads to insert on the page|

events.addListener

To add a listener for a certain event, use the addListener method.

parameters

| Type | name | description | | -------- | ----------- | -------------------------------------------------- | |string | eventName | The name of the event (e.g. 'afterAdsInserted') | |function | callback | the callback to execute when the event is fired |

example

pocket_native_ads.events.addListener('afterAdsInserted', function(currentAds) { console.log('ads inserted') });

events.removeListener

To remove a listener for a certain event, use the removeListener method.

parameters

| Type | name | description | | -------- | ----------- | -------------------------------------------------- | |string | eventName | The name of the event to remove the listener from (e.g. 'afterAdsInserted') | |function | callback | The function current registered to the event listener |

example

function afterAdsInserted() {
  console.log('after ads inserted');
}

pocket_native_ads.events.removeListener('afterAdsInserted', afterAdsInserted);

When included on a page, the library executes the following flow:

1. Obtain the application ID of the publisher's application
2. Retrieve the native ad configurations (from the OfferEngine API) that should run on the current page, based on the applicationID, the current pathname, and the device of the user currently visiting the page.
3. Iterate over the configurations that should get inserted on the page (if any)
4. Interpret each configuration: Where should the ad be placed (does this container exist), how many ads should get inserted?
5. Request the required number of ads to insert from the OfferEngine API
6. Merge the details of the advertisement with the HTML template of the ad configuration
7. Insert the native ad on the page

Contributing (build instructions)

Pre-requisites

1. Install Node.js

Building the project

1. cd to the project directory
2. Run npm install
3. Run grunt (default build, Javascript browser library) or grunt build:phonegap
4. pm-native.js and pm-native.min.js files are placed in dist directory, inside of browser and phonegap respective folders.

Testing the project

1. Navigate to the project directory
2. Run npm install to download the required dependencies
3. Run npm test to run the unit tests. Additionally, run npm run test:watch to automatically retest when source files change