> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mutalabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Events

> Learn how to handle custom events from your Muta flows

Muta allows you to emit custom events from your flows using the platform's behavior system. You can configure custom events in the Muta web editor and listen for them in your app to trigger specific actions.

## Setting Up Custom Events

1. In the Muta web editor, add an "Emit Event" behavior to any element
2. Give your event a unique name (e.g., `signup_started`, `premium_selected`, `survey_completed`)
3. Optionally add custom data to pass along with the event

## Example Usage

```tsx theme={null}
import { Muta } from '@mutalabs/react-native-muta';

function Onboarding() {
  useEffect(() => {
    // Listen for your custom events
    const signupListener = Muta.on('signup_started', (event) => {
      console.log('User started signup process');
      // Trigger your signup flow
      navigateToSignup();
    });

    const premiumListener = Muta.on('premium_selected', (event) => {
      console.log('User selected premium option', event.eventData);
      // Handle premium selection
      setPremiumUser(true);
    });

    const surveyListener = Muta.on('survey_completed', (event) => {
      console.log('Survey answers:', event.eventData);
      // Save survey responses
      saveSurveyData(event.eventData);
    });

    const formListener = Muta.on('form_submitted', (event) => {
      // Access the form data from eventData
      const { name, email, preferences } = event.eventData;
      
      console.log('User submitted:', { name, email, preferences });
      
      // Save to your backend
      saveUserProfile({ name, email, preferences });
    });

    // Show the placement
    Muta.displayPlacement({
      placementId: 'your-placement-id',
      bgColor: '#000000'
    });

    return () => {
      signupListener.remove();
      premiumListener.remove();
      surveyListener.remove();
      formListener.remove();
    };
  }, []);

  return <View style={{ flex: 1 }} />;
}
```

## Custom Event Structure

```tsx theme={null}
{
  type: string,         // Your custom event name
  timestamp: number,    // Unix timestamp in ms
  placementId: string,  // ID of the placement
  flowName?: string,    // Name of the flow
  screenIndex?: number, // Current screen index
  eventData?: any       // Custom data you configured in the editor
}
```

## Common Use Cases

### User Actions

Track when users click specific CTAs or make choices:

```tsx theme={null}
Muta.on('cta_clicked', (event) => {
  const buttonName = event.eventData?.buttonName;
  analytics.track('CTA Click', { button: buttonName });
});
```

### Navigation Control

Trigger app navigation based on flow interactions:

```tsx theme={null}
Muta.on('go_to_home', () => navigation.navigate('Home'));
Muta.on('open_settings', () => navigation.navigate('Settings'));
Muta.on('start_tutorial', () => startTutorial());
```

### Data Collection

Gather form submissions or survey responses:

```tsx theme={null}
Muta.on('preferences_selected', (event) => {
  const preferences = event.eventData?.preferences;
  AsyncStorage.setItem('userPreferences', JSON.stringify(preferences));
});
```

### Feature Flags

Enable/disable features based on onboarding choices:

```tsx theme={null}
Muta.on('feature_toggle', (event) => {
  const { feature, enabled } = event.eventData;
  featureFlags.set(feature, enabled);
});
```

### Conversion Tracking

Track specific conversion events:

```tsx theme={null}
Muta.on('trial_started', (event) => {
  mixpanel.track('Trial Started', {
    plan: event.eventData?.plan,
    duration: event.eventData?.duration
  });
});

Muta.on('purchase_initiated', (event) => {
  analytics.track('Purchase Initiated', {
    product: event.eventData?.product,
    price: event.eventData?.price
  });
});
```

## Best Practices

1. **Consistent Naming**: Use descriptive, consistent event names across your flows
2. **Type Safety**: Consider creating a TypeScript interface for your custom events
3. **Error Handling**: Always validate eventData before using it
4. **Documentation**: Document your custom events and their expected data structure
5. **Analytics Integration**: Forward custom events to your analytics provider for tracking
6. **Cleanup**: Always remove event listeners when components unmount to prevent memory leaks