@fnet/gpt

Introduction

@fnet/gpt is a module designed to manage Google Publisher Tag (GPT) advertisements on web pages. Its primary purpose is to simplify the integration and handling of ads, ensuring that they are loaded and displayed efficiently without interfering with other page functionalities. The module allows for flexibility in defining and refreshing ad slots with an event-driven approach for handling ad renders.

How It Works

This module operates by integrating with Google's GPT library. It initializes the necessary configurations to manage ad slots and renders them on demand. Users can define where and how ads should appear, with capabilities to update, refresh, or replace ad slots dynamically. The module provides an API for listening to ad-related events, allowing developers to respond accordingly when ads are successfully rendered or encounters issues.

Key Features

• Ad Slot Management: Define, replace, and remove ad slots easily.
• Event Handling: Receive notifications for ad rendering events through an event-driven system.
• Responsive Sizing: Adjusts ad sizes based on available space, with configurations for maximum and minimum dimensions.
• Dynamic Loading: Refresh ad slots on-demand, supporting single ad requests or multiple at once.
• Error Handling: Built-in error notifications for handling failed ad loads effectively.

Conclusion

@fnet/gpt offers a straightforward solution for incorporating and managing GPT advertisements on your website. While it provides essential features for ad handling, it remains focused on utility without excessive complexity, making it suitable for developers looking for reliable ad management capabilities without the need for extensive customization.

Developer Guide for @fnet/gpt

Overview

The @fnet/gpt library provides a streamlined way to manage Google Publisher Tags (GPT) for dynamic ad loading in web applications. This library encapsulates common ad-related operations such as defining ad slots, managing ad rendering, and refreshing ads. It simplifies the integration of GPT by handling script loading and event management, providing a more manageable and concise interface for developers.

Installation

To use the @fnet/gpt library in your project, install it via npm or yarn:

npm install @fnet/gpt

or

yarn add @fnet/gpt

Usage

Here we'll demonstrate how you can use the @fnet/gpt library to integrate and manage ads within your application. We assume basic knowledge of web development and familiarity with ad networks.

Firstly, import and initialize the GPT manager:

import Gpt from '@fnet/gpt';

// Initialization
(async function initializeAds() {
    const adManager = await Gpt({
        slot: { 
            getSlot: async () => ({
                adUnitPath: '/1234567/sports',
                sizes: [[300, 600], [728, 90]],
                targeting: {"test": "value"}
            })
        },
        container: document.getElementById('ad-container'),
        keepSizes: true
    });

    adManager.requestAds();

    // Optional: You can listen to events like on impression or error
    adManager.on('impression', (event) => {
        console.log('Ad Impression:', event);
    });

    adManager.on('error', (error) => {
        console.error('Ad Error:', error);
    });
})();

Examples

Define and Display an Ad Slot

(async function defineAdSlot() {
    const adManager = await Gpt({
        slot: { 
            getSlot: async () => ({
                adUnitPath: '/1234567/news',
                sizes: [[300, 250], [728, 90]],
            })
        },
        container: document.getElementById('my-ad-container'),
    });

    adManager.requestAds();
})();

Refresh an Ad Slot

(async function refreshAd() {
    const adManager = await Gpt({ /* initialization params */ });

    // Refresh the ads associated with the current slots
    await adManager.refreshAds();
})();

Replace an Existing Slot

(async function replaceAdSlot() {
    const adManager = await Gpt({ /* initialization params */ });

    // Function to replace an ad slot with a new configuration
    await adManager.replaceSlot({
        slot: {
            getSlot: async () => ({
                adUnitPath: '/1234567/tech',
                sizes: [[160, 600], [300, 250]],
            })
        },
        define: true
    });
})();

Acknowledgement

The @fnet/gpt library builds upon the event management capabilities of EventEmitter3 and uses nanoid for generating unique IDs.

Input Schema

$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
  slot:
    type: object
    description: The slot configuration object.
  keepSizes:
    type: boolean
    description: Flag to keep sizes unchanged.
  container:
    type: object
    description: HTML element serving as the ad container.
  maxWidth:
    type: integer
    description: Maximum allowed width for the ad.
  minWidth:
    type: integer
    description: Minimum allowed width for the ad.
  maxHeight:
    type: integer
    description: Maximum allowed height for the ad.
  minHeight:
    type: integer
    description: Minimum allowed height for the ad.
required:
  - slot
  - container