Geo Banner 2 Widget

Migration Notice: We are transitioning from <bw-widget> to <nw-blocks> tags. While both are currently supported for backward compatibility, <nw-blocks> is now the recommended tag for all new implementations. Existing <bw-widget> implementations will continue to function.

Overview

Geo Banner 2 is an enhanced version of the geo-targeting banner widget with improved TypeScript implementation and optimized rendering. It provides the same geo-aware promotional banner functionality with refined performance characteristics and better type safety.

Key Features:

  • Enhanced Type Safety: Full TypeScript implementation for better reliability
  • Geo-Targeting: Automatic region-specific banner display
  • Performance Optimized: Advanced image loading with fetchpriority and lazy loading
  • Click Tracking: Built-in analytics with tracking parameters
  • SEO Control: Configurable link attributes (rel, target)
  • Responsive Design: Adapts to all screen sizes
  • Cache Optimization: Improved caching strategy for faster delivery

Basic Usage

Expand me...

With Priority Loading

Expand me...

Regional Campaign

Expand me...

Lazy Loading (Below Fold)

Expand me...

Attributes Reference

Attribute Type Required Default Description
id string Yes - Must be “geobanner2”
bannerID string Yes - Unique banner identifier from CMS
language string No “en” ISO 639-1 language code for banner content
country string No “ZZ” ISO 3166-1 country code for geo-targeting
trackinglinktarget string No "" Tracking parameter for analytics
target string No “_blank” Link target attribute (how link opens)
rel string No “nofollow” Link rel attribute for SEO control
loading string No “lazy” Image loading strategy (“lazy” | “eager”)
fetchpriority string No “medium” Image fetch priority (“high” | “low” | “medium”)

Widget Features

Enhanced Type Safety

Geo Banner 2 uses full TypeScript implementation:

  • Type-Safe Props: All attributes strongly typed
  • Runtime Validation: Better error catching
  • IDE Support: Enhanced autocomplete and hints
  • Compile-Time Checks: Catch errors before deployment

Image Loading Optimization

Fetchpriority Strategy:

Value Use Case Example
high Critical above-the-fold banners Hero sections, main promotions
medium Important content (default) Mid-page banners
low Below-the-fold content Footer, sidebar bottom

Loading Strategy:

Value Behavior Best For
eager Load immediately Above-the-fold banners
lazy Load when near viewport Below-the-fold content

Automatic Optimization:

  • High priority automatically uses eager loading
  • Lazy loading adds async decoding for performance
  • Browser-native implementation for best results

Geo-Targeting Capabilities

Country-Based:

  • Target specific countries with ISO codes
  • Use country="ZZ" for global fallback
  • Automatic regional content selection

Language-Based:

  • Display localized banner variants
  • Support for all major languages
  • Automatic translation integration

Click Tracking

URL Structure:

/go/{cloaked-link}/{tracking-target}?wid={widget-id}

Tracking Benefits:

  • Widget-level attribution
  • Campaign performance metrics
  • Position-based analytics
  • Conversion tracking

Common Use Cases

Hero Banner (Critical Load)

<nw-blocks 
  id="geobanner2" 
  bannerID="hero-welcome-2025" 
  language="en" 
  country="UK" 
  fetchpriority="high" 
  loading="eager"
  trackinglinktarget="hero-main"
  rel="nofollow" 
  target="_blank">
</nw-blocks>

<nw-blocks 
  id="geobanner2" 
  bannerID="sidebar-bonus-offer" 
  language="en" 
  country="US" 
  loading="lazy"
  trackinglinktarget="sidebar-right"
  rel="nofollow">
</nw-blocks>

Multi-Language Campaign

<!-- English UK -->
<nw-blocks 
  id="geobanner2" 
  bannerID="christmas-promo-en" 
  language="en" 
  country="UK" 
  trackinglinktarget="xmas-campaign">
</nw-blocks>

