Custom Events

Technical Reference

Use Technical Reference to work with PersonalizeWP programmatically.

trackEvent() Function

window.PersonalizeWP.tracking.trackEvent( eventName, eventArgs )

Parameters

eventName (string, required)

  • Event type identifier
  • Must match registered event type in PHP
  • Restricted to lowercase alphanumeric characters, dashes, and underscores
  • Processed through WordPress sanitize_key() function
  • Examples: click , video-play , form-submit

eventArgs (object, required)

  • Key-value pairs of event metadata
  • Keys follow same format restrictions as eventName (max 150 chars)
  • Values should follow WordPress Post Meta format conventions
  • Avoid deeply nested objects or binary data

Automatic Data

The following data is automatically added to all events:

  • Visitor UUID – Unique identifier for the visitor
  • Timestamp – When the event occurred
  • Current URL – Page where the event was triggered
  • Page context – Post ID and type (if available via window.pwpTrack )

Return Value

None. Errors are logged to console if tracking fails.

registereventtype() Function

$personalizewp->registereventtype( $event_type, $args )

Parameters

$event_type (string, required)

  • Event type identifier, must match JavaScript eventName
  • Same format restrictions as JavaScript

$args (array, optional)

  • label (string) – Display name in admin. Defaults to $event_type

Example

$personalizewp = personalizewp(); $personalizewp->registereventtype( 'newsletter-signup', array( 'label' => 'Newsletter Subscription', ) );

Display Filter Hook

addfilter( 'personalizewpactivitytableeventvalue{$eventtype}', callable $callback, int $priority = 10, int $acceptedargs = 4 )

Callback Parameters

  1. $link_title (string) – Default link title
  2. $link (string) – Default link URL
  3. $title (string) – Default title
  4. $item (array) – Complete activity item data, including:
  5. ID – Activity record ID
  6. url – Page URL where event occurred
  7. visitor_id – Associated visitor profile ID
  8. Plus any other activity fields

Accessing Metadata

Use the Activity model's get_metadata() method:

$value = PersonalizeWP\Model\Activity::get_metadata( $item['ID'], // Activity ID 'meta-key', // Metadata key true // Single value (true) or array (false) );

Return Value

Return a formatted HTML string for display in the "Event Value" column. HTML is allowed but will be escaped where appropriate by the admin interface.

Related articles