Skip to main content

JS Embed

Overview​

PuzzleMe provides a readily available JavaScript that can be inserted directly into the CMS or the webpage. The JavaScript runs on the puzzle page and inserts an iframe to render the puzzle passing the required information to the iframe. The integration effort is minimal with this approach and the features mentioned will work out of the box.

  • Social share: Shared links from the puzzle on social media will work as the embed script configures the iframe with the correct URL.
  • Seamless multiplayer mode: The link based invite will work as the embed script will pass the information required to connect the two plays to the iframe.
  • Session stickiness: The embed script creates a first-party cookie, hence the sessions will remain sticky within the browser.
note

Session mobility will not work out of the box, as the user identity will not persist across devices unless the parent page adds a custom handler for passing the logged in user identity to PuzzleMe Embed JavaScript (described below).

This guide covers the following topics:

  1. Steps to embed PuzzleMe JavaScript into a webpage
  2. Integration of identity of the user (UID)
  3. Social share and multiplayer setup
  4. iframe communication with the parent page

Steps to embed PuzzleMe JavaScript​

PuzzleMe JavaScript embed has three components.

  1. The JavaScript to be added to the header A sample JavaScript to be included in the HTML headers is shown below. The crypto-js is required only if you are using the hash() function for masking the UID that’s passed to PuzzleMe via iframe URL parameter (explained later)
<!-- Include the CryptoJS library for hashing the user id before sending it to the PuzzleMe server. -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.1.1/crypto-js.min.js"></script>
<!-- Include the javascript library for embedding this puzzle. -->
<script id="pm-script" src="https://puzzleme.amuselabs.com/pmm/js/puzzleme-embed.js"></script>
  1. The base link of the Amuse Labs PuzzleMe service, please note you’ll get the exact link (all components) from the Dashboard.
<!-- Specify the Amuse Labs server name from where the puzzles will be served -–>
<script> PM_Config.PM_BasePath = "https://puzzleme.amuselabs.com/pmm/"; </script>
  1. The skeleton HTML to embed in the iframe for the picker
<!-- Following line embeds the picker on your page. If you want to render multiple pickers on your page then you can copy paste it multiple times. -->
<div class="pm-embed-div" data-set="demo-crossword" data-page="date-picker" data-height="700px"></div>
  1. The skeleton HTML to embed in the iframe for a puzzle
<div class="pm-embed-div" data-id="a7b2b0e0" data-set="demo-crossword" data-puzzleType="crossword" data-height="700px" data-mobieMargin="10px"></div>

Where:

  • data-id: puzzle id
  • data-set: series name of this puzzle
  • data-puzzletype: type of this puzzle, eg: crossword, sudoku, wordsearch etc.
  • data-heigth : height on desktop and tablet browsers (default 700px)
  • data-mobileMargin : height of the sticky headers/footers on the parent page

User identification​

To allow a user to restore a game’s state across different browsers or devices the PuzzleMe integration should be able to uniquely identify a user. The PuzzleMe Embed JavaScript has a function PM_Config.getUID that generates a random UID, and creates a one-way hash and sets the hash in a cookie. You can customize this function as per your website’s UID policy by assigning a specific function to the PM_Config.getUID field. The assigned function should be responsible for retrieving and returning a user identifier that is unique to the current user.

Any implementation of PM_Config.getUID method should return an identifier used to identify the user, such as a CRM ID, a cookie value or an email address. We recommend using an appropriate one-way hash function (such as SHA 256) to hash the identifier, before returning it as UID. The hash ensures that Amuse Labs does not receive any personally identifiable information (PII) from the website. The hash value should also not be easily guessable in order to ensure that players cannot look into another players’ state.

Social share and multiplayer integration​

Major browsers such as Safari, Chrome, and Firefox have been tightening their security policies recently. These security updates disallow a third party iframe (such as your PuzzleMe iframe) from reading the complete URL of the host page where the iframe is embedded. PuzzleMe needs the host page URL when users share a game on social media from within the iframe, or invite friends to join them in a game. It also needs this URL to open a deep link to a game. A deep link is a link that bypasses the games picker and directly opens a specific game.

To fix this problem, the host page needs to provide the URL of the page to the PuzzleMe iframe, along with the deep link parameters (which are typically a puzzle id to identify a specific puzzle, or a play id for an invitee to join a specific session). This is handled by the PuzzleMe embed JavaScript.

Iframe communication​

The PuzzleMe iFrame can communicate with the parent (container) page where it is embedded, via the window.postMessage() JavaScript API. The iFrame sends these messages to inform the parent page of various events occurring inside the iFrame. PuzzleMe embed JavaScript handles the events below out of the box.

  • Dynamically resizes the iframe based on the optimal height and width required for the picker or a puzzle to ensure a snug fit.
  • When the user clicks on any element of the game, the page is scrolled to bring the iframe into view.

There are other events that can be used for further customization and tracking of puzzle progress. The PuzzleMe embed JavaScript provides hooks for them. If you are interested in handling these events, please contact our Product Support team for further assistance.