<!-- German -->
<nw-blocks 
  id="geobanner2" 
  bannerID="weihnachten-promo-de" 
  language="de" 
  country="DE" 
  trackinglinktarget="xmas-campaign">
</nw-blocks>

<!-- French -->
<nw-blocks 
  id="geobanner2" 
  bannerID="noel-promo-fr" 
  language="fr" 
  country="FR" 
  trackinglinktarget="xmas-campaign">
</nw-blocks>

Mobile-Optimized Banner

<nw-blocks 
  id="geobanner2" 
  bannerID="mobile-app-download" 
  language="en" 
  country="CA" 
  loading="lazy"
  trackinglinktarget="mobile-banner"
  target="_blank">
</nw-blocks>

<nw-blocks 
  id="geobanner2" 
  bannerID="footer-newsletter" 
  language="es" 
  country="ES" 
  loading="lazy" 
  fetchpriority="low"
  trackinglinktarget="footer-cta">
</nw-blocks>

<nw-blocks 
  id="geobanner2" 
  bannerID="partner-spotlight-2025" 
  language="en" 
  country="AU" 
  rel="sponsored nofollow"
  trackinglinktarget="sponsored-banner">
</nw-blocks>

Best Practices

Performance Optimization

  • Hero Banners: Always use fetchpriority="high" and loading="eager"
  • Above Fold: Prioritize immediately visible banners
  • Below Fold: Use loading="lazy" and fetchpriority="low"
  • Image Format: Use modern formats (WebP, AVIF) in CMS
  • Image Size: Optimize and compress banner images
  • Responsive: Serve appropriate sizes for different screens

Geo-Targeting Strategy

  • Create country-specific variants for major markets
  • Use language parameter for proper localization
  • Maintain global fallback (country="ZZ")
  • Test banners across different regions
  • Consider time zones for time-sensitive campaigns

SEO and Compliance

  • Use rel="nofollow" for affiliate banners (default)
  • Use rel="sponsored" for paid promotional content
  • Set target="_blank" for external links (default)
  • Ensure banner images have descriptive alt text
  • Use clear banner IDs for content identification

Tracking Implementation

  • Use descriptive tracking targets for clarity
  • Maintain consistent naming conventions
  • Track by position (hero, sidebar, footer)
  • Include campaign identifiers
  • Monitor click-through rates by banner

Cache Optimization

  • Widget includes cache key for debugging
  • Data cached per banner/country/language combination
  • Automatic cache invalidation on updates
  • Fast delivery through KV storage

Advanced Configuration

Priority Loading Matrix

Position Fetchpriority Loading Use Case
Hero Section high eager Main promotional banner
Top Content high eager Important above-fold
Mid-Page medium lazy In-content promotions
Sidebar medium lazy Secondary content
Footer low lazy Lowest priority banners 
<!-- Affiliate banner (default) -->
<nw-blocks id="geobanner2" bannerID="..." rel="nofollow"></nw-blocks>

<!-- Sponsored content -->
<nw-blocks id="geobanner2" bannerID="..." rel="sponsored"></nw-blocks>

<!-- Sponsored + nofollow combination -->
<nw-blocks id="geobanner2" bannerID="..." rel="sponsored nofollow"></nw-blocks>

<!-- User-generated content -->
<nw-blocks id="geobanner2" bannerID="..." rel="ugc"></nw-blocks>

<!-- Trusted partner -->
<nw-blocks id="geobanner2" bannerID="..." rel="follow"></nw-blocks>

Tracking Strategies

By Page Type:

<nw-blocks id="geobanner2" bannerID="..." trackinglinktarget="homepage"></nw-blocks>
<nw-blocks id="geobanner2" bannerID="..." trackinglinktarget="review-page"></nw-blocks>
<nw-blocks id="geobanner2" bannerID="..." trackinglinktarget="comparison"></nw-blocks>

By Position:

