Skip to main content

iFrame messaging

Objective

Learn what information the PuzzleMe iframe can communicate to your page

Illustration​

Event Dispatches

Overview​

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 events that are occurring inside the iFrame. There are three typical uses for these messages:

  1. The parent page can process these messages and use them to update content on the container page such as the puzzle title, and author.
  2. The parent page can dynamically resize the iframe based on the optimal height and width required for a specific puzzle to ensure a snug fit.
  3. The parent page can use these events to maintain analytics in its own data lake, and correlate user behavior inside the iframe with other user activity on the site.

For further information on window.postMessage() API, please refer to the MDN documentation.

Picker page post messages​

On Picker Load​

When the puzzle picker is loaded, the following message is sent. This event can be used as a trigger to set up a page for displaying the picker.

{
    "src": "picker",
    "message": "Picker shown"
}

On Picker Display​

When the puzzles in the picker are fully displayed, the following message is sent. It contains the height of the iFrame. This can be used to set the iFrame height to display the entire list of puzzles on the screen without having an iFrame scroll.

{
    "src": "picker",
    "message": "Picker shown",
    "frameHeight": 741
}

Puzzle page post messages​

On Puzzle Load​

When a puzzle is loaded, the following message is sent. It contains detailed metadata about the puzzle. This event can be used to update the puzzle information on the parent page.

{
    "src": "crossword",
    "id": "amuselabs-expert_20210503_0300",
    "series": "daily-crossword-expert",
    "puzzleType": "crossword",
    "width": 15,
    "height": 15,
    "title": "Daily Crossword",
    "author": "Amuse Labs",
    "authorURL": "",
    "tn_url": "",
    "copyright": "© Amuse Labs 2022",
    "attributions": "",
    "puzzle_instructions": "",
    "progress": "puzzleLoaded"
}

Use cases

  • Display the title, author name or other metadata outside the iframe on your puzzle page. For example, check Washington Post's implementation of the sunday crossword, where the title of each puzzle is displayed above the iframe.

On Puzzle Display and Resize​

When the puzzle is completely rendered on the screen, its height and width in pixels is posted to the parent page. This message is posted every time the puzzle is resized. 

{
    "src": "crossword",
    "id": "daily-crossword_20230131_0300",
    "series": "daily-crossword",
    "puzzleType": "crossword",
    "frameHeight": 702,
    "frameWidth": 1207
}

Use cases

  • Adjust the iframe height and width
  • Change layout of the parent page. For example, repositioning a sidebar if the puzzle requires more width than the original iframe width. For example, check Washington Post's implementation of the daily crossword, where the sidebar is visible for weekday puzzles, but is dropped when the larger Sunday puzzle is opened.

On Puzzle Click​

When the user clicks or taps on any part of the puzzle, the parent page should scroll to bring the entire puzzle in view, so that the user does not have to scroll the page manually. This is especially useful for mobile users. The iframe issues a message to snap the puzzle frame into the best scroll position at first interaction. In this position, the entire puzzle is in view. 

{
  "src": "crossword",
  "id": "daily-crossword_20230131_0300",
  "series": "daily-crossword",
  "puzzleType": "crossword",
  "type": "event",
  "gridOffset": 0
}

On Puzzle Completion​

When a puzzle has been fully solved, the following message is sent. This message contains information such as score and time taken to solve the puzzle. 

{
    "src": "crossword",
    "id": "amuselabs-expert_20210503_0300",
    "series": "daily-crossword-expert",
    "puzzleType": "crossword",
    "progress": "puzzleCompleted",
    "timeTaken": 8,
    "score": 0
}

Use cases

  • Log score, time taken and completion to your own data lake
  • Trigger events linked to puzzle completion on your page, such as opening a form, adding a survey link, or displaying a congratulatory message