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

admanager

v0.6.4

Published

A JavaScipt library for interacting with Google DFP.

Downloads

18

Readme

AdManager

A JavaScipt library for interacting with Google DFP.

Introduction

AdManager is a JavaScript library for interacting with Google Publisher Tags (GPT) and Google DFP. It handles the loading of the GPT library as well as the definition and request of ad inventory. Below you’ll find documentation on its configuration and usage.

Installation

Bower

Use the Bower package manager to install AdManager into your project. To do so you can either use the CLI:

$ bower install admanager --save

Or define it in your bower.json manifest:

    "dependencies": {
        "admanager": "latest"
    }

npm

Similarly, AdManager can be installed using npm. To do so you can either use the CLI:

$ npm install admanager --save

Or define it in your package.json manifest:

    "dependencies": {
        "admanager": "latest"
    }

Direct download

If package managers are not your thing, the library can be downloaded directly from GitHub using the Download ZIP button.

Basic Usage

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>AdManager Usage</title>
    <script src="jquery.js"></script>
    <script src="AdManager.min.js"></script>
</head>
<body>
    <!--
    This is the ad unit container. AdManager looks for all of the
    [data-ad-unit] in the DOM and grabs the slot name to make a
    request from DFP to fill those units.
    -->
    <div data-ad-unit="Unit_Name_in_DFP"></div>

    <script type="text/javascript">
        ( function () {

            var config = {
                account: 1234567,
                inventory: [
                    {
                        slot: 'Unit_Name_in_DFP',
                        sizes: [
                            [ 728, 90 ],
                            [ 970, 250 ],
                            [ 1000, 220 ]
                        ]
                    }
                ]
            };

            AdManager( config );

        } () );
    </script>
</body>
</html>

Configuration

A configuration object is required to initialize the AdManager.

| key | type | | ---------------------------------------- | ------- | | account | Integer | | autoload | Boolean | | clientType | String | | inventory | Array | | context | String | | enabled | Boolean | | targeting | Array | | insertionEnabled | Array | | insertion | Object |

Example Configuration:

{
    account: 1234567,
    clientType: 'desktop',
    inventory: [
        {
            slot: 'Unit_Name_in_DFP',
            sizes: [
                [ 728, 90 ],
                [ 970, 250 ],
                [ 1000, 220 ]
            ]
        }
    ]
}

account

Type: Integer

Default: null, must be specified

Description: Your network code, found in the “Admin” tab of DFP.

:arrow_up:

autoload

Type: Boolean

Default: true

Description: Whether to start the qualification process automatically.

:arrow_up:

clientType

Type: String

Default: 'default', optional

Description: This declares the client type (such as desktop, tablet, or mobile). The value can be set by an external client-detection script and will be used to compare against each inventory item to see whether the item should be displayed or not for that client.

For example, if a desktop device is detected, this value should be set to clientType: 'desktop' and items in the inventory array that match (type: 'desktop') will be displayed. This allows you to include both desktop and mobile inventory items, but only show the appropriate ones according to what clientType is set to at load time.

:arrow_up:

inventory

Type: Array

Default: [], must be specified

Description: An array of one or more objects that define different ad types. See the Inventory section below. More information can be found in the inventory section below.

Example:

var config = {
    // ...
    inventory: [
        {
            slot: 'Unit_Name_1',
            sizes: [
                [ 728, 90 ],
                [ 970, 250 ],
                [ 1000, 220 ]
            ]
        },
        {
            slot: 'Unit_Name_2',
            sizes: [
                [ 728, 90 ],
                [ 970, 250 ],
                [ 1000, 220 ]
            ]
        },
        // ...
    ]
};

:arrow_up:

context

Type: String

Default: 'body', optional

Description: This is used as a jQuery selector that specifies the DOM context where ads are to be inserted. In standard cases this will be static since there will only be one page. In infinite scroll applications, there may exist multiple pages in a single window and this provides a way to distinguish one page/context from another.

:arrow_up:

enabled

Type: Boolean

Default: true, optional

Description: This provides a way to disable the AdManager.

