PocketMedia Native Ads library for web ad units
npm install pocketmedia-native-ads-libraryThe 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.
tag of the bundled version of the native ads library from our CDN on your website, like so: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.
#### 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.
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
example
``
pocket_native_ads.refresh();
example
``
pocket_native_ads.reload();
parameters
| Type | name | description |
| -------- | ----------- | ----------------------------------- |
| string[] | adUnitNames | The names of the ad units to remove |
example
``
pocket_native_ads.removeAdUnits(['featuredArticles']);
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 The following events are current available: |event name |Description| | #### events.addListener parameters | Type | name | description | example #### events.removeListener parameters | Type | name | description | example pocket_native_ads.events.removeListener('afterAdsInserted', afterAdsInserted);
`
pocket_native_ads.loadAdUnits([
{
name: 'medialist',
urlPatterns: ['/'],
containers: [{
xPath: '//div[@class="mediaList"]',
startIndex: 0,
interval: 2,
}],
htmlTemplate: '##campaign_name##
##campaign_description##',
}]);
`addListener$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.
|----------------|--------------------------------------------------------------------|
|afterAdsInserted|Fires when the ad library has inserted all ads to insert on the page|
To add a listener for a certain event, use the method.`
| -------- | ----------- | -------------------------------------------------- |
|string | eventName | The name of the event (e.g. 'afterAdsInserted') |
|function | callback | the callback to execute when the event is fired |`
pocket_native_ads.events.addListener('afterAdsInserted', function(currentAds) { console.log('ads inserted') });removeListener
To remove a listener for a certain event, use the method.`
| -------- | ----------- | -------------------------------------------------- |
|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 |`
function afterAdsInserted() {
console.log('after ads inserted');
}cd
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 pageContributing (build instructions)
$3
1. Install Node.js$3
1. to the project directorynpm install
2. Run grunt
3. Run (default build, Javascript browser library) or grunt build:phonegappm-native.js
4. and pm-native.min.js files are placed in dist directory, inside of browser and phonegap respective folders.npm install$3
1. Navigate to the project directory
2. Run to download the required dependenciesnpm test
3. Run to run the unit tests. Additionally, run npm run test:watch` to automatically retest when source files change