# Gapify Live Chat WordPress Plugin

A WordPress plugin that enables Gapify live chat widget on WordPress sites using a website token. The plugin provides comprehensive configuration options, user identification, and advanced display rules.

## Features

### Phase 1: Basic Configuration
- ✅ **Widget Integration**: Inject Gapify SDK and initialize the chat widget
- ✅ **Basic Settings**: Enable/disable, website token, position (left/right)
- ✅ **Appearance**: Dark mode (light/dark/auto), widget style (standard/flat)
- ✅ **Customization**: Launcher title, message bubble visibility, popout button
- ✅ **Language**: Browser language detection or manual locale setting
- ✅ **Base Domain**: Cookie domain configuration for multi-domain setups

### Phase 2: User Identification
- ✅ **Automatic Identification**: Identify logged-in WordPress users to the chat widget
- ✅ **Identifier Options**: Use WordPress user ID or email as unique identifier
- ✅ **User Data**: Include email, display name, avatar URL, and phone number
- ✅ **Privacy Controls**: Granular control over what user data to include

### Phase 3: Advanced Configuration & Display Rules
- ✅ **Auto-detection**: Automatic locale detection from WordPress settings
- ✅ **Smart Domains**: Auto-compute base cookie domain from site URL
- ✅ **Role-based Hiding**: Hide widget for specific user roles (including guests)
- ✅ **Content Filtering**: Exclude widget from specific post types
- ✅ **URL Patterns**: Hide widget on URLs matching wildcard patterns

## Installation

1. Download the plugin files
2. Upload to your WordPress `wp-content/plugins/` directory
3. Activate the plugin in WordPress admin
4. Configure the plugin in **Settings > Gapify Live Chat**

## Configuration

### Main Settings

| Setting | Description | Default |
|---------|-------------|---------|
| **Enabled** | Enable/disable the chat widget | `true` |
| **Website Token** | Your Gapify website token (required) | - |
| **Position** | Widget position on screen | `right` |
| **Locale** | Manual locale override (e.g., `en`, `fa_IR`) | - |
| **Use Browser Language** | Let browser detect language automatically | `true` |
| **Dark Mode** | Theme preference | `auto` |
| **Widget Style** | Visual style | `standard` |
| **Hide Message Bubble** | Hide the message notification bubble | `false` |
| **Launcher Title** | Custom text for the chat launcher | - |
| **Show Popout Button** | Display popout button in widget | `false` |
| **Show Unread Messages Dialog** | Show unread message notifications | `true` |
| **Base Cookie Domain** | Domain for cookies (e.g., `.example.com`) | - |

### User Identification

| Setting | Description | Default |
|---------|-------------|---------|
| **Identify Logged-in Users** | Automatically identify WordPress users | `false` |
| **Identifier Field** | Use `id` or `email` as unique identifier | `id` |
| **Include Email** | Send user email to chat | `true` |
| **Include Name** | Send user display name to chat | `true` |
| **Include Avatar** | Send user avatar URL to chat | `true` |
| **Include Phone** | Send user phone number to chat | `false` |

### Advanced Configuration

| Setting | Description | Default |
|---------|-------------|---------|
| **Auto-detect Locale** | Automatically detect locale from WordPress | `true` |
| **Auto-compute Base Domain** | Automatically compute base domain from site URL | `true` |

### Display Rules

| Setting | Description | Default |
|---------|-------------|---------|
| **Hide for User Roles** | User roles to hide widget from | `[]` |
| **Exclude Post Types** | Post types to exclude widget from | `[]` |
| **Exclude URL Patterns** | URL patterns to exclude (one per line, supports `*` wildcards) | - |

## Usage Examples

### Basic Setup
1. Enter your Gapify website token
2. Choose widget position (left or right)
3. Save settings

### User Identification
1. Enable "Identify Logged-in Users"
2. Choose identifier field (ID or Email)
3. Select which user data to include
4. Users will be automatically identified when they log in

### Display Rules
1. **Hide from Administrators**: Select "administrator" in "Hide for User Roles"
2. **Exclude from Shop**: Select "product" in "Exclude Post Types"
3. **Hide from Admin Areas**: Add patterns like:
   ```
   /wp-admin/*
   /admin/*
   /private/*
   ```

### URL Pattern Examples
- `/admin/*` - Hide on all admin pages
- `/wp-admin/*` - Hide on WordPress admin
- `https://example.com/private/*` - Hide on specific domain paths
- `/checkout` - Hide on exact page
- `*/payment/*` - Hide on any payment-related URLs

## Locale Support

The plugin supports automatic locale detection and manual overrides:

### Supported Locales
- English: `en`
- Persian/Farsi: `fa_IR`
- Portuguese (Brazil): `pt_BR`
- Chinese (Simplified): `zh_CN`
- Chinese (Traditional): `zh_TW`
- Spanish: `es`
- French: `fr`
- German: `de`
- Italian: `it`
- Dutch: `nl`
- Russian: `ru`
- Japanese: `ja`
- Korean: `ko`
- Arabic: `ar`

### Auto-detection
When "Auto-detect Locale" is enabled, the plugin will:
1. Use manual locale if specified
2. Fall back to WordPress site language
3. Apply locale normalization (e.g., `en_US` → `en`)

## Development

### Testing
```bash
# Run all tests
php tests/run.php

# Run specific phase tests
php tests/E2E/Phase1BasicTest.php
php tests/E2E/Phase2IdentificationTest.php
php tests/E2E/Phase3FeaturesTest.php
```

### File Structure
```
gapify-livechat.php          # Main plugin file
includes/
├── Plugin.php               # Main plugin class
├── Options.php              # Settings management
├── Sanitizer.php            # Input sanitization
├── AdminPage.php            # WordPress admin interface
├── FrontendInjector.php     # Widget injection logic
├── BaseUrlProvider.php      # Base URL resolution
├── CurrentUserProvider.php  # User identification
├── LocaleProvider.php       # Locale detection
└── DisplayRulesProvider.php # Display rules logic
assets/                      # WordPress.org plugin directory assets
├── icon-128x128.png         # Plugin icon (required)
├── banner-772x250.png       # Plugin banner (required)
└── screenshot-*.png         # Plugin screenshots
tests/                       # E2E test suite
languages/                   # Translation files
readme.txt                   # WordPress.org plugin description
```

### WordPress.org Assets

For WordPress.org submission, add your visual assets to the `assets/` directory:

**Required:**
- `icon-128x128.png` - Plugin icon (128x128px)
- `banner-772x250.png` - Plugin banner (772x250px)

**Recommended:**
- `icon-256x256.png` - High-res icon (256x256px)
- `banner-1544x500.png` - High-res banner (1544x500px)
- `screenshot-1.png`, `screenshot-2.png`, etc. - Plugin screenshots

See `assets/README.md` for detailed specifications and requirements.

## Changelog

### Version 0.1.0
- ✅ **Phase 1**: Basic widget configuration and integration
- ✅ **Phase 2**: User identification and data passing
- ✅ **Phase 3**: Advanced configuration and display rules

## Requirements

- PHP 7.4+
- WordPress 5.0+
- Gapify account and website token

## Support

For issues and feature requests, please contact the Gapify support team.

## License

GPLv2 or later