Skip to main content

Component Reference

This document provides the API reference for all AdSense-related components in the board-web application.

File Structure​

app/third-parties/
├── google-ad-sense.jsx              # Script loader component
└── google-ad-sense/
    ├── ad-sense-constants.js        # Slot ID constants
    ├── ad-sense-unit.jsx            # Main ad component
    ├── ad-sense-unit.scss           # Styles
    └── ad-sense-placeholder.jsx     # Dev/QA placeholder

GoogleAdSenseScript​

Location: app/third-parties/google-ad-sense.jsx

Loads the AdSense library script in the document <head>. Only renders when VITE_ADSENSE_PUBLISHER_ID is set.

Usage​

// In root.jsx Layout component
import { GoogleAdSenseScript } from '@/third-parties/google-ad-sense'

export function Layout({ children }) {
  return (
    <html>
      <head>
        <GoogleTagManagerScript />
        <GoogleAdSenseScript />  {/* Add after GTM */}
        <Meta />
        <Links />
      </head>
      <body>{children}</body>
    </html>
  )
}

Behavior​

EnvironmentVITE_ADSENSE_PUBLISHER_IDResult
ProductionSetScript tag renders
DevelopmentNot setReturns null
QANot setReturns null

AdSenseUnit​

Location: app/third-parties/google-ad-sense/ad-sense-unit.jsx

The main component for displaying ads. Handles environment detection, initialization, and responsive sizing.

Props​

PropTypeDefaultDescription
slotstringrequiredThe AdSense slot ID (from AD_SENSE_UNITS)
formatstring'auto'Ad format: 'auto', 'fluid', 'rectangle', 'horizontal', 'vertical'
layoutstringundefinedLayout for in-article ads: 'in-article'
styleobject{}Additional inline styles
minHeightstring'250px'Minimum height to reserve (prevents CLS)
classNamestring''Additional CSS classes for wrapper
responsiveClassstringundefinedCSS class for responsive sizing

Usage Examples​

In-Article Fluid Ad​

Best for: Between content sections

import AdSenseUnit from '@/third-parties/google-ad-sense/ad-sense-unit'
import AD_SENSE_UNITS from '@/third-parties/google-ad-sense/ad-sense-constants'

<AdSenseUnit
  slot={AD_SENSE_UNITS.HOME_AFTER_HERO}
  format="fluid"
  layout="in-article"
  minHeight="100px"
/>

Responsive Horizontal Banner​

Best for: Above the fold, fixed positions

<AdSenseUnit
  slot={AD_SENSE_UNITS.HOME_HERO}
  responsiveClass="ad-sense-horizontal-banner"
/>

Rectangle Ad​

Best for: Sidebars, in-content

<AdSenseUnit
  slot={AD_SENSE_UNITS.SIDEBAR}
  format="rectangle"
  minHeight="250px"
/>

Component Logic Flow​

AdSensePlaceholder​

Location: app/third-parties/google-ad-sense/ad-sense-placeholder.jsx

Visual placeholder shown in development and QA environments.

Props​

PropTypeDefaultDescription
widthstring'100%'Placeholder width
heightstring'250px'Placeholder height
slotstring'Auto'Slot name to display
classNamestring''Additional CSS classes
responsiveClassstring''CSS class for responsive sizing

Appearance​

The placeholder displays:

  • "Google AdSense Placeholder" header
  • The slot ID/name
  • "Visible in Development/QA only" note
  • Dashed border styling

AD_SENSE_UNITS​

Location: app/third-parties/google-ad-sense/ad-sense-constants.js

Constants for ad slot IDs. Always use these constants instead of hardcoding slot IDs.

Current Slots​

const AD_SENSE_UNITS = {
  PLACEHOLDER          : 'placeholder',   // Forces placeholder display
  HOME_HERO            : '1133995872',    // Display ad - hero banner
  HOME_AFTER_HERO      : '3568603439',    // In-article ad - after hero
  HOME_LIST_GROUP_ITEM : '8803768184'     // In-feed ad - job listings
}

Adding New Slots​

  1. Create the ad unit in Google AdSense Dashboard
  2. Copy the data-ad-slot value
  3. Add to ad-sense-constants.js:
const AD_SENSE_UNITS = {
  // ... existing slots
  NEW_PLACEMENT: '1234567890'  // Description of where it's used
}

CSS Classes​

Location: app/third-parties/google-ad-sense/ad-sense-unit.scss

.ad-sense-wrapper​

Applied to all ad unit wrappers. Used for:

  • Hiding unfilled ads via :has() selector
  • Applying minHeight for CLS prevention

.ad-sense-horizontal-banner​

Responsive banner with standard IAB sizes. Breakpoints are designed to work inside Bootstrap columns (e.g., Col lg={7}):

BreakpointDimensionsAd TypeNotes
< 576px320 x 50Mobile BannerMobile devices
576-1399px468 x 60BannerTablet through large desktop
1400px+728 x 90LeaderboardOnly at xxl when column is wide enough

Why these breakpoints?

At Bootstrap's lg breakpoint (992-1199px), a Col lg={7} is only ~560px wide. A 728px leaderboard would overflow. We only show the leaderboard at xxl (1400px+) where the column is ~770px wide.

Adding Custom Responsive Classes​

// Example: Large rectangle for sidebars
.ad-sense-large-rectangle {
  width: 300px;
  height: 250px;
  margin: 0 auto;

  @media (min-width: 992px) {
    width: 336px;
    height: 280px;
  }
}

Environment Variables​

VITE_ADSENSE_PUBLISHER_ID​

EnvironmentValueEffect
Productionca-pub-XXXXXXXXReal ads load
QAnot setPlaceholders shown
Developmentnot setPlaceholders shown

Configuration Files​

The variable must be set in:

  1. .env (local development) - Leave empty
  2. Dockerfile - Build arg and runtime env
  3. deploy/deploy.yml - Kamal deployment secrets
  4. .github/workflows/ci.yml - CI build args

Type Definitions (JSDoc)​

For better IDE support, the components use JSDoc comments:

/**
 * @param {Object} props
 * @param {string} props.slot - The AdSense slot ID
 * @param {string} [props.format='auto'] - Ad format
 * @param {string} [props.layout] - Layout for in-article ads
 * @param {Object} [props.style={}] - Additional inline styles
 * @param {string} [props.minHeight='250px'] - Minimum height
 * @param {string} [props.className=''] - Additional CSS classes
 * @param {string} [props.responsiveClass] - CSS class for responsive sizing
 * @returns {JSX.Element}
 */