Skip to content

Mark complete() obsolete and move page code to onChange #25

Description

@jwrosewell

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

  1. A note in this repository's README and in the rendered script's own
    documentation saying complete() is obsolete and what to use instead.
  2. The same in each pipeline language's documentation, because the script is
    rendered by every one of them.
  3. 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).
  4. 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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    type: cleanupTidying that changes no behaviour

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions