Architecture overview 

The extension does not call rek.ai APIs from PHP. Instead, TYPO3 outputs HTML <div> elements with data-* attributes, and the rek.ai JavaScript client reads those attributes at runtime to render personalized content.

Feature overview 

• Middleware-based script embedding in frontend responses
• Per-site configuration via Site Settings (TYPO3 13/14) or config.yaml fallback (TYPO3 12)
• Consent mode support (data-useconsent attribute)
• Optional autocomplete initialization for a configurable CSS selector
• Content element Rek.ai Recommendations (rekai_recommendations)
• Content element Rek.ai Q&A (rekai_qna)
• Test mode with project ID and secret key for sandbox environments
• Automatic window.rek_blocksaveview for logged-in backend users so editor previews are not counted as visits

Compatibility 

• TYPO3: 12.4 LTS, 13.4 LTS, 14.x
• PHP: 8.1 (TYPO3 12) or 8.2+ (TYPO3 13/14)
• EXT:fluid_styled_content (included in TYPO3 core)

Requirements 

• TYPO3 12.4 LTS, 13.4 LTS, or 14.x
• PHP 8.1 (TYPO3 12) or PHP 8.2+ (TYPO3 13/14)
• A rek.ai account with a project and script URL

Install via Composer 

composer require pluswerk/rekai

Activate the extension 

In non-Composer setups, activate the extension manually:

1. Open Admin Tools > Extensions
2. Find rekai and activate it
3. Flush all caches

Configure the site (TYPO3 13 / 14) 

Add the Rek.ai Site Set as a dependency of your site:

dependencies:
  - pluswerk/rekai

The settings then appear in the Site module under Site Management > Sites > [your site] > Settings > rekai. At minimum set rekai.enabled to true and enter rekai.embedCode.

Configure the site (TYPO3 12) 

Site Sets and the Settings UI do not exist in TYPO3 12. Settings must be written directly into config/sites/<identifier>/config.yaml under the settings.rekai key:

settings:
  rekai:
    enabled: true
    embedCode: 'https://cdn.rek.ai/PROJECT/s.js'
    consentMode: true
    autocomplete:
      mode: auto
      selector: '#tx-solr-q'
      nrOfHits: 10
      navigateOnClick: true
      useCurrentLang: true
    advanced:
      testMode: false

The TypoScript (templates and FlexForm defaults) is loaded automatically via the static template Rek.ai which must be included in the site's root TypoScript template.

See Configuration for all available settings and the full migration table from 1.x.

Site settings 

Since version 2.0, all global settings are managed per site.

TYPO3 13 / 14 — manage values through the Settings editor. Open Site Management > Sites, then on the site card click the gear icon (Site-Einstellungen bearbeiten):

In the Settings editor, expand the Rek.ai group on the left to access Basic, Autocomplete and Advanced:

Values are stored in config/sites/<identifier>/settings.yaml under the flat rekai namespace (one entry per dotted key).

TYPO3 12 — the Settings editor does not exist. Write the values directly into config/sites/<identifier>/config.yaml under settings.rekai as a nested tree (see Example below). The extension reads from this location automatically when the TYPO3 13+ SiteSettings API is unavailable.

Example 

TYPO3 13 / 14 — flat keys in settings.yaml (written by the editor or by hand):

rekai.enabled: true
rekai.embedCode: 'https://cdn.rek.ai/PROJECT/s.js'
rekai.consentMode: true
rekai.autocomplete.mode: auto
rekai.autocomplete.selector: '#tx-solr-q'
rekai.autocomplete.nrOfHits: 10
rekai.autocomplete.navigateOnClick: true
rekai.autocomplete.useCurrentLang: true
rekai.advanced.testMode: false

TYPO3 12 — nested tree in config.yaml under settings.rekai:

settings:
  rekai:
    enabled: true
    embedCode: 'https://cdn.rek.ai/PROJECT/s.js'
    consentMode: true
    autocomplete:
      mode: auto
      selector: '#tx-solr-q'
      nrOfHits: 10
      navigateOnClick: true
      useCurrentLang: true
    advanced:
      testMode: false

Content element FlexForm settings 

Each content element exposes additional settings through a FlexForm panel visible in the backend. See Editor Guide for field descriptions.

Validation behaviour 

If the extension is enabled but rekai.embedCode is not a valid HTTPS URL, the rek.ai script is silently not injected. No error is thrown.

Migration from 1.x 

Before 2.0, settings were stored globally in Admin Tools > Settings > Extension Configuration > rekai. Move your existing values into the site settings:

Adding a content element 

Both rek.ai content elements are available in the new content element wizard under the rek.ai group:

• Rek.ai Recommendations — displays personalized page recommendations
• Rek.ai Q&A — displays context-aware questions and answers

Standard TYPO3 header fields (header, subheader, header layout) are available on each element and rendered by your site template in the standard TYPO3 way.

Rek.ai Recommendations 

Rek.ai Q&A 

Architecture overview 

The extension has three independent parts:

1. Middleware — injects the rek.ai script tag into every frontend response
2. Controllers — produce <div data-*> placeholder markup for the content elements
3. TypoScript / Fluid — integrates the content elements into lib.contentElement

Middleware 

Pluswerk\Rekai\Middleware\RekaiScriptMiddleware runs in the frontend middleware stack (after prepare-tsfe-rendering, before output-compression) and uses TYPO3's AssetCollector to inject:

