v2.0 changes & updates

Overview

WooCommerce Intercom Integration v2.0.0 represents a complete modernization of the codebase while maintaining 100% backward compatibility. This document outlines changes, new features, and best practices for developers working with the plugin.

Version 2.0.0 – What Changed for Developers

Backward Compatibility

✅ All hooks and filters remain unchanged

All existing filters continue to work identically
All existing actions fire at the same points
All public methods maintain the same signatures
All settings structure unchanged
No code changes required for existing customizations

Technical Modernization

PHP 8.1+ Requirements

Breaking Change: PHP 8.1+ now required (was 7.3+)
Strict types (declare(strict_types=1)) throughout codebase
Comprehensive type hints on 120+ methods
Return type declarations everywhere
Better null safety with nullable types

Code Quality Improvements

WordPress Coding Standards compliance
PHPStan static analysis (level 5)
Comprehensive docblocks following WordPress standards
Better error handling with early returns
Strict comparison operators (===) throughout

New Developer Features

1. Intercom API v2.x Support (Experimental)

Opt-in to Intercom API v2.x behavior via filter:

add_filter( 'ewi_intercom_api_version', function( $version ) {
    return '2.9'; // opt-in to v2.x
});

What changes with v2.x:

Authentication: Bearer token instead of Basic auth
Endpoints: Automatic mapping (users → contacts, etc.)
Payloads: Automatic transformation for v2.x format

Payload transforms:

user_id → external_id (by default)
company_id → id for companies
Timestamps coerced to integers

Customize transforms:

<? 
// Opt-out of external_id mapping for specific contexts
add_filter( 'ewi_v2_use_external_id', function( $use, $context ) {
    if ( 'event' === $context ) {
        return false; // keep user_id for events
    }
    return $use;
}, 10, 2 );

// Adjust event payloads
add_filter( 'ewi_v2_event_payload', function( $event ) {
    $event['custom_field'] = 'value';
    return $event;
} );

// Adjust tag payloads
add_filter( 'ewi_v2_tag_payload', function( $tag ) {
    // Note: contacts[] array instead of users[]
    return $tag;
} );

// Adjust user/contact payloads
add_filter( 'ewi_v2_user_payload', function( $user ) {
    return $user;
} );

// Adjust company payloads
add_filter( 'ewi_v2_companies_payload', function( $companies ) {
    return $companies;
} );

⚠️ Experimental Notice: Intercom API v2.x support is experimental. Test thoroughly in staging before using in production. Default remains v1.4 for full backward compatibility.

2. Enhanced Error Handling

Automatic Retry Logic

Transient API failures (5xx) automatically retried
Exponential backoff with configurable max delay
Respects Retry-After header when provided
Configurable via constants in class-ewi-intercom-api.php

Better Error Messages

Normalized error extraction from API responses
More specific error messages in logs
Easier debugging and troubleshooting

3. Improved Logging

WooCommerce Logger Integration

All logs accessible via WooCommerce > Status > Logs
Multiple log levels: error, warning, info, debug
Better performance than file-based logging
Secure (no file permission issues)

Accessing Logs in Code:

// Access the main plugin instance
global $ektgn_woointercom;
$ewi = $ektgn_woointercom->get_eWI();

// Log at different levels
$ewi->elog( 'Debug message', 'debug' );
$ewi->elog( 'Info message', 'info' );
$ewi->elog( 'Warning message', 'warning' );
$ewi->elog( 'Error message', 'error' );

4. Better Testing Infrastructure

PHPUnit Setup

Comprehensive test infrastructure
WordPress shims for isolated testing
Mock utilities for API calls
Example tests for key functionality

Running Tests:

composer install
composer test

API Changes

Version-Aware Endpoint Mapping

Endpoints are automatically mapped based on API version:

v1.4 (default):

users → /users
visitors/convert → /visitors/convert
bulk/users → /bulk/users

v2.x (when opted-in):

users → /contacts
visitors/convert → /contacts/convert
bulk/users → /bulk/contacts

All mapping is automatic – your code doesn’t need to change.

Headers & Authentication

v1.4 (default):

Basic authentication
Headers: Authorization: Basic {base64(app_id:pat)}

