fluentcrm-event-tracking

FluentCRM: event tracking

Use this skill when a plugin wants to record product usage, LMS actions, purchase milestones, profile events, or any other contact activity into FluentCRM's event timeline and Pro automation conditions.

Guard the feature

Event tracking is core FluentCRM code, but it is disabled by default behind the experimental setting:

use FluentCrm\App\Services\Helper;

if (!function_exists('FluentCrmApi') || !Helper::isExperimentalEnabled('event_tracking')) {
    return;
}

FluentCrmApi('event_tracker')->track() returns WP_Error('not_enabled', ...) when the flag is off. Always handle WP_Error.

Track an event

The API key is event_tracker:

$event = FluentCrmApi('event_tracker')->track([
    'subscriber_id' => (int) $contactId,       // preferred when known
    'provider'      => 'my-plugin',
    'event_key'     => 'course_completed',
    'title'         => 'Course completed',
    'value'         => (string) $courseId,
], true);

if (is_wp_error($event)) {
    return;
}

Subscriber resolution order in Tracker::track():

• subscriber object, when supplied
• subscriber_id
• email
• user_id converted to the WP user's email
• current contact cookie / current user through fluentcrm_get_current_contact()

Required fields are event_key and title. Both are truncated to 192 characters and sanitized. provider defaults to custom; value is sanitized as textarea text.

Repeatable vs append-only

Second argument controls storage behavior:

FluentCrmApi('event_tracker')->track($data, true);  // repeatable/default
FluentCrmApi('event_tracker')->track($data, false); // append a new row every time

With $repeatable = true, FluentCRM looks up an existing row by (subscriber_id, event_key, title), updates value, increments counter, saves, and fires fluent_crm/event_tracked.

With $repeatable = false, it creates a new fc_event_tracking row every time and fires the same action.

There is no unique DB key for the repeatable lookup in 3.1.13; the counter is application-level, not an atomic financial counter. Use it for automation/activity state, not exact billing/accounting.