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

# Customer Data Hydration

> Capture user engagement data from wizard questions and sync it to external platforms like Shopify for segmentation and personalization

When users answer questions in your Nudj challenges, those answers represent valuable customer data — preferences, interests, demographics, and intent signals. Customer Data Hydration captures those answers and makes them available both inside Nudj and in your external platforms, enabling powerful customer segmentation without manual data entry.

<Info>
  **How it works**: When a user completes a question action with data hydration enabled, Nudj stores the answer as structured custom data on the user's profile, then asynchronously syncs it to any connected external platforms.
</Info>

## Two-Layer Architecture

Customer Data Hydration operates in two layers. The first layer is always active when hydration is enabled. The second layer activates only when a platform sync is configured.

<CardGroup cols={2}>
  <Card title="Layer 1: Generic Custom Data" icon="layer-group" color="#10b981">
    **Always active when enabled**

    Stores resolved answers on the user's community profile as structured key-value data. Available immediately for use within Nudj — segmentation, personalization, and reporting.
  </Card>

  <Card title="Layer 2: Platform Sync" icon="arrows-rotate" color="#0ea5e9">
    **Optional, per-platform**

    Asynchronously syncs the same data to external platforms (e.g., Shopify customer metafields). Non-blocking — the user's participation flow is never delayed by external sync.
  </Card>
</CardGroup>

## Data Flow

<Steps>
  <Step title="User Answers a Question">
    A user completes a question action (multiple choice, open-ended, rating, date selection, etc.) within a challenge.
  </Step>

  <Step title="Answer is Resolved">
    Nudj resolves the raw answer into a human-readable value. For choice-based questions, option IDs are mapped to their labels. For typed questions, the value is coerced to the configured data type (text, integer, decimal, boolean, or date).
  </Step>

  <Step title="Custom Data is Stored">
    The resolved value is written to the user's community profile under a configurable field key. A schema definition is also tracked to ensure type consistency across actions sharing the same key.
  </Step>

  <Step title="Platform Sync is Queued">
    If a platform sync is configured (e.g., Shopify), an async job is queued to push the data to the external platform. This happens in the background and does not affect the user's experience.
  </Step>
</Steps>

## Supported Action Types

Data hydration works with any question-type action. The system automatically extracts the appropriate value based on the action type:

| Action Type           | Extracted Value          |
| --------------------- | ------------------------ |
| Multiple Choice       | Selected option label(s) |
| Select from List      | Selected option label(s) |
| Select from Images    | Selected option label(s) |
| Vote                  | Voted option label       |
| Open Ended            | Free-text answer         |
| Rate Your Experience  | Numeric rating           |
| Select Value in Range | Selected numeric value   |
| Select Date           | Date in ISO format       |
| Single Fixed Answer   | The fixed answer text    |
| Secret Access Code    | The entered code         |

## Data Types

Each hydrated field has a configured data type that determines how values are stored and validated:

| Type        | Description      | Example                |
| ----------- | ---------------- | ---------------------- |
| **Text**    | Free-form string | `"Blue"`, `"New York"` |
| **Integer** | Whole number     | `42`, `7`              |
| **Decimal** | Decimal number   | `4.5`, `9.99`          |
| **Boolean** | True/false       | `true`, `false`        |
| **Date**    | ISO date string  | `"2025-03-15"`         |

<Tip>
  If type coercion fails (e.g., a user enters "hello" for an integer field), the raw text value is still stored in Nudj's generic custom data layer. Only the external platform sync is skipped for that particular answer.
</Tip>

## Multi-Select Handling

For question actions where users can select multiple options, two storage modes are available:

<Tabs>
  <Tab title="Comma Separated">
    All selected labels are joined into a single text value.

    **Field key**: `favorite_colors`
    **Stored value**: `"Red, Blue, Green"`

    Best for: simple reporting, unlimited options, text-based platforms.
  </Tab>

  <Tab title="Boolean Expansion">
    Each option becomes its own boolean field. Limited to 5 options per action.

    **Field keys**: `favorite_colors_opt1`, `favorite_colors_opt2`, `favorite_colors_opt3`
    **Stored values**: `true`, `false`, `true`

    Best for: platforms that support boolean filters (e.g., Shopify customer segments), when you need per-option filtering.
  </Tab>
</Tabs>

## Platform Integrations

<CardGroup cols={2}>
  <Card title="Shopify" icon="shopify" href="/enterprise/customer-data-shopify">
    Sync customer data to Shopify metafields for native customer segmentation and personalization.

    **Status**: Available now
  </Card>

  <Card title="More Coming Soon" icon="puzzle-piece">
    Additional platform integrations (Adobe CDP, HubSpot, etc.) are on the roadmap.

    **Status**: Planned
  </Card>
</CardGroup>

## Key Concepts

<AccordionGroup>
  <Accordion title="Field Key">
    A unique identifier for each data field (e.g., `favorite_color`, `shirt_size`). Must be 2-64 characters, start with a lowercase letter, and contain only lowercase letters, numbers, and underscores. Auto-suggested from the question text but fully customizable.
  </Accordion>

  <Accordion title="Immutability After Sync">
    Once data has been synced to an external platform, certain configuration fields become locked: the field key, data type, multi-select mode, and choices override. This prevents breaking existing data on the external platform. Display name, description, and platform-specific settings like pinning can still be updated.
  </Accordion>

  <Accordion title="Non-Blocking Participation">
    External platform sync is always asynchronous. If Shopify is down or a sync fails, the user's challenge participation still succeeds. Failed syncs are automatically retried by the queue system.
  </Accordion>

  <Accordion title="Schema Consistency">
    If two actions share the same field key, they must use the same data type. Nudj tracks field definitions per community and rejects conflicting type assignments. This ensures data integrity across your entire question library.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Configure Data Hydration" icon="sliders" href="/enterprise/customer-data-configuration">
    Learn how to enable and configure data hydration on your question actions in the admin panel.
  </Card>

  <Card title="Shopify Integration" icon="shopify" href="/enterprise/customer-data-shopify">
    Set up Shopify customer metafield sync for native segmentation in your Shopify store.
  </Card>
</CardGroup>