AdView

AdView is a modern, type-safe React library for displaying and managing advertisements in web applications. It provides flexible components for multiple ad formats with built-in tracking, error handling, and both client-side and server-side rendering support.

Features

• 🎯 Multiple Ad Formats: Support for banner, native, and proxy advertisements
• 🔄 Dual Rendering: Both client-side and server-side rendering capabilities
• 📊 Built-in Tracking: Automatic impression and click tracking
• 🛡️ Type Safety: Full TypeScript support with comprehensive type definitions
• 🎨 Customizable Styling: Flexible styling system for different ad formats
• 🚀 Performance Optimized: Lazy loading and efficient bundle splitting
• 🔧 Extensible: Plugin-based scraper system for data collection

Packages

This monorepo contains the following packages:

• @adview/core: Core utilities, types, and shared functionality
• @adview/react: React components and hooks for AdView

Table of Contents

• Installation
• Quick Start
• API Reference
• Ad Formats
• Configuration
• Tracking
• Server-Side Rendering
• Development
• Contributing
• License

Installation

Install the package using npm or yarn:

npm install @adview/react

yarn add @adview/react

Import Styles

AdView supports multiple import styles for different use cases:

Package-level imports (recommended)

// React components
import { AdViewUnit, AdViewProvider } from '@adview/react';

// Server components
import { AdViewUnitServer } from '@adview/react/server';

Direct utility imports

// Core utilities (tree-shakable)
import { adViewFetcher, getResolveConfig } from '@adview/core/utils';

// TypeScript types
import { AdViewData, AdViewConfig } from '@adview/core/typings';

Benefits:

• Tree-shaking: Import only what you need
• Type safety: Full TypeScript support
• Intellisense: Better IDE autocomplete
• Future-proof: Ready for framework extensions (@adview/vue, @adview/angular)

Quick Start

Basic Usage

import { AdViewUnit } from '@adview/react';

function MyComponent() {
  return (
    <AdViewUnit
      unitId="your-ad-unit-id"
      srcURL="https://your-ad-server.com/ads/{<id>}"
      format="banner"
    />
  );
}

With Provider (Recommended)

import { AdViewProvider, AdViewUnit } from '@adview/react';

function App() {
  return (
    <AdViewProvider srcURL="https://your-ad-server.com/ads/{<id>}">
      <AdViewUnit unitId="header-banner" format="banner" />
      <AdViewUnit unitId="sidebar-native" format="native" />
    </AdViewProvider>
  );
}

Custom Rendering

import { AdViewUnit } from '@adview/react';

function CustomAd() {
  return (
    <AdViewUnit unitId="custom-ad" format="native">
      {({ data, state, error, onDefault }) => {
        if (state.isLoading) return <div>Loading ad...</div>;
        if (state.isError) return <div>Failed to load ad</div>;
        if (!data) return onDefault?.() || null;
        
        return (
          <div className="custom-ad">
            <h3>{data.fields?.title}</h3>
            <p>{data.fields?.description}</p>
          </div>
        );
      }}
    </AdViewUnit>
  );
}

API Reference

AdViewUnit

Main component for displaying advertisements.

Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | unitId | string | ✓ | Unique identifier for the ad unit | | format | 'banner' \| 'native' \| 'proxy' | ✗ | Ad format type | | srcURL | string | ✗ | Ad server URL template | | onDefault | () => ReactNode \| ReactNode | ✗ | Fallback content when no ad is available | | children | function \| ReactElement | ✗ | Custom render function or component |

Load State

The component provides detailed loading states:

type AdLoadState = {
  isInitial: boolean;  // Initial state before loading
  isLoading: boolean;  // Currently fetching ad data
  isError: boolean;    // Error occurred during loading
  isComplete: boolean; // Loading completed (success or error)
};

AdViewProvider

Context provider for global configuration.

Provider Props

| Prop | Type | Description | |------|------|-------------| | srcURL | string | Default ad server URL template | | children | ReactNode | Child components |

Ad Formats

Banner Ads

Simple image-based advertisements:

<AdViewUnit unitId="banner-300x250" format="banner" />

Native Ads

Content-style ads with structured data:

<AdViewUnit unitId="native-article" format="native" />

Proxy Ads

Delegated rendering to external systems:

<AdViewUnit unitId="proxy-widget" format="proxy" />

Configuration

Environment Variables

# Default ad server URL
ADSERVER_AD_JSONP_REQUEST_URL=https://your-ad-server.com/ads/{<id>}

URL Template

The srcURL should contain {<id>} placeholder that will be replaced with the unitId:

