@vexia/vexia-ads-lib

v1.0.10

Published

17 hours ago

A comprehensive ads management library for integrating various ad types including betting odds, banners, images, and interactive HTML widgets

0High
0Medium
0Low

iquirino_ls

Vexia Ads Library

A comprehensive TypeScript library for managing and integrating various types of advertisements into web applications. Build your own ads server or ads management system with support for betting odds, banners, images, interactive HTML widgets, and more.

Overview

Vexia Ads Library is designed as a complete ads management solution that allows you to:

Serve different types of ad widgets (odds, banners, interactive content)
Manage ad configurations through Firebase
Display real-time data-driven advertisements
Build custom ad widgets with reusable components

Features

🎯 Multiple Ad Types - Odds widgets, banners, images, interactive HTML widgets, and more
🔥 Real-time Updates - Live data updates via Firebase Firestore
🎨 Customizable - Configure assets, styles, and behavior per widget type
📘 Full TypeScript Support - Complete type definitions included
🔄 Multiple Formats - Works in ESM, CommonJS, and browser (IIFE) environments
🚀 Zero Configuration - Firebase initialized internally, no setup required
📱 Responsive Design - Shadow DOM encapsulation with mobile-friendly styling
📦 Modular Architecture - Each ad type bundled separately for optimal loading
🛠️ Ads Management System - Build your own ads server with flexible widget system

Installation

For NPM Projects

npm install @vexia/vexia-ads-lib
# or
pnpm install @vexia/vexia-ads-lib

For Browser/WordPress Projects

Option 1: Via CDN (Recommended)

Include the specific ad type widget from a CDN:

<!-- Odds Widget from jsDelivr CDN (recommended) -->
<script src="https://cdn.jsdelivr.net/npm/@vexia/vexia-ads-lib@1/dist/odds/browser.js"></script>

<!-- Or from unpkg CDN -->
<script src="https://unpkg.com/@vexia/vexia-ads-lib@1/dist/odds/browser.js"></script>

Option 2: Self-hosted

Download the widget files from the releases page or from npm, then include them:

<!-- For odds widget -->
<script src="/path/to/dist/odds/browser.js"></script>

<!-- Future ad types will be available at:
     /path/to/dist/banners/browser.js
     /path/to/dist/interactive/browser.js
     etc. -->

Each ad type is bundled separately with its own dependencies, allowing you to load only what you need.

Usage

Browser/HTML (Simple)

Load the script and add the widget element:

<!DOCTYPE html>
<html>
<head>
  <title>Vexia Ads - Odds Widget</title>
  <script src="https://cdn.jsdelivr.net/npm/@vexia/vexia-ads-lib@1/dist/odds/browser.js"></script>
</head>
<body>
  <!-- Simple: Use the custom element -->
  <odds-widget widget-id="9QB0NfDEVqhGfd4Ccrny"></odds-widget>

  <!-- Or: Add programmatically -->
  <div id="container"></div>
  <script>
    VexiaOddsAds.addOddsWidget(
      document.getElementById('container'),
      '9QB0NfDEVqhGfd4Ccrny'
    );
  </script>
</body>
</html>

React/Next.js

import '@vexia/vexia-ads-lib/odds';

export default function OddsPage() {
  return (
    <div>
      <h1>Live Betting Odds</h1>
      <odds-widget widget-id="9QB0NfDEVqhGfd4Ccrny" />
    </div>
  );
}

NPM/TypeScript Projects

import { addOddsWidget } from '@vexia/vexia-ads-lib';

const container = document.getElementById('widget-container');
addOddsWidget(container, '9QB0NfDEVqhGfd4Ccrny');

Ads Management System

Vexia Ads Library is designed to be the foundation of a complete ads management system. The library provides:

Current Ad Types

Odds Widget (dist/odds/browser.js) - Real-time betting odds from multiple operators

Planned Ad Types

Banner Ads (dist/banners/browser.js) - Static and animated banner advertisements
Image Ads (dist/images/browser.js) - Responsive image-based advertisements
Interactive Widgets (dist/interactive/browser.js) - HTML-based interactive ad experiences
Video Ads - Video advertisement widgets
Native Ads - Content-style native advertisements

Architecture

Each ad type is:

Independently bundled - Load only what you need
Firebase-powered - Real-time configuration and data updates
Web Components - Custom elements with Shadow DOM encapsulation
Configurable - Flexible attributes for customization
Type-safe - Full TypeScript support

