npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

pocketmedia-native-ads-library

v1.2.3

Published

PocketMedia Native Ads library for web ad units

Downloads

15

Readme

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