Tour Master Facebook Conversions API

This plugin integrates Tour Master with the Official Facebook Pixel plugin to send Server-Side Events (Conversions API) reliably. It captures standard booking and engagement actions and processes them asynchronously via WordPress Cron to ensure high performance and reliability.

Features

Event Tracking

• Purchase Tracking: Fires a Purchase event when a booking payment status is changed to online-paid, approved, or deposit-paid in the database.
• Lead Tracking: Fires a Lead event when a customer submits an enquiry form.
• CompleteRegistration: Fires a CompleteRegistration event when a new user registers an account.
• InitiateCheckout: Fires an InitiateCheckout event when a customer lands on the payment/checkout page, computing price and quantity directly from the booking cookie.

Queue & Reliability

• Asynchronous Processing: Prevents checkout slowdowns by storing events in a database queue and dispatching them in the background via WordPress Cron (every 5 hours).
• Smart Retries: Failed events are automatically retried up to 5 times using an incremental back-off strategy (1 h → 2 h → 3 h → 4 h → 5 h). After 5 failed attempts, the event is permanently marked as failed and not retried again.
• Event Statuses: Every event moves through a clear lifecycle — new → sending → success or failed.

Admin Dashboard

• Facebook Events Page: A dedicated Facebook Events submenu under the TourMaster admin menu gives you full visibility into the event queue.
• Statistics Cards: At-a-glance counters for Total, Pending, Sent, and Failed events, plus the next scheduled cron run time.
• Status Filters: Quickly filter the table by All, New, Sending, Success, or Failed.
• Sortable Columns: Click any column header (ID, Event, Status, Created, Updated) to sort ascending or descending — the current sort direction is indicated by ▲ / ▼.
• Payload Inspector: Expand any row to view the full JSON payload that was (or will be) sent to Facebook's Conversions API.
• Manual Fire: For any event with status new or failed, use the Send button to dispatch it to Facebook immediately, without waiting for the next cron run.
• Single Delete: Remove any event permanently from the queue with the trash icon.
• Multi-Select & Bulk Delete: Use the checkboxes to select one or more events (or use the header/footer select-all checkbox) and apply the Delete bulk action to remove them all at once.
• Dependency Notices: If TourMaster or the Official Facebook Pixel plugin is not active, a clear admin notice is shown with direct installation links.

Requirements

To use this plugin, you must have the following installed and activated:

• WordPress 5.0+
• Tour Master (Booking System)
• Official Facebook Pixel (by Facebook)

Installation

1. Download or clone this repository into your WordPress wp-content/plugins/ directory.
2. The folder name should be facebook-tourmaster-conversions-api.
3. Go to your WordPress Admin Dashboard → Plugins.
4. Find Tour Master Facebook Conversions API in the list and click Activate. Note: Upon activation, the plugin automatically creates the necessary database table (wp_tourmaster_fb_events) and schedules the cron job.

Configuration

No manual configuration is required in this plugin!
Just ensure your Official Facebook Pixel plugin is fully set up, connected to your Meta Business Manager, and has a valid Access Token configured for Server-Side tracking. This plugin uses the Facebook Pixel SDK built into the official plugin to route the events.

How It Works

1. Event Capture: When a customer performs an action (e.g., submits an enquiry or completes a payment), the plugin intercepts the data using Tour Master's native hooks:

   • goodlayers_set_payment_complete / tourmaster_facebook_plugin_order_paid → Purchase
   • wp_ajax_tourmaster_send_enquiry_form → Lead
   • tourmaster_user_register → CompleteRegistration
   • include_goodlayers_payment_script → InitiateCheckout

2. Database Queue: Instead of pausing the user's page load to talk to Facebook's servers, the event payload is serialized and inserted into the custom table wp_tourmaster_fb_events with a status of new.

3. Cron Processing: A WordPress Cron job runs every 5 hours. It fetches batches of up to 50 new and failed (due for retry) events and dispatches them to the Facebook Conversions API via the Official Facebook Pixel SDK.

4. Resiliency: If Facebook's API rejects an event, the attempts counter is incremented and a next_attempt timestamp is calculated using an increasing delay. After 5 failures, the event is saved as permanently failed.

5. Manual Dispatch: At any time, an administrator can visit TourMaster → Facebook Events and click Send on any pending or failed event to fire it immediately without waiting for the next cron cycle.

Admin Panel Walkthrough

Navigate to WP Admin → TourMaster → Facebook Events.

Testing

To test the integration:

1. Ensure your Facebook Pixel extension is active in your browser.
2. Trigger an event on your site (e.g., load the checkout page to trigger InitiateCheckout, or submit an enquiry for Lead).
3. Check the queue: go to TourMaster → Facebook Events — the event should appear with status new.
4. Click Send on the event row to dispatch it immediately.
5. Check your Facebook Events Manager under the Test Events tab to confirm the server-side payload was received.
6. Alternatively, use a tool like WP Crontrol to manually trigger the tourmaster_fb_send_events_cron hook to process the entire queue.

Security

If you discover a security issue with this integration, please report it privately rather than opening a public issue.

Support This Project

If this plugin saved you time, consider supporting its development:

Every bit helps keep this integration maintained and up to date with TourMaster and Facebook Conversions API changes.

License

This plugin is open-sourced software licensed under the MIT license.