:arrow_up:

insertionEnabled

Type: Boolean

Default: false, optional

Description: Whether to enable dynamic insertion.

:arrow_up:

insertion

Type: Object

Example Insertion:

{
    pxBetweenUnits: 800,
    adHeightLimit: 1000,
    insertExclusion: [
        'img',
        'iframe',
        'video',
        'audio',
        '.video',
        '.audio',
        '[data-ad-unit]'
    ]
}

insertion.insertExclusion

Type: Array

Default:

[
    'img',
    'iframe',
    'video',
    'audio',
    '.video',
    '.audio',
    '[data-ad-unit]'
]

Description: When using the dynamic insertion feature, this allows customization of what elements to exclude when looking for valid insertion points.

:arrow_up:

insertion.pxBetweenUnits

Type: Integer

Default: 800, optional

Description: The minimum distance between dynamically inserted units.

:arrow_up:

insertion.adHeightLimit

Type: Integer

Default: 1000, optional

Description: The max height for dynamically inserted units.

:arrow_up:

Inventory

The inventory array is a collection of objects that represent different ad positions.

| property name | type | | | ------------------------------- | ------- | -------------------------------------- | | slot | String | | | sizes | Array | | | type | String | | | dynamic | Boolean | | | localContext | String | optional (required if dynamic: true) |

Example Usage:

var config = {
    // ...
    inventory: [
        {
            slot: 'Article_Leaderboard',
            sizes: [
                [ 728, 90 ],
                [ 970, 250 ],
                [ 1000, 220 ]
            ],
            type: 'desktop',
            dynamic: false
        },
        {
            slot: 'Article_Dynamic',
            sizes: [
                [ 300, 250 ],
                [ 300, 600 ]
            ],
            type: 'desktop',
            dynamic: true,
            localContext: '.entry-content'
        }
        // ...
    ]
};

slot

Type: String

Description: The slot name defined in DFP.

:arrow_up:

sizes

Type: Array

Description: An array of accepted sizes for this unit. Must match up to the sizes defined in DFP.

:arrow_up:

type

Type: String

Description: This can be used to categorize inventory. For example, it can be used to denote whether an unit is for desktop or mobile devices. This value is checked against clientType.

:arrow_up:

dynamic

Type: Boolean

Default: false

Description: This enables/disables dynamic insertion. If set to false, AdManager will expect a container on the page with the data-ad-unit attribute value that corresponds to the slot name defined in the Inventory object.

:arrow_up:

localContext

Type: String

Description: This is needed only for dynamic insertion. The string is a jQuery selector that specifies an insertion point for the new ad.

Example:

var config = {
    // ...
    inventory: [
        // ...
        {
            slot: 'Article_Dynamic',
            sizes: [
                [ 300, 250 ],
                [ 300, 600 ]
            ],
            type: 'desktop',
            dynamic: true,
            localContext: '.entry-content'
        }
        // ...
    ]
};

:arrow_up:

Events

Custom jQuery events prefixed with AdManager.

| event | trigger source | | ---------------------------------------------------------------- | --------------- | | AdManager:libraryLoaded | internal | | AdManager:adUnitRendered | internal | | AdManager:slotsDefined | internal | | AdManager:refresh | external | | AdManager:runSequence | both | | AdManager:emptySlots | external | | AdManager:emptySlotsInContext | external | | AdManager:importConfig | both |

AdManager:libraryLoaded

Description: This is triggered once when the GPT library is loaded.

:arrow_up:

AdManager:adUnitRendered

Description: This is triggered each time an ad is rendered. Bind to this event to receive notification of a particular ad that has rendered.

Parameter: unit {Object}

| name | type | description | | ------------- | ------- | --------------------------------------------------------- | | name | String | The slot name defined in DFP. | | id | String | HTML id for the current ad wrapper. | | size | Array | Indicates the pixel size of the rendered creative. | | isEmpty | Boolean | true if no ad was returned for the slot, false otherwise. | | creativeId | String | Creative ID of the rendered ad. | | lineItemId | String | Line item ID of the rendered ad. | | serviceName | String | Name of the service that rendered the slot. |

