Agility CMS

Developer

Audience & Region Query Parameter System

This system allows you to store and access audience and region selections through URL query parameters throughout your Next.js application.

Note: The current query parameter approach is implemented for testing purposes. In production, a system would detect the user's region and audience at the edge (via middleware or edge functions) and then rewrite to the appropriate version of the site using query strings automatically, rather than requiring manual query parameter manipulation.

How it works

The audience and region selections are stored as query parameters in the URL:

  • ?audience=Enterprise&region=North%20America
  • These parameters persist across page navigation
  • Any component can read and update these values

Query Parameter Filtering: The middleware only processes whitelisted query parameters (audience, region, q). Tracking parameters (e.g., Google Analytics _gl, _ga, _gcl_au) are automatically filtered out to prevent crashes from extremely long query strings. Only query strings under 500 characters are processed.

Usage

1. In Client Components

Use the useAudienceRegionParams hook:

2. In Server Components

Use the server-side utility function:

2a. In Server Components (with ContentIDs)

When you need access to contentIDs for filtering or API calls:

Server-side:

4. Creating Links with Context

5. Working with ContentIDs

When you need to access the Agility CMS contentID for audiences or regions (useful for content filtering, API calls, etc.):

To get audiences/regions with contentIDs, use the enhanced listing methods:

Available Hooks and Utilities

Client-side Hook: useAudienceRegionParams

Server-side Utilities

  • getAudienceRegionFromPage() - Extract values from page searchParams
  • getAudienceRegionWithContentIDFromPage() - Extract values including contentIDs
  • shouldShowContentForAudienceRegion() - Check if content should show
  • createUrlWithAudienceRegion() - Generate URLs with context
  • getAudienceContentIDByName() - Get audience contentID by name
  • getRegionContentIDByName() - Get region contentID by name
  • getSelectedContentIDs() - Get both audience and region contentIDs
  • transformContentItemsWithContentID() - Transform ContentItems to include contentID

Components

AudienceRegionIndicator

Shows current selection with a clear button.

ConditionalContent

Wrapper component that conditionally renders children based on audience/region.

Preview Bar Integration

The preview bar in src/components/preview-bar.tsx manages the query parameters and provides the UI for selecting audience and region. It automatically:

  • Reads current selections from URL
  • Updates URL when selections change
  • Shows visual indication when context is active
  • Provides clear functionality

Benefits

  1. URL-based state: Selections persist across page reloads and navigation
  2. Shareable URLs: Users can share links with specific audience/region context
  3. Server and client compatibility: Works in both Server and Client Components
  4. No additional dependencies: Uses only Next.js built-in functionality
  5. Clean separation: Query parameter logic is abstracted into reusable hooks/utilities

Production Implementation

In a production environment, the system would work differently:

  • Edge Detection: User's region and audience would be detected at the edge (middleware or edge functions) based on:
    • IP geolocation for region detection
    • User profile data, cookies, or authentication context for audience detection
  • Automatic Rewriting: The edge layer would automatically rewrite requests to include the appropriate query parameters
  • Transparent to Users: Users wouldn't need to manually add query parameters; the system would handle it automatically
  • Testing: The current query parameter approach allows developers and content editors to easily test different audience/region combinations by manually adding parameters to URLs