# User Preferences Feature

## Overview

The User Preferences feature allows subscribers to customize their email experience directly from your unsubscribe page. Instead of unsubscribing, subscribers can:

- **Adjust email frequency** - Choose how often they receive emails (weekly, monthly, etc.)
- **Select email topics** - Choose which types of emails they want to receive
- **Stay subscribed** - Remain on your list with their preferred settings

This feature helps you retain more subscribers by giving them control over their email experience.

## How It Works

### Subscriber Experience

1. **Initial Page** - When a subscriber clicks unsubscribe, they see your initial page with options
2. **Preferences Page** - If they click "Manage Email Preferences", they're taken to a preferences page
3. **Customization** - They can:
   - Select their preferred email frequency (e.g., weekly, monthly)
   - Choose which email topics they want (e.g., promotions, newsletters, updates)
   - Save their preferences
4. **Confirmation** - After saving, they see a success message and remain subscribed

### Behind the Scenes

When preferences are saved:

1. **Klaviyo Profile Updated** - The subscriber's Klaviyo profile is updated with:
   - `email_frequency` - Their selected frequency
   - `email_topics` - Comma-separated list of selected topics
   - `stay_subscribed` - Set to `true`

2. **Database Storage** - Preferences are stored in the database for:
   - Analytics tracking
   - Pre-filling preferences on future visits
   - Reporting and insights

3. **Analytics Events** - Two separate events are tracked:
   - `ACTION_SAVED_FREQUENCY` - When frequency is saved
   - `ACTION_SAVED_TOPICS` - When topics are saved

## Setting Up Preferences

### 1. Configure Frequency Options

Go to **Settings → User Preferences → Frequencies tab**:

- Add or edit frequency options (e.g., "Weekly", "Monthly", "Quarterly")
- Set the number of days for each frequency
- Reorder options by dragging
- Enable/disable specific options

### 2. Configure Topic Options

Go to **Settings → User Preferences → Topics tab**:

- Add or edit topic options (e.g., "Promotions", "Newsletters", "Product Updates")
- Customize labels for each topic
- Reorder options by dragging
- Enable/disable specific options

### 3. Create Topic Exclusion Segments (Klaviyo)

In the Topics tab, scroll to the **Segments** section. Create topic exclusion segments for each topic. These segments contain subscribers who have opted out of that topic. In Klaviyo campaigns and flows:

- **Send to:** Use any main segment (e.g., "All Subscribers", "Newsletter List")
- **Don't send to:** Add the **matching** topic exclusion segment—the one that corresponds to the type of email you're sending (e.g., for a newsletter campaign, add `LC - Exclude Topic: Newsletters`; for a sales campaign, add `LC - Exclude Topic: Sales & Discounts`)

This lets you use your existing segments while respecting subscriber topic preferences.

### 4. Create Frequency Exclusion Segments (Klaviyo)

In the Frequencies tab, scroll to the **Segments** section. Create frequency exclusion segments for each frequency. These segments contain subscribers who chose a less-frequent option. In Klaviyo campaigns and flows:

- **Send to:** Use any main segment
- **Don't send to:** Add **every** LC - Exclude Frequency segment (e.g., `LC - Exclude Frequency: Weekly`, `LC - Exclude Frequency: Monthly`, etc.)—you need all of them to enforce frequency limits across your audience

### 5. Add Preferences Page to Your Unsubscribe Page

In your unsubscribe page editor:

1. Add a "Manage Email Preferences" button with `data-action="go-to-preferences"`
2. Create a preferences page using the template variables:
   - Use `{{preferencesFrequencies}}` to automatically generate frequency selection options
   - Use `{{preferencesTopics}}` to automatically generate topic selection options
   - Add save buttons with `data-action="save-frequency"` and `data-action="save-topics"`

**Example preferences page HTML:**

```html
<div class="preferences-form">
  <div class="preferences-section">
    <h3>Email Frequency</h3>
    <p>How often would you like to hear from us?</p>
    {{preferencesFrequencies}}
    <button data-action="save-frequency">Save Frequency</button>
  </div>

  <div class="preferences-section">
    <h3>Email Topics</h3>
    <p>What would you like to hear about?</p>
    {{preferencesTopics}}
    <button data-action="save-topics">Save Topics</button>
  </div>
</div>
```

The template variables automatically generate the correct HTML form elements (radio buttons for frequency, checkboxes for topics) based on your team-wide configuration. This ensures consistency and makes it easy to update options across all pages.

> **Note:** For advanced use cases where you want custom options that differ from your team-wide settings, you can manually create form elements with `name="emailFrequency"` and `name="emailTopics"`, but this is generally not recommended as it won't sync with your team configuration.

### 6. Use Preferences Components

The page editor includes built-in components:

- **Frequency Options** - Pre-built frequency selection component (uses `{{preferencesFrequencies}}`)
- **Topic Options** - Pre-built topic selection component (uses `{{preferencesTopics}}`)
- **Preferences Frequencies** - Full preferences page with frequency options
- **Preferences Topics** - Full preferences page with topic options

## Template Variables

When building custom preferences pages, use these template variables:

### Frequency Variables

- `{{preferencesFrequencies}}` - Automatically generates HTML for frequency selection (radio buttons) based on your team's frequency configs
- The generated HTML includes proper form structure with `name="emailFrequency"` attributes
- Options are automatically pulled from your team-wide frequency configuration

### Topic Variables

- `{{preferencesTopics}}` - Automatically generates HTML for topic selection (checkboxes) based on your team's topic configs
- The generated HTML includes proper form structure with `name="emailTopics"` attributes
- Options are automatically pulled from your team-wide topic configuration

### Other Variables

- `{{selectedFrequency}}` - Currently selected frequency (if user has saved preferences) - used by `PreferencesInitializer` component
- `{{selectedTopics}}` - Array of currently selected topics (if user has saved preferences) - used by `PreferencesInitializer` component

## Best Practices

### 1. Make Preferences Easy to Find

- Place the "Manage Email Preferences" button prominently on your initial page
- Use clear, action-oriented text like "Manage Email Preferences" or "Customize My Emails"

### 2. Keep Options Simple

- Limit frequency options to 3-5 choices
- Limit topic options to 5-7 choices
- Use clear, descriptive labels

### 3. Provide Defaults

- Pre-select the most common frequency option
- Pre-select all topics by default (users can uncheck what they don't want)

### 4. Show Success Feedback

- Display a clear success message after saving
- Confirm what was saved (e.g., "Your preferences have been saved!")

### 5. Allow Partial Updates

- Users can save frequency and topics separately
- Don't require both to be set at once

## Troubleshooting

### Preferences Not Saving

- Check that the save button has the correct `data-action` attribute
- Verify the API endpoint is accessible
- Check browser console for errors

### Preferences Not Showing

- Ensure preferences page is included in your unsubscribe page
- Verify the `PreferencesInitializer` component is included
- Check that saved preferences exist in the database

### Klaviyo Profile Not Updating

- Verify Klaviyo integration is connected
- Check that the subscriber's profile exists in Klaviyo
- Review Klaviyo API logs for errors

## Related Features

- [Analytics](./analytics.md) - Track preferences-related events
- [Subscriber Experience](./subscriber-experience.md) - Understand the full subscriber journey
- [Getting Started](./getting-started.md) - Initial setup guide