Custom Events

Trigger events when needed for more granular analytics

Beyond automatic page view tracking, PluginPulse allows you to track specific feature usage in your plugin. This helps you understand which features are most popular and how users interact with your plugin.

Adding Custom Event Tracking

The PluginPulse script adds a global pluginpulse() function that you can call to track custom events:

pluginpulse('YOUR_PLUGIN_ID', {
  event_type: 'feature',
  event_name: 'Export PDF',
  payload: {
    // Optional custom data
    action: 'click',
    component: 'export-button',
    success: true
  }
});

Parameters

Parameter	Required	Description	Example
plugin_id	Yes	Your PluginPulse plugin ID	"1706526741286x876166435619471400"
event_type	No	Type of event (default: "page_view")	"feature"
event_name	No	Name of the event/feature (default: "Page View")	"Export PDF"
payload	No	Custom JSON data for additional context	{format: "pdf", pages: 5}

Event Types

PluginPulse supports two event types:

• page_view: Used for tracking page/screen views

• feature: Used for tracking feature usage and interactions

• error: Used for tracking errors

Best Practices

When to Track Events

PluginPulse is flexible enough that you can track any event you feel important enough to monitor. So key events could include:

1. Feature Activation: When a user activates a feature

   pluginpulse('YOUR_PLUGIN_ID', {
     event_name: 'Export Started',
     payload: { format: 'pdf' }
   });

2. Success/Failure: Track outcomes of actions

   pluginpulse('YOUR_PLUGIN_ID', {
     event_name: 'Export Completed',
     payload: { success: true, duration_ms: 1250 }
   });

3. Configuration Changes: When settings are modified

   pluginpulse('YOUR_PLUGIN_ID', {
     event_name: 'Settings Changed',
     payload: { setting: 'theme', value: 'dark' }
   });

Payload Best Practices

• Keep payloads small and focused

• Avoid personally identifiable information (PII)

• Use consistent naming conventions

• Include success/failure status when applicable

• Consider adding timestamps for long-running operations

Implementation Examples

Tracking within an Action

function image_uploaded(instance, properties, context) {
  // Your existing code...

  pluginpulse("YOUR_PLUGIN_ID", {
    event_type: "feature",
    event_name: "Image Uploaded",
  });
}

Tracking element settings

function update(instance, properties, context) {
  // Your existing code...

  //Spread the properties into the payload to track all the initial settings
  pluginpulse("YOUR_PLUGIN_ID", {
    event_type: "feature",
    event_name: "Initialised Settings",
    payload: {
      ...properties,
    },
  });

  //Track a specific setting value
  if (properties.base64Output) {
    pluginpulse("YOUR_PLUGIN_ID", {
      event_type: "feature",
      event_name: "Base64 Output",
      payload: {
        base64Type: properties.base64Type,
      },
    });
  }
}

Error tracking

For tracking errors in your plugin

function example(instance, properties, context) {
  // Your existing code...
​
  if (error) {
    pluginpulse("YOUR_PLUGIN_ID", {
      event_type: "error",
      event_name: "Action Error",
      payload: {
        message: error.message,
        action: "Image Uploaded",
      },
    });
  }
}

Data Dashboard

All custom events appear in your PluginPulse dashboard alongside page views, allowing you to:

• Compare feature popularity

• Identify error patterns

• Understand user workflows

• Make data-driven decisions for future development

Remember that events are only tracked in test environments by default.