Custom Fields in Recommender Layouts

Engagement Recommender
,
1

Use custom article metadata in your Recommender layouts. When you configure Custom Fields to sync to Recommender, extracted values become available in the recommendations data and can be rendered directly in your layout templates.

How It Works

Custom Fields extracts metadata from your articles during crawling using XPath or JSONPath expressions. When you enable Sync to: Recommender on a custom field, the extracted value is stored with the article and included in the recommendations JSON payload.

Article HTML → Custom Fields extraction → Recommender data → Layout template

This means any metadata present in your page’s server-rendered HTML can flow into your recommendation modules without code changes on your site.

Accessing Custom Fields in Templates

Custom fields are delivered inside each recommendation object under the customProperties key. Access them with dot notation:

{{customProperties.yourFieldName}}

Extended Recommendations Data

With custom fields configured, the recommendations JSON expands:

{
  "recommendations": [{
    "title": "Article title",
    "url": "https://domain.com/path/to/article.html",
    "img": "https://domain.com/path/to/image.jpg",
    "authors": ["Author 1"],
    "sections": ["Politics"],
    "tags": ["Tag1", "tagGroup:Tag2"],
    "publishTime": "2024-12-26 17:01:03",
    "visibility": "open",
    "customProperties": {
      "description": "The article excerpt extracted from meta description",
      "alternativeImage": "https://domain.com/path/to/alt-image.jpg",
      "secondImage": "https://domain.com/path/to/second-image.jpg",
      "metaValue": "Custom metadata value"
    }
  }]
}

The customProperties object contains every custom field synced to Recommender for that article. Field names match the names you defined in your Custom Fields configuration.

Practical Examples

Display Article Excerpts

Extract og:description and render it below the headline. Useful for newsletter-style recommendation modules.

Custom Field configuration:

Setting Value
Expression //meta[@property="og:description"]/@content
Extract Attribute Value (content)
Save as Custom field: description
Sync to Recommender

Layout template:

{{#recommendations}}
<article>
  <a href="{{url}}">
    <img src="{{img}}" alt="{{title}}" />
    <h2>{{title}}</h2>
    {{#customProperties.description}}
      <p class="excerpt">{{customProperties.description}}</p>
    {{/customProperties.description}}
  </a>
</article>
{{/recommendations}}

The {{#customProperties.description}} block ensures the excerpt only renders when a value exists for that article.

Use Custom Thumbnail Images

Replace the default {{img}} with a publisher-preferred image extracted from structured data. Useful when the standard image crop doesn’t suit your layout.

Custom Field configuration:

Setting Value
Expression $.@graph[?(@.@type=="NewsArticle")].thumbnailUrl
Save as Custom field: thumbnailUrl
Sync to Recommender

Layout template:

{{#recommendations}}
<article>
  <a href="{{url}}">
    {{#customProperties.thumbnailUrl}}
      <img src="{{customProperties.thumbnailUrl}}" alt="{{title}}" />
    {{/customProperties.thumbnailUrl}}
    {{^customProperties.thumbnailUrl}}
      <img src="{{img}}" alt="{{title}}" />
    {{/customProperties.thumbnailUrl}}
    <h2>{{title}}</h2>
  </a>
</article>
{{/recommendations}}

This falls back to the default {{img}} when no custom thumbnail exists.

Add Proper Image Alt Text

Extract alt attributes from article images for use in recommendations. Improves accessibility and PageSpeed scores by avoiding generic fallbacks.

Custom Field configuration:

Setting Value
Expression //figure/img
Extract Attribute Value (alt)
Save as Custom field: imageAlt
Sync to Recommender

Layout template:

{{#recommendations}}
<article>
  <a href="{{url}}">
    <img src="{{img}}" alt="{{#customProperties.imageAlt}}{{customProperties.imageAlt}}{{/customProperties.imageAlt}}{{^customProperties.imageAlt}}{{title}}{{/customProperties.imageAlt}}" />
    <h2>{{title}}</h2>
  </a>
</article>
{{/recommendations}}

Uses the extracted alt text when available, falls back to {{title}} otherwise.

Display a Premium Badge

Show a visual indicator when an article belongs to a premium content tier. Combine with the built-in {{visibility}} field or use a custom field for more granular tiers.

Custom Field configuration:

Setting Value
Expression //meta[@name="content-tier"]/@content
Extract Attribute Value (content)
Save as Custom field: contentTier
Sync to Recommender

Layout template:

{{#recommendations}}
<article>
  <a href="{{url}}">
    <img src="{{img}}" alt="{{title}}" />
    <div class="headline-wrap">
      {{#if "customProperties.contentTier eq 'premium'"}}
        <span class="premium-badge">Premium</span>
      {{/if}}
      <h2>{{title}}</h2>
    </div>
  </a>
</article>
{{/recommendations}}

Conditionally Style by Custom Property

Apply different visual treatments based on extracted metadata. This example adds a CSS class based on a section-specific property:

{{#recommendations}}
<article class="card {{#customProperties.contentTier}}tier-{{customProperties.contentTier}}{{/customProperties.contentTier}}">
  <a href="{{url}}">
    <img src="{{img}}" alt="{{title}}" />
    <h2>{{title}}</h2>
  </a>
</article>
{{/recommendations}}

With corresponding CSS:

.tier-premium { border-left: 3px solid gold; }
.tier-free { border-left: 3px solid #ccc; }

Testing with Custom Fields

The Layout Editor preview uses the JSON tab’s example data. To test layouts that use custom fields:

  1. Open a Recommender experience that targets articles with custom fields configured
  2. Click JSON endpoint in the preview options (top right)
  3. Copy the response — it will include the customProperties object with real extracted data
  4. Paste into the Layout Editor’s JSON tab

You can also manually add a customProperties object to your test JSON to simulate different scenarios before real data is available.

Limits

Custom fields in Recommender layouts inherit the same restrictions as the Custom Fields configuration:

Going Deeper