v2.x (when opted-in):

Bearer token authentication
Headers: Authorization: Bearer {pat}
Additional: Intercom-Version: {version}

Security Improvements

Input Sanitization

All $_GET, $_POST, $_COOKIE inputs sanitized
Uses sanitize_text_field( wp_unslash( ... ) )
Validation before processing

Output Escaping

All admin notices use wp_kses_post() or esc_html()
URLs escaped with esc_url()
JavaScript values escaped with esc_js()

Nonce Verification

All admin actions protected with nonces
Bulk sync operations verified
AJAX requests validated

WooCommerce 10.x Compatibility

Method Updates

get_user_id() → get_customer_id() (better guest handling)
All WC_Order methods verified current
HPOS compatibility confirmed
All hooks verified working

No Breaking Changes

All existing hooks remain valid
All filters work identically
No deprecated functionality

Constants & Configuration

API Configuration

// Available constants in class-ewi-intercom-api.php
API_BASE_URL = 'https://api.intercom.io/'
DEFAULT_API_VERSION = '1.4'
DEFAULT_TIMEOUT = 45
MAX_RETRIES = 3
BACKOFF_CAP_SECONDS = 10

Background Processing

// Available in class-ewi-background-process.php
PROGRESS_DELAY_US = 250000

Hooks & Filters Reference

Existing Filters (All Still Work)

See this for for complete hook/filter documentation. All existing filters remain unchanged.

New Filters (v2.0.0)

API Version Control:

ewi_intercom_api_version – Set API version to use

v2.x Payload Filters (when v2.x enabled):

ewi_v2_use_external_id – Control user_id → external_id mapping
ewi_v2_event_payload – Modify event payloads
ewi_v2_tag_payload – Modify tag payloads
ewi_v2_user_payload – Modify user/contact payloads
ewi_v2_companies_payload – Modify company payloads

Migration Guide

From v1.x to v2.0.0

1. PHP Version Check

// Ensure PHP 8.1+
phpversion(); // Should return 8.1.0 or higher

2. Update Plugin

Standard WordPress plugin update
No settings migration needed
All configurations preserved

3. Verify Custom Code

All hooks/filters work identically
No code changes required
Test in staging first

4. Optional: Enable v2.x API

// Only if you want to test Intercom API v2.x
add_filter( 'ewi_intercom_api_version', function() {
    return '2.9';
} );

Testing Your Customizations

Recommended Checks:

Verify all custom filters still work
Test event creation with your metadata
Verify tag creation/modification
Test bulk sync if you use it
Check logs for any warnings

Debug Mode: Enable debug logging in settings to see detailed activity:

All API calls
Payloads sent/received
Error messages
Retry attempts

Code Examples

Custom Event Metadata

// Add custom metadata to order completed events
add_filter( 'ewi_order_completed_meta', function( $metadata, $order ) {
    $metadata['payment_method'] = array(
        'value' => $order->get_payment_method(),
        'label' => 'Payment Method'
    );
    return $metadata;
}, 10, 2 );

Custom Tag Modification

// Modify tags before sending to Intercom
add_filter( 'ewi_before_tagging_tags', function( $tags, $user_id, $order_id ) {
    // Add custom tag
    $tags[] = 'VIP Customer';

    // Remove specific tag
    $tags = array_filter( $tags, function( $tag ) {
        return $tag !== 'Regular Customer';
    } );

    return array_values( $tags ); // Re-index array
}, 10, 3 );

Disable Specific Features

// Disable cart tracking
add_filter( 'ewi_core_actions_cart_init', '__return_false' );

// Disable subscription events
add_filter( 'ewi_sub_actions_init', '__return_false' );

Troubleshooting

API Connection Issues

Use the “Test Connection” button in settings
Check logs at WooCommerce > Status > Logs
Verify PAT has correct permissions in Intercom

Events Not Appearing

Enable debug logging
Check logs for API errors
Verify customer exists in Intercom
Check rate limiting (429 errors)

Bulk Sync Issues

Check PHP memory limits
Verify background processing (WP Cron) works
Monitor progress in admin notices
Use cancel feature if stuck

Performance Considerations