# Best Practices

Learn how to get the most out of **Tode analytics** in your Figma plugins and widgets. Following these best practices will help you collect meaningful data, avoid common pitfalls, and build a robust analytics implementation.

## Why Best Practices Matter

Good analytics implementation is the difference between actionable insights and noise. When you track the right events with clear naming conventions, you can:

- Understand how users actually interact with your plugin
- Identify which features drive engagement
- Make data-driven decisions about your product roadmap
- Debug issues by correlating user actions with errors

---

## Initialization

### Initialize Early

Call `tode.init()` immediately after `figma.showUI()` in your plugin controller. This ensures the SDK is ready before any user interactions occur.

```typescript title="code.ts"
import { tode } from '@tode-sdk/core';

// Show UI first
figma.showUI(__html__, { width: 400, height: 600 });

// Then initialize Tode
await tode.init({ apiKey: 'your-api-key' });

// Now safe to track
tode.trackAction('plugin_opened');
```

**Why this matters:** Initializing too late means you might miss early user interactions. Initializing too early (before `showUI()`) can cause configuration issues.

### Enable Debug Mode During Development

Use debug mode to see what's being tracked and catch issues early.

```typescript title="code.ts"
await tode.init({
  apiKey: 'your-api-key',
  debug: process.env.NODE_ENV === 'development'
});
```

**Why this matters:** Debug mode logs all tracking calls to the console, making it easy to verify your implementation without checking the dashboard.

---

## Tracking Events

### Track Right Away

You don't have to wait for `isReady`. The UI gets its config from the plugin controller a moment after it loads, and events tracked before that are held and sent once it arrives, with the time they actually happened.

```typescript
// Fine, even on the first render
tode.trackAction('plugin_opened');
```

The SDK holds up to 50 events this way. Use `isReady` for what it is good at: showing a connection status, or disabling a button until analytics is up.

### Track Meaningful Actions

Focus on tracking user interactions that provide actionable insights. Not every button click needs to be tracked.

```typescript
// Good - tracks key user journeys
tode.trackAction('plugin_opened');
tode.trackAction('export_completed');
tode.trackAction('settings_changed');
tode.trackAction('premium_feature_used');

// Bad - too granular, creates noise
tode.trackAction('mouse_moved');
tode.trackAction('input_focused');
tode.trackAction('scroll_happened');
```

**What to track:**
- Plugin open/close events
- Core feature usage (export, import, transform, etc.)
- Settings changes
- Error occurrences
- Conversion points (trial to paid, feature discovery)

**What to avoid:**
- Low-level UI interactions (hover, focus, scroll)
- Events that fire too frequently
- Redundant events that can be derived from others

---

## Naming Conventions

### Use Descriptive, Snake Case Names

Clear, consistent naming makes your analytics data much easier to analyze.

```typescript
// Good - descriptive snake_case
tode.trackAction('export_to_png');
tode.trackAction('layer_renamed');
tode.trackAction('color_picker_opened');
tode.trackAction('batch_resize_completed');

// Bad - vague or inconsistent
tode.trackAction('click');
tode.trackAction('action1');
tode.trackAction('exportToPNG'); // camelCase
tode.trackAction('Export To PNG'); // spaces
```

### Use a Consistent Naming Pattern

Adopt a pattern like `object_action` or `feature_action` and stick to it throughout your plugin.

```typescript
// Pattern: object_action
tode.trackAction('layer_selected');
tode.trackAction('layer_renamed');
tode.trackAction('layer_deleted');

// Pattern: feature_action
tode.trackAction('export_started');
tode.trackAction('export_completed');
tode.trackAction('export_failed');
```

**Why this matters:** Consistent naming makes it easy to filter and group events in your analytics dashboard. You can quickly see all layer-related or export-related events.

---

## Using Metrics

### Track Numeric Values When Relevant

Use `trackActionWithMetric()` when a numeric value adds context to the action.

```typescript
// Good - metric adds valuable context
tode.trackActionWithMetric('items_exported', 42);
tode.trackActionWithMetric('processing_time_ms', 1523);
tode.trackActionWithMetric('layers_selected', 5);

// Less useful - boolean as metric
tode.trackActionWithMetric('feature_enabled', 1); // Use trackAction instead
```

**Good use cases for metrics:**
- Count of items processed
- Processing duration
- File sizes
- Number of selected elements
- Numeric settings values

---

## Performance

### Don't Block User Interactions

Tracking calls are asynchronous and designed to not block the UI. Don't await them unless necessary.

```typescript
// Good - fire and forget
const handleExport = () => {
  tode.trackAction('export_started');
  performExport(); // Don't wait for tracking
};

// Usually unnecessary - awaiting tracking
const handleExport = async () => {
  await tode.trackAction('export_started'); // Blocks export
  performExport();
};
```

### Clean Up Resources

When using framework adapters, clean up when components unmount to prevent memory leaks.

```typescript
// React
useEffect(() => {
  return () => {
    // Cleanup handled by hook
  };
}, []);

// Svelte
onDestroy(() => todeStore.destroy());

// Vanilla
window.addEventListener('beforeunload', () => client.destroy());
```

---

## Testing Your Implementation

### Verify Events in Debug Mode

Before shipping, enable debug mode and walk through your plugin's user flows to verify all events fire correctly.

```typescript
await tode.init({
  apiKey: 'your-api-key',
  debug: true
});
```

### Check the Dashboard

After testing, verify that events appear in your Tode dashboard with the expected names and values.

---

## Common Mistakes to Avoid

| Mistake | Problem | Solution |
|---------|---------|----------|
| Never calling `init()` | Events wait forever and are never sent | Call `tode.init()` in code.ts after `showUI()` |
| Vague event names | Hard to analyze data | Use descriptive names |
| Tracking too much | Noise drowns signal | Focus on key interactions |
| Inconsistent naming | Fragmented analytics | Adopt a naming convention |
| Not cleaning up | Memory leaks | Call `destroy()` on unmount |

---

## Next Steps

- Review the [API Reference](https://docs.usetode.dev/api) for method details
- Check your framework guide: [React](https://docs.usetode.dev/react), [Vue](https://docs.usetode.dev/vue), [Angular](https://docs.usetode.dev/angular), [Svelte](https://docs.usetode.dev/svelte), [Vanilla](https://docs.usetode.dev/vanilla)
- Return to the [Introduction](https://docs.usetode.dev/) for setup instructions

Source: https://docs.usetode.dev/best-practices
