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.

$3

The easiest way to start displaying native ads on your website on phonegap application, is by including a

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.

$3

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

`$3`


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

example`pocket_native_ads.refresh();`

`$3`


Reloads the entire native ads library.

example`pocket_native_ads.reload();`

`$3`


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']);`

`$3`


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

`##campaign_name##`

##campaign_description##',
  }]);


$3

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 theaddListener 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 theremoveListener 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)`

`$3`


1. Install Node.js
$3

1.

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

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