What to change
Mark complete() obsolete in the client script and move page code, examples
and documentation to onChange(). Keep complete() working, because pages
in the wild use it, and remove it only in a major release.
Why
complete(fn) answers a question that stopped having one answer when the
script gained refresh().
Read at commit f47917c of this repository, on branch
feature/create-last-a (#23):
complete(fn) (line 1364) calls fn at once when completed or failed
is already true. Otherwise it registers a wrapper through onChange
(line 1389) that calls fn when the round ends.
refresh() (line 1400) sets completed and failed back to false and
runs another round, which happens when the visitor's answer arrives or
changes.
loadParsedJSON (line 982) sets completed true and fires every
changeFuncs handler at the end of every round.
So a handler registered before the first round ends stays in changeFuncs
and fires again at the end of every later round, whilst one registered after
that fires once, immediately, and never again. Which of the two a page gets
depends on when its code ran, which a page author cannot control on a slow
network.
The result that matters: on the ordinary path the visitor answers after the
first round has ended, so the 51Did exists only in a later round. A handler
registered late, which is what a documentation example does, is called with
a payload that carries no 51Did.
onChange(fn) has none of this. It fires on every payload, including one
that arrives after a refresh, and it catches a handler up when the page view
was served from the session storage cache (line 1351).
What this needs
- A note in this repository's README and in the rendered script's own
documentation saying complete() is obsolete and what to use instead.
- The same in each pipeline language's documentation, because the script is
rendered by every one of them.
- Examples and demonstrations move to
onChange, checking the value is
present before using it. The 51Degrees developer documentation is being
changed to do that now
(documentation#238).
- A decision on whether
complete() should fire once per page view until
it is removed, which is what it did before refresh() existed.
Raised on James Rosewell's decision of 15 September 2026, during the create
last review, which is tracked internally.
What to change
Mark
complete()obsolete in the client script and move page code, examplesand documentation to
onChange(). Keepcomplete()working, because pagesin the wild use it, and remove it only in a major release.
Why
complete(fn)answers a question that stopped having one answer when thescript gained
refresh().Read at commit
f47917cof this repository, on branchfeature/create-last-a(#23):complete(fn)(line 1364) callsfnat once whencompletedorfailedis already true. Otherwise it registers a wrapper through
onChange(line 1389) that calls
fnwhen the round ends.refresh()(line 1400) setscompletedandfailedback to false andruns another round, which happens when the visitor's answer arrives or
changes.
loadParsedJSON(line 982) setscompletedtrue and fires everychangeFuncshandler at the end of every round.So a handler registered before the first round ends stays in
changeFuncsand fires again at the end of every later round, whilst one registered after
that fires once, immediately, and never again. Which of the two a page gets
depends on when its code ran, which a page author cannot control on a slow
network.
The result that matters: on the ordinary path the visitor answers after the
first round has ended, so the 51Did exists only in a later round. A handler
registered late, which is what a documentation example does, is called with
a payload that carries no 51Did.
onChange(fn)has none of this. It fires on every payload, including onethat arrives after a refresh, and it catches a handler up when the page view
was served from the session storage cache (line 1351).
What this needs
documentation saying
complete()is obsolete and what to use instead.rendered by every one of them.
onChange, checking the value ispresent before using it. The 51Degrees developer documentation is being
changed to do that now
(documentation#238).
complete()should fire once per page view untilit is removed, which is what it did before
refresh()existed.Raised on James Rosewell's decision of 15 September 2026, during the create
last review, which is tracked internally.