@bygd/opus-hl

Introduction

The @bygd/opus-hl project provides a script that manages header bidding configurations for web applications. It helps simplify the integration and configuration process for header bidding solutions, potentially optimizing ad revenue for publishers. This utility dynamically loads and configures header bidding scripts based on specific site configurations and targeting criteria.

How It Works

@bygd/opus-hl operates by loading a set script for header bidding and configuring it according to the page's parameters and targetings, such as the page URL and specific targeting keys for advertisements. It overrides certain aspects of configuration to align advertising slots with the site's requirements and makes it possible to customize how ads are served, including altering slot sizes and targeting keys.

Key Features

• Dynamic Script Loading: Automatically loads the header bidding script from a specified source, ensuring up-to-date configurations.
• Configurable Bid Adjustments: Allows modification of configuration options like slot sizes and targeting adjustments for better ad placements.
• Supports Geo-Targeting and Slot Customization: Adjust advertisement slots dynamically based on location and user-provided targeting data.
• Caches Configuration: Maintains a cached instance, optimizing repeated initializations and reducing unnecessary overhead on repeated page loads.

Conclusion

@bygd/opus-hl offers a straightforward way to integrate and manage header bidding solutions on web pages. By providing an easy-to-use interface for configuring ad slots and targeting attributes, it facilitates a smoother ad revenue optimization process for web publishers.

@bygd/opus-hl Developer Guide

Overview

The @bygd/opus-hl library is designed to assist developers in managing and optimizing header bidding configurations for web pages. It integrates with different advertising scripts and platforms to streamline the advertisement setup process. The main features include setting up and merging configurations for dynamic ad loading and targeting on web pages, with support for video ad slots.

Installation

To install the @bygd/opus-hl library, use either npm or yarn package manager:

npm install @bygd/opus-hl

or

yarn add @bygd/opus-hl

Usage

Below is an example of how you can initialize and use the @bygd/opus-hl library in a typical web application setting:

Initialization

First, you need to import and initialize the library in your script:

import opusHL from '@bygd/opus-hl';

const initializeHeaderLift = async () => {
  try {
    const hlInstance = await opusHL({
      pageUrl: window.location.href,
      gptTargeting: { key1: 'value1', key2: 'value2' }, // replace with actual targeting keys and values
      config: userProvidedConfig // replace with any user-defined configuration or omit to use the default
    });
    
    console.log('Header Lift Initialized:', hlInstance.config);
  } catch (error) {
    console.error('Failed to initialize Header Lift:', error);
  }
};

initializeHeaderLift();

Merging Configurations

If you need to merge additional configurations such as video targeting information or updates on page URL, you can use the mergeWith function:

const mergeAdditionalConfig = async () => {
  try {
    const hlInstance = await opusHL(); // Retrieve the cached instance

    await hlInstance.mergeWith({
      pageUrl: "https://example.com/new-page",
      gameId: "your-game-id",
      videoTargeting: { vidKey1: 'vidValue1', vidKey2: 'vidValue2' }
    });

    console.log('Configurations Merged:', hlInstance.config);
  } catch (error) {
    console.error('Failed to merge configurations:', error);
  }
};

mergeAdditionalConfig();

Examples

Basic Configuration

To set up a basic header lift configuration with default settings:

opusHL({ pageUrl: 'https://example.com' });

Custom GPT Targeting

To apply custom Google Publisher Tag (GPT) targeting:

opusHL({
  gptTargeting: {
    age: '25-34',
    interests: 'technology'
  }
});

Merge and Update Dynamic Content

To update and refine configurations based on user interactions or page changes:

hlInstance.mergeWith({
  gameId: 'new-game-id',
  videoTargeting: {
    category: 'gaming',
    viewer: 'enthusiast'
  }
});

Acknowledgement

Special thanks to the contributors who support and maintain this library, helping to make header bidding configurations more efficient and manageable for developers on various platforms.

Input Schema

$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
  pageUrl:
    type: string
    format: uri
    description: The URL of the page. Defaults to the current window's location.
  gptTargeting:
    type: object
    additionalProperties:
      type: string
    description: Custom GPT targeting properties.
  config:
    type: object
    description: User-provided configuration object to override default settings.
    properties:
      dfp:
        type: object
        properties:
          gpt:
            type: object
            properties:
              slots:
                type: object
                additionalProperties:
                  type: object
                  properties:
                    isDfpBidding:
                      type: boolean
                      default: true
                    collapseEmptyDiv:
                      type: boolean
                      default: false
                    targeting:
                      type: array
                      items:
                        type: array
                        items:
                          type: string
      hbw:
        type: object
        properties:
          initGpt:
            type: boolean
            default: true
          minRefreshRate:
            type: number
            description: Minimum refresh rate in milliseconds.
            default: 3600000
          slots:
            type: object
            additionalProperties:
              type: object
              properties:
                sizes:
                  type: array
                  items:
                    type: array
                    items:
                      type: number
  prebid:
    type: object
    additionalProperties:
      type: object
      properties:
        slots:
          type: object
          additionalProperties:
            type: object
            properties: {}
required: []