https://ads.example.com/serve/{<id>}?format=json

Data Collection

The library automatically collects browser data for ad targeting:

• Screen dimensions
• Timestamp
• Cache-busting tokens

You can extend data collection by adding custom scrapers:

import { pageScrapers } from '@adview/core/utils';

// Add custom scraper
pageScrapers.push(() => ({
  timezone: Intl.DateTimeFormat().resolvedOptions().timeZone
}));

Tracking

Automatic Tracking

The library automatically handles:

• Impression tracking: When ads become visible
• Click tracking: When users interact with ads
• View tracking: Custom view events

Manual Tracking

import { AdViewUnitTracking } from '@adview/react';

<AdViewUnitTracking
  impressions={['https://track.example.com/imp?id=123']}
  clicks={['https://track.example.com/click?id=123']}
  views={['https://track.example.com/view?id=123']}
>
  <YourAdComponent />
</AdViewUnitTracking>

Server-Side Rendering

For SSR applications, use the server-specific components:

import { AdViewUnitServer } from '@adview/react/server';

// In your server component
function ServerPage() {
  return (
    <AdViewUnitServer
      unitId="ssr-banner"
      srcURL="https://ads.example.com/serve/{<id>}"
    />
  );
}

Development

Prerequisites

• Node.js ≥ 18
• npm or yarn

Setup

# Clone the repository
git clone https://github.com/geniusrabbit/adview.git
cd adview

# Install dependencies
npm install

# Build all packages
npm run build

# Start development mode
npm run dev

Scripts

npm run build     # Build all packages
npm run lint      # Run ESLint
npm run test      # Run tests
npm run version   # Version packages
npm run release   # Publish packages

Project Structure

adview/
├── packages/
│   ├── react/              # React components and hooks
│   │   ├── src/
│   │   │   ├── AdViewUnit/ # Core components
│   │   │   ├── types.ts    # TypeScript definitions
│   │   │   ├── index.ts    # Client exports
│   │   │   └── server.ts   # Server exports
│   │   └── package.json
│   └── (future packages: vue, angular, etc.)
├── utils/                  # Shared utilities (@adview/core)
├── typings/               # Global type definitions (@adview/core)
└── package.json          # Core package (@adview/core)

Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow TypeScript best practices
• Add tests for new features
• Update documentation for API changes
• Run linting before submitting PRs

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📖 Documentation: GitHub Wiki

Publishing to npm

For detailed instructions on publishing packages to npm, see PUBLISHING.md.

Quick commands:

# Check packages are ready for publishing
make publish-check

# Check current versions
make version-check

# Login to npm (first time only)
npm login

# Publish all packages
npm run publish

Creating New Framework Packages

To add support for new frameworks (Vue, Angular, etc.):

# Create new package structure
make create-package name=vue framework=Vue language=typescript

# Navigate and implement
cd packages/vue
# ... implement Vue components ...

# Build and test
npm run build
npm publish --dry-run

Publishing & CI/CD

Quick Publishing

The monorepo supports automated publishing with version management:

# Method 1: Quick publish with changeset
npx changeset add
npx changeset version
npm run publish

# Method 2: Manual version bump and publish
npm version patch  # or minor, major
npm publish

Automated Publishing with Tags

The repository includes GitHub Actions for automated publishing:

1. Push a version tag to trigger publishing:

   git tag v1.0.1
   git push origin v1.0.1

2. GitHub Actions automatically:

   • Builds all packages
   • Runs tests and linting
   • Publishes to npm registry
   • Creates GitHub release

CI/CD Workflows

Three GitHub Actions workflows are configured:

• ci.yml: Runs tests, lint, build on PRs and pushes
• publish.yml: Publishes packages when version tags are pushed
• release.yml: Manages changeset-based releases on main branch

See PUBLISHING.md for detailed publishing instructions.

Troubleshooting

Permission Errors

npm ERR! code E403
npm ERR! 403 Forbidden - PUT https://registry.npmjs.org/@adview%2freact

Solution: Ensure you have publishing permissions for the @adview scope.

Authentication Errors

npm ERR! code E401
npm ERR! 401 Unauthorized

Solution: Run npm login again.

Package Already Exists

npm ERR! code E409
npm ERR! Cannot publish over existing version

Solution: Increment version number in package.json.

Automated CI/CD Publishing

For automated publishing in CI/CD pipelines:

# Use npm token for authentication
echo "//registry.npmjs.org/:_authToken=\${NPM_TOKEN}" > .npmrc

# Build and publish
npm run build
npm run publish