Skip to main content

User identity

note

If you are using our JavaScript embed code, AND you do not have a login system implemented on your website/app, then our JavaScript takes care of robustly identifying users. You can skip this section.

The problem​

There are two ways that PuzzleMe can identify a user:

  • Using an optional uid parameter passed to the PuzzleMe iframe
  • If the uid parameter is not present, by placing a cookie to recognize the user across different sessions.

Browsers such as Safari, Chrome, and Brave have been tightening their security policies recently to disallow a third party iframe from setting a cookie on the user’s computer. The Safari browser now disallows such cookies by default on both Mac OS X and iOS unless the user turns on the “enable Cross Site Tracking” option. Google Chrome is planning to completely phase out third party cookies in the second half of 2024, which will also affect other browsers which use the same engine, such as Brave and Microsoft Edge.

Since the PuzzleMe iframe comes from an amuselabs.com domain, any cookie set by PuzzleMe is considered a third party cookie. Therefore, the PuzzleMe cookie is not saved in between visits by the same user to the container page of the puzzle.

Background information

It is highly desirable that PuzzleMe be able to identify a returning user when they revisit a games picker or even a specific game. There are 3 primary reasons for this.

  1. The first is that it allows the PuzzleMe backend to restore the state of a partially completed game, and to show the user which games they have completed. The lack of ability to save puzzles (or losing the state of a partially solved puzzle) is one of the biggest sources of complaints to technical support.
  2. The second benefit is that it allows session mobility; if a user is signed in with the same account, then their game state can travel across devices.
  3. A third benefit is that proper user identity enables you to generate better analytics from the PuzzleMe backend to understand user behavior. For example, you can analyze how many unique users are engaging with the puzzles, how many puzzles they play or print every month, how many they complete, etc.

The solution​

If the user is signed in, the host page would identify the user using whatever CRM identifier is available. The container page could then pass the PuzzleMe iframe an opaque identifier that is a hash of this CRM identity via the uid parameter. If the user is not signed in, the uid parameter can be set to a hash of any of your first-party cookie. Note that the uid parameter can only have the characters A-Z, a-z, 0-9, a hyphen (“-”) and can be no more than 64 characters long. If there are any other characters present, the UID will be considered invalid and will be ignored.

Of course, it should be ensured that the uid parameter does not contain any personally identifiable information. This can be achieved by using a strong and irreversible function (such as SHA-256) to hash the identifier before passing it to the iframe.

JavaScript embeds​

If you are using our JavaScript embed code, the quickest way is to add the uid as an HTML attribute in the embed code for the puzzle. The name of the attribute is data-uid , and its value is the anonymized identifier for the logged in user. This attribute is a part of the div with class pm-embed-div .

For example, say you are embedding a crossword picker, and the anonymized identifier for the user is abc123. Here is the div in your embed code, without any identifier. 

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

To automatically pass the uid, you need to add the data-uid attribute to this div, with the value of abc123. Here is how it would look like (the data-uid attribute in italics): 

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

If the data-uid attribute and the identifier is present in the embed code when the page loads, our JavaScript will read this value and automatically use it while loading the iframe.

Non JavaScript embeds​

If you are not using our JavaScript embeds, please refer to our custom integration section for more details.

Points to remember​

  • If you use cookies to set the opaque identifier for a user, please ensure that the cookie is unique to the specific user. If the cookie is shared by two or more users, it could result in the puzzle state being erroneously shared across different users.
danger

If you are unable to uniquely identify the user for any reason (not signed in/no permission to set cookies), please do not pass the uid parameter at all. Please do not use empty strings, 0, 'undefined', 'null' or similar other identifiers for the uid.

  • For signed in users, whenever possible, please use the sign in identifier as the basis for the uid. This will ensure that the puzzle status is synchronized across different browsers, mobile apps and other devices where the user has signed in. A special case to be aware of is if your site uses a login system, and different users share the same login credentials, then they will see the same state of the puzzle.
  • Please ensure that the first load of the puzzle iframe occurs with the appropriate UID added. A common pitfall that occurs is when website serve the iframe embed code without uid appended, and use JavaScript on the client side to append the uid and reload the iframe. This can cause double loads, slows down the page and causes issues with accurate billing.