Testing, API Reference & Troubleshooting the Personalization Engine
- Last Modified:
- 16 Nov 2026
- User Level:
- Administrator
Now that you've got the Personalization Engine set up, this guide gives you everything you need to know in order to test that it's working and troubleshoot any issues you may encounter.
Overrides for QA and stakeholder previews
Every dimension accepts a querystring override, and it always wins over whatever the engine would normally resolve. It only lasts for that one page load, though: it never touches a stored cookie, so reloading the page without the parameter puts things back to normal.
The set-* parameters are the one exception to that. Instead of just changing what's shown for one load, they write the score into the cookie, so the change sticks around after the page reloads.
| Override | Forces |
|---|---|
?geo=IE |
Country. The region is left empty, and postal code is only available from a ?postalcode override, while this is in use. |
?postalcode=10001 (or ?zip=10001) |
Postal code (and turns on postal-code resolution for the test) |
?persona=UG |
Persona |
?interest=CS or ?topic=OPENDAY |
Interest / topic (single value) |
?set-p=UG:5 or ?set-i=AI:2 or ?set-t=APPLYING:3 |
Writes a lasting score to the cookie, unlike the others above, which are just for that one page load. Clear your cookies to undo it while testing |
You can combine overrides too. ?persona=PG&geo=US shows exactly what a US postgraduate prospect would see. These links are safe to share freely with stakeholders for preview: nothing changes permanently, and the override expires the moment the page reloads without it (the set-* parameters are still the exception).
A page meta tag works too, which is useful for non-Cloud environments or local testing where there are no location headers for the engine to read: <meta name="t4-viewer-postal-code" content="10001"> or <meta name="t4-viewer-country" content="IE">.
Browser console checks
// Engine version: postal needs 1.8+, geo groups and negation need 1.9+
window.Switcher.version;
// Which variant is shown?
document.querySelector('[data-switcher]').getAttribute('data-active');
// Count the fallbacks in each wrapper (each should show 1)
document.querySelectorAll('[data-switcher]').forEach(w =>
console.log(w, w.querySelectorAll('[data-default], [data-codes*="DEFAULT" i]').length));
// Resolved viewer attributes
window.SW_IDENTIFIER; // country, e.g. "IE"
window.SW_REGION; // region, e.g. "L"
window.SW_POSTAL_CODE; // "10001", or "" if unknown/disabled
window.Switcher.postalCodeEnabled(); // boolean
// Force values without changing the URL, then re-run
window.SW_IDENTIFIER = 'IE'; window.SW_REGION = 'L';
window.Switcher.init();
JavaScript API
| Method / property | Returns / effect |
|---|---|
|
|
Engine version string |
|
|
Re-run against the current DOM, optionally scoped |
|
|
Re-run a single wrapper |
|
|
Resolved region code, region name, country name |
|
|
Resolved postal code, or |
|
|
|
|
|
Active persona code; full score map |
|
|
Increment a persona score and re-render. |
|
|
Active interests (array), scores, setter |
|
|
Active topics (array), scores, setter |
|
|
|
|
|
Sets consent from your own cookie banner. |
|
|
Clears all persona, interest and topic cookies and re-renders |
|
|
Lists the cookies the engine uses, with their purpose and expiry in days (0 = session), e.g. for your cookie policy |
Globals mirror the API: SW_IDENTIFIER, SW_REGION, SW_COUNTRY_NAME, SW_REGION_NAME, SW_POSTAL_CODE, SW_POSTAL_CODE_ENABLED, SW_PERSONA, SW_INTEREST (array), SW_TOPIC (array).
Screen reader announcements
When a variant changes after the page has loaded (for example, after a trigger click), the engine announces "Page content updated" to screen readers. To change the message, add data-announce to the variant or wrapper, or set it site-wide with <meta name="t4-announce-text" content="…">. To turn announcements off, add <meta name="t4-announce" content="off">.
Troubleshooting
| Symptom | Likely cause |
|---|---|
|
All blocks flash then collapse |
Missing CSS |
|
Wrong variant shows |
A typo in |
|
First variant shows on no match |
No fallback marked. Add |
|
Postal switcher always shows fallback |
Postal code not enabled for the site, or couldn't be resolved. Confirm with |
|
Region empty, country works |
Region resolution isn't enabled for the site. Ask your Terminalfour contact to turn it on |
|
Geo / postal not working at all |
Edge personalization requires Terminalfour Cloud |
|
Engine never runs (GTM) |
The tag fires on Page View. Switch it to the DOM Ready trigger instead |
|
Postal / geo-group / set-p features missing |
The engine is older than what you need. Check |
|
Group token never matches |
Engine older than 1.9.0, or a typo in the meta tag name |
|
Excluded visitor sees the fallback, not their own variant |
|
|
Scores reset when the browser closes |
No |
|
Scores never stick |
Consent isn't granted. Check |
|
Persona, interest or topic never activates |
The top score is below the threshold. Compare |
|
Combined variant never shows |
An empty attribute such as |
|
A code is ignored |
Codes can only contain letters, numbers, |
|
Content added after page load isn't personalized |
Call |
|
Buttons or links added after page load don't record scores |
Triggers are only set up when the page first loads, and |
|
Postal code variant shows in the wrong country |
Postal codes aren't tied to a country. Pair them with |