Headless WordPress with PersonalizeWP

PersonalizeWP v3.1 enables headless WordPress implementations through secure API authentication, allowing you to use PersonalizeWP's personalisation capabilities when your frontend is built with modern frameworks like React, Vue, Next.js, or other JAMstack technologies whilst your WordPress installation serves as a headless CMS.

Overview

Headless WordPress separates your frontend presentation layer from your WordPress backend, enabling you to build modern, fast frontends whilst leveraging WordPress as a content management system. PersonalizeWP's headless support allows you to maintain full personalisation functionality in this architecture through secure REST API access.

The headless implementation works by generating API keys that authenticate requests from your frontend application to PersonalizeWP's REST API endpoints. Your frontend application can then fetch visitor profiles, check personalisation rules, and display targeted content based on PersonalizeWP's visitor data.

Prerequisites

Before implementing headless WordPress with PersonalizeWP:

  • PersonalizeWP Pro must be installed and activated on your WordPress backend
  • Your WordPress installation must be accessible via HTTPS
  • Your frontend application must be hosted on a domain with HTTPS support
  • Basic understanding of REST API integration in your chosen frontend framework
  • Familiarity with authentication headers and API request handling

Setting Up Authentication for Headless

Generate API Key

  1. Access your WordPress dashboard on the backend installation
  2. Navigate to PersonalizeWP settings
  3. Click the "Authentication" tab
  4. Click "Add New Key"
  5. Enter your frontend application's full URL (e.g., https://app.mysite.com)
  6. Generate and securely store the API key (displayed only once)

[Screenshot: API key generation for headless domain]

Configure CORS Settings

PersonalizeWP automatically configures CORS headers for domains with valid API keys. Once your API key is generated:

  • Your frontend domain is automatically added to allowed origins
  • Necessary CORS headers are set for PersonalizeWP API endpoints
  • Cross-origin requests from your authenticated domain are permitted

Frontend Implementation

Basic API Integration

Configure your frontend application to include the API key in all PersonalizeWP requests:

Request Headers Required:

  • Content-Type: application/json
  • X-PWP-Site-Token: [your-api-key]
  • X-Requested-With: XMLHttpRequest

Available API Endpoints

Your headless implementation can access all PersonalizeWP REST API endpoints:

Visitor Activities Endpoint:

  • URL: /wp-json/personalizewp/v1/visitor-activities
  • Method: POST
  • Purpose: Retrieve visitor interaction history

Profile Data Endpoints:

  • Access visitor profile information
  • Retrieve custom profile fields
  • Update visitor data from frontend interactions

Personalisation Rule Evaluation:

  • Check if content should be displayed to specific visitors
  • Evaluate complex personalisation rules
  • Handle segment and lead score targeting

Authentication Flow

  1. Frontend Request: Your application makes API requests to PersonalizeWP endpoints
  2. Token Validation: PersonalizeWP validates the API key against the request origin
  3. CORS Verification: Cross-origin headers are checked and allowed
  4. Data Response: PersonalizeWP returns requested data or personalisation decisions

Advanced Configuration Options

Multiple Frontend Domains

For applications spanning multiple domains:

  • Generate separate API keys for each frontend domain
  • Configure each domain independently in Authentication settings
  • Manage keys separately for different environments (staging, production)

Environment-Specific Setup

Development Environment:

  • Create API key for development/staging URLs
  • Use development WordPress installation as backend
  • Configure local development domains in Authentication settings

Production Environment:

  • Generate production API key for live frontend domain
  • Ensure production WordPress backend is properly secured
  • Monitor API usage and performance in production

Caching Considerations

When implementing headless PersonalizeWP:

  • Consider caching strategies for personalisation data
  • Implement client-side caching for visitor profiles
  • Balance personalisation accuracy with performance requirements

Security Configuration

Domain Restrictions

PersonalizeWP enforces strict domain matching to ensure API keys only work from their associated domains. Subdomain variations require separate keys, and protocol mismatches between http and https are automatically rejected. This prevents unauthorised access whilst maintaining flexibility for legitimate multi-domain implementations.

Token Security

Store API keys securely in environment variables and never expose them in client-side code where they could be accessed by users. Implement proper key rotation procedures for enhanced security and monitor for unauthorised API usage patterns that might indicate compromised keys.

Request Validation

All headless requests undergo comprehensive validation including origin domain verification, API key authenticity checking, request header validation, and rate limiting protection. This multi-layered approach ensures that only legitimate requests from authorised domains can access your personalisation data.

Troubleshooting

Authentication Failures

If API requests are being rejected, start by verifying the API key is correctly included in request headers and that requests originate from the exact domain specified during key creation. Ensure proper HTTPS protocol is used for both frontend and backend, and confirm the API key hasn't been revoked or expired in the Authentication settings.

CORS Issues

Cross-origin errors typically occur when the frontend domain doesn't match exactly with the API key domain. Check for www vs non-www domain mismatches and ensure requests include all required headers. Test API endpoints directly to isolate CORS issues from other potential problems.

Data Not Loading

When personalisation data isn't accessible, confirm PersonalizeWP Pro is active on the WordPress backend and verify the visitor has valid UID and profile data. Check that API endpoint URLs are correct and accessible, then test with simple API requests before implementing complex personalisation logic.

Performance Issues

Slow headless implementations often benefit from client-side caching for personalisation data and reduced API request frequency where possible. Consider batching multiple personalisation checks into single requests and monitor WordPress backend performance under API load to identify bottlenecks.

Development Environment Problems

Development workflow issues commonly arise from improperly configured domains or SSL certificates. Ensure development domains have valid API keys and that local SSL certificates are properly configured. Verify backend WordPress installation accessibility from your development environment and test basic API connectivity before implementing complex frontend features.

Headless WordPress with PersonalizeWP enables modern frontend architectures whilst maintaining sophisticated personalisation capabilities, providing the flexibility to build cutting-edge user experiences powered by WordPress content management and PersonalizeWP's visitor intelligence.

Still need help? Contact Us Contact Us