iFrame messaging

Objective

Learn how the PuzzleMe™ iframe and your page communicate in both directions via postMessage

Illustration

Event Dispatches

Overview

Communication between the PuzzleMe iframe and the parent page uses the window.postMessage() API in both directions.

Iframe → parent — The iframe sends messages when events occur (e.g. puzzle loaded, puzzle completed). You can use these to:

Update your page with puzzle metadata (e.g. title, author)
Resize the iframe to fit the puzzle
Track analytics and correlate behavior with the rest of your site

Parent → iframe — The parent sends messages to control the player (e.g. switch light/dark mode). The iframe listens and applies the change without reloading.

Iframe to parent page communication

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",
  "pageSrc": "puzzleme-picker",
  "type": "PICKER_LOADED"
}

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",
  "pageSrc": "puzzleme-picker",
  "type": "PICKER_SHOWN",
  "frameHeight": 836
}

On puzzle click

When any puzzle inside the picker is clicked, the following message is sent. The message includes the selected puzzle id. This can be used to trigger actions (such as playing a video ad) after a puzzle is selected in the picker, but before the puzzle gets loaded.

{
  "src": "picker",
  "message": "Puzzle selected",
  "pageSrc": "puzzleme-picker",
  "id": "daily-crossword_20230131",
  "type": "PUZZLE_SELECTED"
}

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,
    "type": "PUZZLE_LOAD",
    "date": 1760503380000,
    "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.

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",
    "type": "PUZZLE_SIZE_CHANGE",
    "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.

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",
    "completedCorrectly": true,
    "timeTaken": 8,
    "type": "PUZZLE_COMPLETE",
    "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 if completed correctly.

On puzzle progress

This message is only sent for Word Flower puzzles when a player finds a valid word. It tells you if the word uses all the letters (pangram) and how many words the player has found so far.

{
    
  "id": "ebba4950",
  "series": "daily-wordflower",
  "puzzleType": "wordf",
  "pageSrc": "puzzleme-player",
  "type": "PUZZLE_PROGRESS",
  "date": 1760328600000,
  "title": "Word Flower",
  "author": "Amuse Labs",
  "authorURL": "",
  "copyright": "",
  "attributions": "",
  "puzzle_instructions": null,
  "tn_url": "",
  "progress": "puzzleInProgress",
  "wordsFound": 1,
  "isPangram": false,
  "totalWords": 11

}

Posted as soon as a social play session is created. This event is sent when a user clicks the social play icon to start a session. Note that the invitee might never join, so this event indicates that social play mode has been activated, not that both users are connected.

{
  "id": "3bb3e06a",
  "series": "daily-crossword",
  "puzzleType": "crossword",
  "src": "crossword",
  "width": 8,
  "height": 8,
  "type": "SOCIAL_PLAY_START",
  "date": 1760503380000,
  "title": "Crossword",
  "author": "Amuse Labs",
  "authorURL": "",
  "copyright": "",
  "attributions": "",
  "puzzle_instructions": null,
  "tn_url": "",
  "playId": "0cbe00b24ae98883e150262d0dada8f6ae0e8440a5baea956779677e6aef04a1"
}

Use cases

Detect when a user is solving a puzzle in social play mode
Track social play sessions for analytics
Customize the parent page experience for social play sessions

You can identify when a user is in social play mode using the following methods:

Method	Description	When Available
URL parameter `playId`	When a user enters via a Social Play link, the URL contains a `playId` parameter that identifies the social play session	On page load (if user arrived via Social Play link)
`SOCIAL_PLAY_START` postMessage	The `playId` is included in the `SOCIAL_PLAY_START` event payload	As soon as a social play session is created (when user clicks the social play icon)

Posted when the user dismisses the completion modal.

{
  "id": "3bb3e06a",
  "series": "daily-crossword",
  "puzzleType": "crossword",
  "src": "crossword",
  "width": 8,
  "height": 8,
  "type": "PUZZLE_COMPLETION_MODAL_DISMISSED",
  "date": 1760503380000,
  "title": "Crossword",
  "author": "Amuse Labs",
  "authorURL": "",
  "copyright": "",
  "attributions": "",
  "puzzle_instructions": null,
  "tn_url": "",
  "progress": "modalClosed"
}

On contest submit

Triggered when a user submits a puzzle in contest mode. This event is fired only on successful submissions, not on failed attempts.

{
    
  "id": "tca251005",
  "series": "daily-crossword",
  "puzzleType": "crossword",
  "src": "crossword",
  "width": 21,
  "height": 21,
  "type": "CONTEST_SUBMIT",
  "date": 1759602600000,
  "title": "Crossword Contest",
  "author": "Amuse Labs",
  "authorURL": "",
  "copyright": "© 2025 Tribune Content Agency, LLC",
  "attributions": "",
  "puzzle_instructions": null,
  "tn_url": "",
  "progress": "contestSubmitted"

}

Parent page to iframe communication

The parent page can send messages to the embedded PuzzleMe iframe to control the player. The iframe listens for these messages and responds without reloading.

Switching light/dark mode

Send a JSON message to the iframe with type set to "updateDarkMode" and darkMode set to true (dark) or false (light):

{
    "type": "updateDarkMode",
    "darkMode": true   // true = dark mode, false = light mode
}

From your page, call postMessage on the iframe’s contentWindow:

function setPlayerDarkMode(iframeElement, enableDarkMode) {
    if (iframeElement && iframeElement.contentWindow) {
        iframeElement.contentWindow.postMessage(
            { type: 'updateDarkMode', darkMode: enableDarkMode },
            '*'
        );
    }
}

// Example: switch to dark mode
setPlayerDarkMode(document.getElementById('puzzle'), true);

Manual test (browser console)

If you already have a puzzle embedded, you can test the behavior by running this in your browser console:

// Enable dark mode
document.getElementById('your_puzzle_iframe_ID').contentWindow.postMessage(
  { type: 'updateDarkMode', darkMode: true },
  '*'
);

// Enable light mode
document.getElementById('your_puzzle_iframe_ID').contentWindow.postMessage(
  { type: 'updateDarkMode', darkMode: false },
  '*'
);

note

Dark mode syncing via postMessage must be enabled for your series. Contact us to enable it.

Illustration​

Event Dispatches

Overview​

Iframe to parent page communication​

Picker page post messages​

On picker load​

On picker display​

On puzzle click​

Puzzle page post messages​

On puzzle load​

On puzzle display and resize​

On puzzle click​

On puzzle completion​

On puzzle progress​

On social play start​

Detecting social play mode​

On completion modal dismiss​

On contest submit​

Parent page to iframe communication​

Switching light/dark mode​

Manual test (browser console)​

Illustration

Overview

Iframe to parent page communication

Picker page post messages

On picker load

On picker display

On puzzle click

Puzzle page post messages

On puzzle load

On puzzle display and resize

On puzzle click

On puzzle completion

On puzzle progress

On social play start

Detecting social play mode

On completion modal dismiss

On contest submit

Parent page to iframe communication

Switching light/dark mode

Manual test (browser console)