@bygd/opus-vast-hl

Introduction

@bygd/opus-vast-hl is a tool designed to facilitate the integration of video advertisements in web applications. It provides a straightforward mechanism to generate and manage Video Ad Serving Template (VAST) URLs based on user-defined parameters and configurations.

How It Works

The project operates by offering two main methods to acquire VAST URLs, byApi and byScript. These methods gather necessary information such as page URL, slot ID, and targeting criteria to build a valid VAST URL. The vastByMerged function intelligently selects between byApi and byScript based on the availability and readiness of certain prerequisites.

Key Features

• Dynamic VAST URL Generation: Facilitates the creation of VAST URLs with specific configurations tailored to different advertising slots.
• Customizable Targeting: Allows overriding default targeting parameters to suit different advertising needs.
• Flexible Slot Mapping: Supports different ad slots like "preroll" and "rewarded", ensuring accurate placement of video advertisements.
• Choice of API or Script Execution: Automatically decides the best method to execute, ensuring robust ad delivery.

Conclusion

@bygd/opus-vast-hl offers a practical solution for embedding video ads into web pages with customizable parameters. It is particularly useful for developers looking to integrate advertisements effortlessly while maintaining flexibility in terms of targeting and ad length.

Developer Guide for @bygd/opus-vast-hl

Overview

The @bygd/opus-vast-hl library is designed to facilitate the generation and management of VAST (Video Ad Serving Template) URLs for digital advertising. It provides an API that helps developers to dynamically configure and retrieve VAST URLs while catering to different advertising slots and scenarios. This library is particularly useful for those looking to integrate video ads into their web applications and manage targeting and slot configurations efficiently.

Installation

To get started with @bygd/opus-vast-hl, you can use either npm or yarn to install the package:

npm install @bygd/opus-vast-hl

or

yarn add @bygd/opus-vast-hl

Usage

The library provides three main functions to handle VAST URL generation:

• VastByApi: For generating VAST URLs using an API-focused approach.
• VastByScript: For generating VAST URLs using a script-based approach when relevant browser scripts are available.
• VastByMerged: A combined approach that selects between API and script-based methods based on the environment.

Example: Using the VastByApi Function

Here's a simple example of how to use the VastByApi function to obtain a VAST URL:

import { VastByApi } from '@bygd/opus-vast-hl';

async function fetchVastUrl() {
  const vastProvider = await VastByApi({
    pageUrl: "https://example.com",
    pageType: "gd",
    assetId: "your-asset-id",
    slotId: "preroll",
    targeting: { key: 'value' },
    max_ad_duration: 300,
    size: "640x480"
  });

  const vastResponse = await vastProvider.getVAST();
  console.log(vastResponse.value); // Outputs the VAST URL
}

fetchVastUrl();

Example: Using the VastByScript Function

If your environment supports idhb scripts, you may use the VastByScript function:

import { VastByScript } from '@bygd/opus-vast-hl';

async function fetchVastUrlViaScript() {
  const vastProvider = await VastByScript({
    slotId: "rewarded",
    pageUrl: "https://example.com",
    overrideTargeting: { customKey: 'customValue' }
  });

  const vastResponse = await vastProvider.getVAST();
  console.log(vastResponse.value); // Outputs the modified VAST URL
}

fetchVastUrlViaScript();

Example: Using the VastByMerged Function

Use VastByMerged to automatically choose the appropriate VAST generation method:

import { VastByMerged } from '@bygd/opus-vast-hl';

async function fetchVastUrlDynamically() {
  const vastProvider = await VastByMerged({
    api: true,
    hl: true,
    pageUrl: "https://example.com",
    slotId: "preroll"
  });

  const vastResponse = await vastProvider.getVAST();
  console.log(vastResponse.value); // Outputs the VAST URL or modified URL
}

fetchVastUrlDynamically();

Acknowledgement

While this library may integrate with certain external advertising systems or scripts, it is self-contained in terms of core functionality.

Input Schema

$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
  hlConfig:
    type: object
    description: Configuration object for HL
  pageUrl:
    type: string
    default: https://www.gry.pl/gra/bubble_shooter
    description: URL of the page
  pageType:
    type: string
    default: gd
    description: Type of the page
  assetId:
    type: string
    default: 27673bc45d2e4b27b7cd24e422f7c257
    description: Asset ID
  slotId:
    type: string
    default: preroll
    description: Slot identifier
  targeting:
    type: object
    description: Targeting parameters
  max_ad_duration:
    type: number
    description: Maximum ad duration in seconds
  size:
    type: string
    default: 640x480
    description: Size of the ad
  overrideTargeting:
    type: object
    description: Override targeting parameters
required: []