:arrow_up:

AdManager:slotsDefined

Description: This is triggered when slots are successfully defined, but before ads are rendered.

:arrow_up:

AdManager:refresh

Description: Pass an array of slot names to be refreshed. Slots should already be in the DOM.

Example Usage:

$.event.trigger( 'AdManager:refresh', [ 'Unit_Name_1', 'Unit_Name_2' ] );

:arrow_up:

AdManager:runSequence

Description: Trigger to run the full qualification sequence: the identification of positions in the DOM, define of DFP slots, targeting, request for creative, and display.

Example Usage:

$.event.trigger( 'AdManager:runSequence' );

:arrow_up:

AdManager:emptySlots

Description: Pass an array of slot names to be emptied.

Example Usage:

$.event.trigger( 'AdManager:emptySlots', [ 'Unit_Name_1', 'Unit_Name_2' ] );

:arrow_up:

AdManager:emptySlotsInContext

Description: Pass an array of slot names to be emptied within a selection.

Example Usage:

$.event.trigger( 'AdManager:emptySlotsInContext', {
    $context: $( '.entry-content' ), // Defaults to the context set in the config.
    removeContainer: true // Defaults to true
} );

:arrow_up:

AdManager:importConfig

Description: Pass an object to import new configuration values. The new config will override values in the current config.

Example Usage:

$.event.trigger( 'AdManager:importConfig', {
    targeting: {
        category: [
            'athletics',
            'technology',
            'graphic design'
        ]
    }
} );

:arrow_up:

Dynamic Insertion

Overview

Note: This feature is optional.

This feature allows AdManager to dynamically insert a variable number of new ad positions on the fly, without predetermined ad containers. The Insertion.js module contains logic that analyzes the DOM nodes in a specified text area to determine the optimal places where to insert ads.

Instructions

  • Add new inventory items that reflect the maximum possible number of dynamically inserted ads.
  • Set the additional options dynamic and localContext in the inventory config.
var config = {
    // ...
    inventory: [
        // ...
        {
            slot: 'Dynamic_Unit_1',
            sizes: [
                [ 300, 250 ],
                [ 300, 425 ],
                [ 300, 600 ]
            ],
            type: 'desktop',
            dynamic: true,
            localContext: '.entry-content'
        },
        {
            slot: 'Dynamic_Unit_2',
            sizes: [
                [ 300, 250 ],
                [ 300, 425 ],
                [ 300, 600 ]
            ],
            type: 'desktop',
            dynamic: true,
            localContext: '.entry-content'
        },
        {
            slot: 'Dynamic_Unit_3',
            sizes: [
                [ 300, 250 ],
                [ 300, 425 ],
                [ 300, 600 ]
            ],
            type: 'desktop',
            dynamic: true,
            localContext: '.entry-content'
        }
    ]
};

AdManager( config );
  • If a more specific outer/main context is needed (the default context is body), the property context can be added to the config. This is needed when keeping multiple contexts or articles separate, such as in infinite scroll applications. In the example below, it is .hentry.
<body>
    <div class="hentry">
        <div class="entry-content">
            <p>Paragraph 1</p>
            <p>Paragraph 2</p>
            <p>Paragraph 3</p>
        </div>
    </div>

    <script type="text/javascript">
        ( function () {

            var config = {
                // ...
                context: '.hentry',
                inventory: [
                    {
                        // ...
                        dynamic: true,
                        localContext: '.entry-content'
                        }
                    ]
                }
            };

            AdManager( config );

        } () );
    </script>
</body>

Contributing

Coding Style

AdManager follows the WordPress JavaScript Coding Standards. There is a .jscsrc included in the project for automatic linting using JSCS.

The modules are written in the UMD pattern to support AMD, CommonJS, and global usage.

Development

The project contains a gulpfile.js for concatenation and minification. To use first install gulp and the dependencies (npm install). The default gulp task (gulp) will start the watch task.

Dependencies

AdManager requires jQuery.

References