# ISML isactivedatahead Element
## Overview
The `<isactivedatahead>` element configures pages to enable active data collection from ISML templates. It initializes the necessary JavaScript libraries and tracking infrastructure for Commerce Cloud analytics, Einstein AI, and customer behavior tracking. This element is essential for enabling data collection capabilities on pages with an HTML `<head>` tag.
## Syntax
```isml
<isactivedatahead/>
```
## Attributes
**None** - This is a self-closing tag with no attributes.
## Purpose
The `<isactivedatahead>` element serves several critical functions:
1. **Analytics Initialization:** Sets up the active data collection framework for the page
2. **Einstein AI Support:** Enables data collection for Einstein recommendations and personalization
3. **JavaScript Library Loading:** Loads required tracking scripts and analytics libraries
4. **Data Collection Framework:** Establishes the foundation for other analytics ISML tags to function
5. **Customer Behavior Tracking:** Enables tracking of customer interactions and browsing patterns
### When to Use
- **Required:** On all templates that contain an HTML `<head>` tag and serve customer-facing pages
- **Not Required:** On templates without an HTML `<head>` tag (e.g., included fragments, AJAX responses)
- **Best Practice:** Include on all `<head>` tags unless the page has guaranteed no analytic interest
### When to Skip
You may skip this tag only if:
- The template has no HTML `<head>` tag
- The page is guaranteed to never have data of analytic interest
- The page is purely administrative or internal (not customer-facing)
## Placement Requirements
### Recommended Placement
**Best Practice:** Place the tag **immediately before the closing `</head>` tag**:
```isml
<head>
<title>${pdict.pageTitle}</title>
<meta charset="UTF-8">
<!-- Other head elements -->
<isactivedatahead/>
</head>
```
### Critical Placement Rules
The tag **must** appear in the following order:
1. ✅ **After** all references to external JavaScript libraries
2. ✅ **Before** any other analytics data collection ISML tags
3. ✅ In a location where `<script>` tags are valid
#### Rule 1: After External JavaScript Libraries
```isml
<head>
<!-- External JavaScript libraries first -->
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script src="${URLUtils.staticURL('/js/main.js')}"></script>
<!-- Then isactivedatahead -->
<isactivedatahead/>
</head>
```
**Why:** Placing it before external libraries can cause compatibility issues with those libraries.
#### Rule 2: Before Other Analytics Tags
```isml
<head>
<!-- isactivedatahead first -->
<isactivedatahead/>
<!-- Then other analytics tags -->
<isactivedatacontext category="${pdict.category}" />
</head>
```
**Why:** Other analytics tags depend on the framework initialized by `<isactivedatahead>` and will fail to collect data if it appears after them.
#### Rule 3: Valid Script Location
```isml
<!-- ✅ Good: Inside head tag -->
<head>
<isactivedatahead/>
</head>
<!-- ✅ Good: At end of body -->
<body>
<!-- Page content -->
<isactivedatahead/>
</body>
<!-- ❌ Bad: Between table rows -->
<table>
<tr><td>Data</td></tr>
<isactivedatahead/> <!-- Invalid: Not a valid script location -->
<tr><td>More Data</td></tr>
</table>
```
## Common Use Cases
### Standard Page Template
```isml
<iscontent type="text/html" charset="UTF-8" compact="true"/>
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>${pdict.pageTitle}</title>
<!-- CSS -->
<link rel="stylesheet" href="${URLUtils.staticURL('/css/main.css')}">
<!-- External JavaScript -->
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<!-- Active Data Head - Before closing head tag -->
<isactivedatahead/>
</head>
<body>
<!-- Page content -->
</body>
</html>
```
### SFRA Decorator Pattern
```isml
<!-- common/layout/page.isml -->
<iscontent type="text/html" charset="UTF-8" compact="true"/>
<!DOCTYPE html>
<html lang="${require('dw/util/Locale').getLocale(request.getLocale()).getLanguage()}">
<head>
<isinclude template="components/header/htmlHead" />
<!-- Additional head elements -->
<isactivedatahead/>
</head>
<body>
<isreplace/>
</body>
</html>
```
### With Category Context
```isml
<head>
<title>${pdict.category.displayName}</title>
<!-- External libraries -->
<script src="${URLUtils.staticURL('/js/vendor.js')}"></script>
<!-- Active data initialization -->
<isactivedatahead/>
<!-- Category context (after isactivedatahead) -->
<isactivedatacontext category="${pdict.category}" />
</head>
```
### Product Detail Page
```isml
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>${pdict.product.productName}</title>
<!-- SEO Meta Tags -->
<meta name="description" content="${pdict.product.shortDescription}">
<!-- Stylesheets -->
<link rel="stylesheet" href="${URLUtils.staticURL('/css/product.css')}">
<!-- JavaScript Libraries -->
<script src="${URLUtils.staticURL('/js/jquery.min.js')}"></script>
<script src="${URLUtils.staticURL('/js/product.js')}"></script>
<!-- Active Data Head -->
<isactivedatahead/>
<!-- Product Category Context -->
<isactivedatacontext category="${pdict.product.primaryCategory}" />
</head>
<body>
<!-- Product details -->
</body>
</html>
```
### Modular Head Template
```isml
<!-- components/header/htmlHead.isml -->
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<!-- Favicon -->
<link rel="icon" type="image/x-icon" href="${URLUtils.staticURL('/images/favicon.ico')}">
<!-- CSS Resources -->
<isinclude template="components/header/cssIncludes" />
<!-- JavaScript Resources -->
<isinclude template="components/header/jsIncludes" />
<!-- Active Data Initialization -->
<isactivedatahead/>
```
## Best Practices
1. **Always Include on Customer-Facing Pages:**
```isml
<!-- Include on all standard pages -->
<head>
<!-- ... -->
<isactivedatahead/>
</head>
```
2. **Place Before Closing Head Tag:**
```isml
<head>
<title>${pdict.pageTitle}</title>
<!-- All other head elements -->
<isactivedatahead/> <!-- Last item before </head> -->
</head>
```
3. **Centralize in Decorator Templates:**
```isml
<!-- Put in main page decorator for consistent inclusion -->
<!-- common/layout/page.isml -->
<head>
<isinclude template="components/htmlHead" />
<isactivedatahead/>
</head>
```
4. **Check External Library Order:**
```isml
<head>
<!-- 1. External libraries first -->
<script src="https://cdn.example.com/library.js"></script>
<!-- 2. Then isactivedatahead -->
<isactivedatahead/>
<!-- 3. Then analytics tags -->
<isactivedatacontext category="${pdict.category}" />
</head>
```
5. **Don't Duplicate:**
```isml
<!-- Bad: Multiple instances -->
<head>
<isactivedatahead/>
<!-- ... -->
<isactivedatahead/> <!-- Unnecessary duplication -->
</head>
<!-- Good: Single instance -->
<head>
<!-- ... -->
<isactivedatahead/>
</head>
```
6. **Include Only Once Per Page:**
- Place in the main decorator template, not in multiple includes
- Avoid adding to fragment templates that don't have their own `<head>` tag
7. **Conditional Inclusion for Special Cases:**
```isml
<!-- Only if analytics is enabled -->
<isif condition="${!pdict.isInternalPage}">
<isactivedatahead/>
</isif>
```
## Consequences of Incorrect Placement
### Missing Tag
**Impact:**
- Analytics data collection fails
- Einstein recommendations may not work
- Customer behavior tracking is disabled
- Marketing attribution is lost
**Example:**
```isml
<!-- Bad: Missing isactivedatahead -->
<head>
<title>${pdict.pageTitle}</title>
<isactivedatacontext category="${pdict.category}" /> <!-- Will fail -->
</head>
```
### Tag After Analytics Tags
**Impact:**
- Other analytics tags fail to collect data
- JavaScript errors in browser console
- Incomplete tracking data
**Example:**
```isml
<!-- Bad: isactivedatahead after analytics tags -->
<head>
<isactivedatacontext category="${pdict.category}" /> <!-- Will fail -->
<isactivedatahead/> <!-- Too late -->
</head>
```
### Tag Before External Libraries
**Impact:**
- External JavaScript libraries may become incompatible
- Potential JavaScript conflicts
- Page rendering issues
**Example:**
```isml
<!-- Bad: Before external libraries -->
<head>
<isactivedatahead/> <!-- Too early -->
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
</head>
```
### Invalid Script Location
**Impact:**
- JavaScript errors
- Page rendering failures
- Analytics initialization fails
**Example:**
```isml
<!-- Bad: Invalid location -->
<table>
<tr>
<td>Data</td>
<isactivedatahead/> <!-- Invalid: Not a valid script location -->
</tr>
</table>
```
## Error Handling
When the tag is missing or incorrectly placed:
1. **JavaScript Errors:** Browser console may show initialization errors
2. **Page Rendering Issues:** Visual elements may not render correctly
3. **Silent Failures:** Analytics may fail silently without obvious errors
4. **User Experience Impact:** Customers may see error messages or broken functionality
### Debugging Missing Tag
```javascript
// Check if active data framework is initialized in browser console
if (typeof window.dw !== 'undefined' && window.dw.ac) {
console.log('Active data initialized');
} else {
console.error('Active data not initialized - check for isactivedatahead tag');
}
```
## Template Types
### Templates That Should Include the Tag
- ✅ Main page decorators (`common/layout/page.isml`)
- ✅ Product detail pages
- ✅ Category landing pages
- ✅ Search results pages
- ✅ Cart and checkout pages
- ✅ Account pages
- ✅ Homepage templates
### Templates That Should NOT Include the Tag
- ❌ Fragment templates without `<head>` tag
- ❌ AJAX response templates
- ❌ Email templates
- ❌ Include-only components
- ❌ JSON/XML output templates
- ❌ Fragments loaded via AJAX
## Integration with Other Analytics Tags
The `<isactivedatahead>` tag works with other analytics elements:
```isml
<head>
<!-- External libraries -->
<script src="${URLUtils.staticURL('/js/vendor.js')}"></script>
<!-- 1. Initialize active data framework -->
<isactivedatahead/>
<!-- 2. Set category context (depends on isactivedatahead) -->
<isif condition="${pdict.category}">
<isactivedatacontext category="${pdict.category}" />
</isif>
<!-- 3. Other tracking tags (depend on isactivedatahead) -->
<isanalytics/>
</head>
```
**Dependency Chain:**
1. External JavaScript libraries (if any)
2. `<isactivedatahead/>` (initializes framework)
3. `<isactivedatacontext/>` (uses framework)
4. Other analytics tags (use framework)
## Performance Considerations
- **Minimal Overhead:** The tag loads necessary scripts asynchronously when possible
- **Caching:** Script resources are cached for improved performance
- **Page Load Impact:** Minimal impact on initial page load time
- **Async Loading:** Many tracking scripts load asynchronously to avoid blocking rendering
## Testing and Validation
### Manual Testing
1. **View Page Source:** Verify the tag appears in the correct location
2. **Browser Console:** Check for JavaScript errors
3. **Network Tab:** Verify analytics beacons are sent
4. **Einstein Activity:** Confirm recommendations are working
### Validation Checklist
- [ ] Tag appears in templates with `<head>` tags
- [ ] Tag is placed after external JavaScript libraries
- [ ] Tag is placed before other analytics tags
- [ ] Tag is in a valid `<script>` location
- [ ] No JavaScript errors in browser console
- [ ] Analytics beacons appear in network tab
- [ ] Page renders correctly without errors
### Common Test Scenarios
```isml
<!-- Test 1: Verify basic placement -->
<head>
<title>Test Page</title>
<isactivedatahead/>
</head>
<!-- Test 2: Verify with external libraries -->
<head>
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<isactivedatahead/>
</head>
<!-- Test 3: Verify with category context -->
<head>
<script src="${URLUtils.staticURL('/js/main.js')}"></script>
<isactivedatahead/>
<isactivedatacontext category="${pdict.category}" />
</head>
```
## Migration Guidance
### SiteGenesis to SFRA
When migrating from SiteGenesis to SFRA:
1. **Locate Existing Tags:** Find all `<isactivedatahead/>` instances in SiteGenesis templates
2. **Move to Decorator:** Consolidate into SFRA decorator template
3. **Verify Placement:** Ensure correct order with external libraries
4. **Test Thoroughly:** Verify analytics continue working after migration
```isml
<!-- SiteGenesis: htmlhead_UI.isml -->
<head>
<!-- ... -->
<isactivedatahead/>
</head>
<!-- SFRA: common/layout/page.isml -->
<head>
<isinclude template="components/header/htmlHead" />
<isactivedatahead/>
</head>
```
## Related Elements
- `<isactivedatacontext>` - Sets category context for analytics (depends on this tag)
- `<isanalytics>` - General analytics tracking (depends on this tag)
- `<isslot>` - Content slots that may use active data for targeting
## Notes
- This tag has no visible output; it only includes JavaScript tracking code
- Required for Einstein AI and Commerce Cloud analytics to function
- Must appear exactly once per page (in the main template)
- Templates without `<head>` tags should not use this tag
- The tag is a prerequisite for other analytics ISML tags to work
- Incorrect placement can cause JavaScript errors and broken page rendering
## Security Considerations
- The tag loads scripts from trusted Commerce Cloud domains
- No customer data is exposed client-side by this tag alone
- Follow Content Security Policy (CSP) guidelines when using this tag
- Ensure tracking scripts are loaded over HTTPS in production
## Troubleshooting
### No Analytics Data Collected
**Check:**
1. Tag is present in the `<head>` section
2. Tag appears before other analytics tags
3. No JavaScript errors in browser console
### JavaScript Errors
**Check:**
1. Tag is placed after external JavaScript libraries
2. Tag is in a valid `<script>` location
3. No duplicate tags on the page
### Einstein Recommendations Not Working
**Check:**
1. `<isactivedatahead/>` is present
2. `<isactivedatacontext/>` is correctly configured
3. Both tags are in the correct order
### Page Rendering Issues
**Check:**
1. Tag is not placed in invalid locations (e.g., between table rows)
2. Tag appears only once per page
3. No conflicts with external JavaScript libraries
