Skip to main content

User identity

Objective

Understand why PuzzleMe needs a stable user identity (UID), how to pass one safely, and what to avoid.

Skip this if…

You use JavaScript embed and your site has no login system. The embed script already sets a first-party cookie so progress sticks in that browser. Come back here when you need cross-device progress or signed-in users.

Why user identity matters​

A stable id lets PuzzleMe recognize the same player on return visits. That unlocks:

BenefitWhat players / you get
Progress restorePartially completed puzzles and “already finished” status come back on revisit
Session mobilitySame signed-in account → same progress across browsers and devices
Reliable analyticsUnique users, plays, prints, and completions you can trust

Losing progress is one of the most common support complaints—identity is how you prevent it.

The problem​

PuzzleMe runs in an iframe on amuselabs.com. Cookies set from that iframe are third-party on your site.

Browsers increasingly block those cookies (Safari by default; Chrome and related engines have also restricted them). When the PuzzleMe cookie is blocked, the player looks new on every visit—even in the same browser.

Fix: Pass an opaque user id from your page (first party), so PuzzleMe does not rely on third-party cookies.

How PuzzleMe identifies a user​

Two approaches, in preferred order:

  1. uid from your page — Pass a hashed CRM / login / first-party cookie value into the embed (see below). Best for signed-in users and cross-device progress.
  2. First-party cookie via JS embed — If no uid is supplied, the embed script can create and reuse a first-party cookie. Good for anonymous same-browser progress; not enough for cross-device mobility on its own.
Pseudonymize UID

Always hash raw identifiers (for example SHA-256) before sending them so PuzzleMe never receives personally identifiable information (PII).

UID format​

RuleDetail
Allowed charactersA–Z, a–z, 0–9, and hyphen (-)
Max length64 characters
Invalid valuesAny other character → UID ignored

Pass a UID with JavaScript embed​

Option A: data-uid on the container (simplest)​

If you already know the anonymized id when the page renders, put it on the embed div:

<div class="pm-embed-div"
     data-set="demo-crossword"
     data-page="date-picker"
     data-height="700px"
     data-uid="abc123"></div>

The embed script reads data-uid at load time and applies it to the iframe.

Option B: PM_Config.getUID (programmatic)​

Use this method when the UID must be read at runtime, such as when the page has already authenticated user and the UID is present in the browser's cookie or it can be obtained from the runtime envirorment. The reference code with an example of reading the UID cookie and hashing it can be referenced from here:

Full setup → Step 4: User identity

Pass a UID with iframe embed​

Append uid to the iframe src before the first load—do not load once without it and reload with it later (see pitfalls below).

<iframe
  src="https://puzzleme.amuselabs.com/pmm/crossword?id=EXAMPLE&set=EXAMPLE&embed=1&uid=abc123"
  style="height: 700px; width: 100%;"
  title="PuzzleMe puzzle"></iframe>

Use the same hashed, format-valid value you would use for data-uid.

Rules and pitfalls​

Never invent a placeholder UID

If you cannot identify the user, omit uid / data-uid entirely. Do not pass empty string, 0, undefined, null, or similar stand-ins—those can merge unrelated players’ progress.

  • One user, one id. Cookie or login values used for the UID must be unique per person. A shared cookie merges puzzle state across users.
  • Prefer the login id for signed-in users. Hash your CRM / account id so progress syncs across browsers, apps, and devices. If multiple people share one login, they will share puzzle state too.
  • Load once with the final UID. Serving the iframe without uid, then appending it client-side and reloading, causes double loads, slower pages, and billing/usage noise. Wait until the UID is ready, then set src (or render data-uid) once.

Table of contents