Core Concepts

Components, data attributes, and behavioral tracking fundamentals.

Components

Wrap content to personalize with the <ai-opt> element:

<ai-opt experiment="hero-block" component-id="1">
  <div class="hero">
    <h2>Comfort Runner Shoes</h2>
    <p>Ultra-light running shoes designed for all-day comfort.</p>
    <button>Shop Now</button>
  </div>
</ai-opt>
experiment

Unique name for the experiment

component-id

ID used to link with reward-button

Reward Button

Use <reward-button> to send feedback signals when users convert:

<reward-button
  variant="A"
  reward="100"
  component-ids='["1", "2"]'>
  Give Reward
</reward-button>
variant

Which variant to attribute reward to (A, B, etc.)

reward

Point value for this conversion (default: 1)

component-ids

JSON array of component IDs to reward

How It Works

StepDescription
1. Wrap contentPlace your HTML inside an <ai-opt> element
2. AI analyzesThe multi-agent system analyzes context and user behavior
3. Content optimizedAI generates personalized content variants
4. Learn & improveSystem learns from conversions and rewards

Identity States

Users are categorized into behavioral states based on their interactions:

confident

Quick decisions

exploratory

Browsing behavior

cautious

Hesitation patterns

impulse_buyer

Fast engagement

comparison_focused

Deep analysis

overwhelmed

Frustration signals

Variants Data Structure

Each user has variant data stored with scoring history for optimization:

{
  "user_id": "12345",

  "variants": {
    "A": {
      "current_html": "<div>...</div>",
      "current_score": 4.3,

      "history": [
        {
          "html": "<div>old version...</div>",
          "score": 3.2,
          "timestamp": "2026-01-17T20:00:00Z"
        },
        {
          "html": "<div>another version...</div>",
          "score": 4.1,
          "timestamp": "2026-01-17T21:00:00Z"
        }
      ]
    },

    "B": {
      "current_html": "<div>...</div>",
      "current_score": 3.0,

      "history": [
        {
          "html": "<div>previous B...</div>",
          "score": 2.7,
          "timestamp": "2026-01-17T19:30:00Z"
        }
      ]
    }
  }
}

Event Tracking

Track custom events to improve personalization:

// Track custom event
HtmlAI.track('product_viewed', 'product-123', {
  name: 'Running Shoes',
  price: 99.99
});

// Get user identity
const user = HtmlAI.getUser();