<nw-blocks id="geobanner2" bannerID="..." trackinglinktarget="hero-section"></nw-blocks>
<nw-blocks id="geobanner2" bannerID="..." trackinglinktarget="sidebar-top"></nw-blocks>
<nw-blocks id="geobanner2" bannerID="..." trackinglinktarget="footer-banner"></nw-blocks>

By Campaign:

<nw-blocks id="geobanner2" bannerID="..." trackinglinktarget="summer-2025"></nw-blocks>
<nw-blocks id="geobanner2" bannerID="..." trackinglinktarget="black-friday"></nw-blocks>
<nw-blocks id="geobanner2" bannerID="..." trackinglinktarget="welcome-bonus"></nw-blocks>

Differences from Geo Banner 1

Feature Geo Banner 1 Geo Banner 2
Implementation JavaScript TypeScript (FC)
Type Safety Basic Full TypeScript
Component Type Regular function Functional Component (FC)
Props Typing Partial Complete interface
Cache Key Basic display Conditional display
Error Handling Standard Enhanced with types
Performance Optimized Further optimized
Code Maintainability Good Excellent

When to use Geo Banner 2:

  • New implementations
  • TypeScript projects
  • Need better type safety
  • Enhanced IDE support required
  • Modern React best practices

When to use Geo Banner 1:

  • Existing implementations
  • JavaScript-only projects
  • Quick migration not needed
  • Legacy compatibility required

Data Requirements

Sanity CMS Structure

Banner configuration in Sanity CMS:

{
  bannerID: "showcase-test-banners-20250909",
  brand: {
    name: "Casino Brand",
    cloakedLink: "brand-casino"
  },
  image: {
    url: "https://cdn.../banner-image.webp",
    alt: "Promotional Banner"
  },
  targetCountries: ["UK", "US", "DE", "FR"],
  targetLanguages: ["en", "de", "fr"],
  startDate: "2025-09-09",
  endDate: "2025-12-31",
  isActive: true,
  clickTrackingEnabled: true
}

Required Fields:

  • bannerID: Unique identifier
  • brand.cloakedLink: Brand link
  • image.url: Banner image URL
  • image.alt: Accessibility text

Optional Fields:

  • targetCountries: Geo-targeting
  • targetLanguages: Language variants
  • startDate/endDate: Campaign scheduling
  • isActive: Activation status

KV Storage

Enhanced caching strategy:

  • Key: GEO_BANNER_2:{bannerID}:{country}:{language}
  • TTL: 1 hour
  • Cache Key: Included for debugging
  • Invalidation: Automatic on CMS update

Error Handling

Missing Banner

If banner ID doesn’t exist:

  • No banner rendered
  • Check banner ID in CMS
  • Verify spelling and format
  • Ensure banner is active

Type Errors

If invalid attributes provided:

  • TypeScript catches at compile time
  • Runtime validation for dynamic values
  • Console warnings for development
  • Graceful degradation in production

Geo-Targeting Issues

If banner unavailable for region:

  • Falls back to global banner if configured
  • Check targeting rules in CMS
  • Verify country/language codes
  • Review geo-targeting configuration

Backward Compatibility

All examples above use the new <nw-blocks> tag. For backward compatibility, you can still use <bw-widget>:

<!-- Old syntax (still supported) -->
<bw-widget 
  id="geobanner2" 
  bannerID="showcase-test-banners-20250909" 
  language="en" 
  country="ZZ" 
  rel="nofollow" 
  target="_blank" 
  trackinglinktarget="homepage">
</bw-widget>

<!-- New syntax (recommended) -->
<nw-blocks 
  id="geobanner2" 
  bannerID="showcase-test-banners-20250909" 
  language="en" 
  country="ZZ" 
  rel="nofollow" 
  target="_blank" 
  trackinglinktarget="homepage">
</nw-blocks>

Both tags work identically, but <nw-blocks> is recommended for all new implementations.