• the external rek.ai script from embedCode
• an optional data-useconsent="true" attribute when consent mode is active
• an optional inline autocomplete bootstrap script
• window.rek_blocksaveview = true; for backend users and in test mode

The script is not loaded with defer — the rek.ai widget runtime expects to initialise during HTML parsing, before its containers are discovered.

Controllers 

RecommendationsController::showAction() and QnaController::showAction() both inherit from AbstractRekaiController. They build a <div> element with the rek.ai data-* attributes derived from the content element's FlexForm settings and the site-resolved configuration, then assign it to the Fluid template as {divHtml}.

The controllers do not perform any HTTP calls to rek.ai. All data fetching happens in the visitor's browser via the injected JavaScript.

Templates 

Content element integration uses the lib.contentElement FLUIDTEMPLATE mechanism. Two templates are registered under a dedicated template root path:

• Resources/Private/Templates/Content/RekaiRecommendations.fluid.html
• Resources/Private/Templates/Content/RekaiQna.fluid.html

The plugin action templates (consumed by Extbase) are separate:

• Resources/Private/Templates/Recommendations/Show.html
• Resources/Private/Templates/Qna/Show.html

These output only {divHtml} — the raw <div> placeholder.

TypoScript 

Configuration/TypoScript/setup.typoscript adds the content template root path to lib.contentElement and registers the FlexForm default values for both plugins.

Configuration service 

Pluswerk\Rekai\Configuration\SiteConfigurationService resolves the rek.ai configuration for a given site and returns an immutable Pluswerk\Rekai\Configuration\SiteConfiguration DTO.

The service inspects the TYPO3 major version via the injected Typo3Version and dispatches to one of two readers:

• TYPO3 13/14: $site->getSettings()->get('rekai', []) — reads the nested tree built from the flat settings.yaml of the Site Set.
• TYPO3 12: $site->getConfiguration()['settings']['rekai'] — reads the nested settings.rekai block from config.yaml directly, since Site Sets and the SiteSettings API do not exist on 12.

The Site Set definition lives in Configuration/Sets/Rekai/ and is loaded automatically when a site declares pluswerk/rekai as a dependency. On TYPO3 12 the Site Set is ignored; the TypoScript is still loaded via ext_localconf.php.

Dependency injection 

All classes use TYPO3's standard DI container (Configuration/Services.yaml with autowire: true and autoconfigure: true). Typo3Version is an optional constructor argument on SiteConfigurationService so the service can also be instantiated via GeneralUtility::makeInstance() (e.g. from Extbase inject methods) without DI wiring.

Testing 

Unit tests cover SiteConfigurationService (both the TYPO3 13/14 and TYPO3 12 branches) and RekaiScriptMiddleware:

vendor/bin/phpunit --configuration vendor/pluswerk/rekai/phpunit.xml

No script in the frontend head 

• Verify rekai.enabled is true in the site settings.
• Verify rekai.embedCode is a valid https:// URL. Leading or trailing whitespace is tolerated (the service trims it), but other invalid values silently disable injection.
• Flush all TYPO3 caches.
• On TYPO3 13/14: confirm the site has pluswerk/rekai listed under dependencies in config/sites/<id>/config.yaml.
• On TYPO3 12: confirm the values are written under settings.rekai in config/sites/<id>/config.yaml (the Site Settings editor does not exist on 12).

Recommendations remain empty in the browser 

The script is loaded and the rek-prediction containers are rendered, but they stay empty (or contain only an empty inner wrapper).

In almost all cases this is a rek.ai backend issue, not an extension bug. Check the following in order:

1. Allowed domains: the requesting hostname must be on the rek.ai Allowed-Domains list (rek.ai dashboard → settings). After adding a domain it can take up to 30 minutes for edge caches to refresh.
2. Visitor context: rek.ai personalisation needs either a configured Cold-Start fallback in the dashboard or some visitor history. The AI Simulator in the rek.ai dashboard can verify whether the backend has recommendations for a given filter combination.
3. Browser state: stale cookies or 304 responses can mask a fixed backend. Test in an incognito window with DevTools → Network → Disable cache enabled.
4. Language mismatch: allowedlangs (FlexForm) must overlap with the page language emitted as pl=… to the predict call. A site that only has en-US will not match an allowedlangs=de filter.

To produce a deterministic preview while diagnosing, set both rekai.advanced.testMode and rekai.advanced.useMockData to true — rek.ai then returns synthetic data regardless of indexing state.

Header not rendered 

The extension registers its content elements using TYPO3's standard content element API and the --palette--;;headers palette. Header rendering is handled by your site template's Default layout (from EXT:fluid_styled_content). If your sitepackage overrides lib.contentElement without including the standard layout root path (EXT:fluid_styled_content/Resources/Private/Layouts/), the header may not appear.

Autocomplete not working 

• Verify rekai.autocomplete.mode is set to auto or manual.
• Verify rekai.autocomplete.selector matches an input element that exists on the page.
• Confirm the rek.ai script is loaded successfully (no console errors).

TypoScript not loaded 

If the content elements render no output at all, the extension TypoScript may not be included in your site template. See Installation for how to add the Site Set dependency (TYPO3 13/14) or include the static template (TYPO3 12).

Content element not available in wizard 

Flush the TYPO3 backend cache after installation. If the problem persists, verify the extension is active under Admin Tools > Extensions.