This modular approach allows you to build a complete ads server that can serve different ad types based on your needs, manage ad campaigns through Firebase, and integrate seamlessly into any web application.

Widget Attributes

| Attribute | Required | Description | |-----------|----------|-------------| | widget-id | Yes* | Pre-configured widget ID from Firestore | | event-id | Yes* | Specific event ID for real-time odds | | assets-url | No | Base URL for assets (default: /assets/) |

*Use either widget-id OR event-id, not both.

Note: An optional assets-url attribute is available to customize the base URL for assets (logos, images). By default, the widget uses the Vexia CDN.

<!-- Using widget ID -->
<odds-widget widget-id="9QB0NfDEVqhGfd4Ccrny"></odds-widget>

<!-- Using event ID -->
<odds-widget event-id="YOUR_EVENT_ID"></odds-widget>

API Reference

`addOddsWidget(target, widgetId)`

Programmatically add an odds widget to a container.

Parameters:

target (HTMLElement) - Container element
widgetId (string) - Widget ID from Firestore

Browser:

VexiaOddsAds.addOddsWidget(document.body, '9QB0NfDEVqhGfd4Ccrny');

NPM/TypeScript:

import { addOddsWidget } from '@vexia/vexia-ads-lib';
addOddsWidget(document.body, '9QB0NfDEVqhGfd4Ccrny');

Note: An optional third parameter assetsUrl is available for custom asset locations.

TypeScript Support

The library is written in TypeScript and includes full type definitions. When using in TypeScript projects, types are automatically available:

import { addOddsWidget } from '@vexia/vexia-ads-lib';

// Types are inferred automatically
const container = document.getElementById('widget-container');
if (container) {
  addOddsWidget(container, '9QB0NfDEVqhGfd4Ccrny');
}

How It Works

Zero Configuration: Firebase is initialized internally, no setup required
Real-time Updates: Live odds updates via Firestore subscriptions
Best Odds Highlighting: Automatically compares and highlights the best odds
Shadow DOM: Encapsulated styles, no CSS conflicts

Examples

Check out the examples/ directory for complete working examples:

examples/express-example/ - Express.js server with HTML/JavaScript implementation
examples/nextjs-example/ - Next.js/React implementation
examples/browser-example/ - Vanilla HTML/JavaScript implementation

Each example includes:

Full source code
Setup instructions
README with detailed explanations

Running the Express Example

cd examples/express-example
npm install
npm start
# Open http://localhost:3000

Development

Build

Build all formats:

npm run build
# or
pnpm run build

This creates:

dist/index.js - ES module for NPM
dist/index.cjs - CommonJS module
dist/browser.js - Bundled browser version (IIFE) with Firebase included
dist/*.d.ts - TypeScript type definitions

Individual build commands:

npm run build:esm      # ES modules only
npm run build:cjs      # CommonJS only
npm run build:browser  # Browser bundle only
npm run dev:browser    # Watch mode for browser bundle

Project Structure

├── src/
│   ├── index.ts         # Main entry point, exports
│   ├── odds/
│   │   └── index.ts     # Odds widget implementation
│   ├── banners/         # (Planned) Banner ads implementation
│   ├── interactive/     # (Planned) Interactive widgets
│   └── types.ts         # TypeScript type definitions
├── dist/                # Built files (generated)
│   ├── index.js         # ES module
│   ├── index.cjs        # CommonJS module
│   ├── odds/
│   │   └── browser.js   # Odds widget bundled for browser (IIFE)
│   ├── banners/         # (Future) Banner ads bundle
│   ├── interactive/     # (Future) Interactive widgets bundle
│   └── *.d.ts           # TypeScript definitions
├── examples/            # Usage examples
│   ├── express-example/     # Express.js server example
│   ├── nextjs-example/      # Next.js/React example
│   └── browser-example/     # Vanilla JS/HTML example
├── package.json
└── tsconfig.json

Note: Each ad type is bundled separately in its own subdirectory under dist/, allowing for modular loading and optimal bundle sizes.

Dependencies

Runtime Dependencies:

firebase - Firebase SDK for Firestore integration

Dev Dependencies:

typescript - TypeScript compiler
esbuild - Fast bundler for browser build

Publishing

The library is configured for publishing to npm with multiple formats and modular ad type exports:

{
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    "./odds": "./dist/odds/browser.js"
  }
}

As new ad types are added, they will be exported similarly:

"./banners": "./dist/banners/browser.js",
"./interactive": "./dist/interactive/browser.js"

License

ISC