# Custom Events

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:

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

### Parameters

<table><thead><tr><th width="124.58984375">Parameter</th><th width="100.01953125">Required</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>plugin_id</td><td>Yes</td><td>Your PluginPulse plugin ID</td><td>"1706526741286x876166435619471400"</td></tr><tr><td>event_type</td><td>No</td><td>Type of event (default: "page_view")</td><td>"page_view", "feature", "error"</td></tr><tr><td>event_name</td><td>No</td><td>Name of the event/feature (default: "Page View")</td><td>"Export PDF"</td></tr><tr><td>payload</td><td>No</td><td>Custom JSON data for additional context</td><td><code>{format: "pdf", pages: 5}</code></td></tr></tbody></table>

### 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

   ```javascript
   pluginpulse('YOUR_PLUGIN_ID', {
     event_name: 'Export Started',
     payload: { format: 'pdf' }
   });
   ```
2. **Success/Failure**: Track outcomes of actions

   ```javascript
   pluginpulse('YOUR_PLUGIN_ID', {
     event_name: 'Export Completed',
     payload: { success: true, duration_ms: 1250 }
   });
   ```
3. **Configuration Changes**: When settings are modified

   ```javascript
   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

{% code overflow="wrap" lineNumbers="true" %}

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

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

{% endcode %}

#### Tracking element settings

```javascript
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

```javascript
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.