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

Switcher.version

Engine version string

Switcher.init(selector?)

Re-run against the current DOM, optionally scoped

Switcher.initOne(rootEl)

Re-run a single wrapper

Switcher.region() / regionName() / countryName()

Resolved region code, region name, country name

Switcher.postalCode()

Resolved postal code, or "" if unknown/disabled

Switcher.postalCodeEnabled()

true once a postal code is available

Switcher.persona() / personaScores()

Active persona code; full score map

Switcher.setPersona(code[, opts])

Increment a persona score and re-render. opts: {weight}, {days}, {force:true}. setPersona('') clears

Switcher.interest() / interestScores() / setInterest()

Active interests (array), scores, setter

Switcher.topic() / topicScores() / setTopic()

Active topics (array), scores, setter

Switcher.consent()

true if the engine is currently allowed to write cookies

Switcher.setConsent(value)

Sets consent from your own cookie banner. false clears all behavioral cookies; null hands control back to the automatic checks

Switcher.forgetMe()

Clears all persona, interest and topic cookies and re-renders

Switcher.cookies()

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 [data-variant][hidden]{display:none!important;}

Wrong variant shows

A typo in data-codes

First variant shows on no match

No fallback marked. Add data-default, or one data-codes="DEFAULT"

Postal switcher always shows fallback

Postal code not enabled for the site, or couldn't be resolved. Confirm with Switcher.postalCodeEnabled()

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 Switcher.version: postal needs 1.8.0 or later, geo groups need 1.9.0, and set-p/set-i/set-t need 1.10.0

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

!FR only takes that variant out of consideration for French visitors. Pair it with a variant that positively targets FR, or nobody wins for them

Scores reset when the browser closes

No t4-persona-expires (or interest/topic equivalent) meta tag, so the cookies are session cookies

Scores never stick

Consent isn't granted. Check Switcher.consent()

Persona, interest or topic never activates

The top score is below the threshold. Compare Switcher.personaScores() with your t4-*-threshold meta tag

Combined variant never shows

An empty attribute such as data-persona="". Only output attributes that have a value

A code is ignored

Codes can only contain letters, numbers, _ or -, up to 32 characters

Content added after page load isn't personalized

Call Switcher.init() after adding it

Buttons or links added after page load don't record scores

Triggers are only set up when the page first loads, and Switcher.init() doesn't pick up new ones. Call Switcher.setPersona(), setInterest() or setTopic() from your own click handler instead

Postal code variant shows in the wrong country

Postal codes aren't tied to a country. Pair them with data-geo in a combined switcher

Back to top