Q42 Puzzles & Games Hub on web

This README provides instructions on how to use the custom web components that are available in the Games Hub in your web application.

Separate pages.

First, you need a VERSION and a list of SLOT_IDs from us.

In your CMS, create an overview page. Populate it with:

<script src="https://cdn.42puzzles.com/hub/VERSION/games-hub.js" type="module"></script>
<script> ... (see below) </script>
<games-hub-overview></games-hub-overview>

Then, in your CMS, create a page for each puzzle. Populate it with:

<script src="https://cdn.42puzzles.com/hub/VERSION/games-hub.js" type="module"></script>
<script> ... (see below) </script>
<games-hub-player slot="SLOT_ID"></games-hub-player>

To make the links from the overview to the puzzle detail pages word, mail/slack us the URL’s of the puzzle detail pages.

Below are extra options you can use to customize and personalize the experience.

Integration

Include the Script

To use these custom elements, you need to include the following script in your HTML file. This script is responsible for lazy loading the necessary custom elements by scanning the DOM for their presence:

<script src="https://cdn.42puzzles.com/hub/VERSION/games-hub.js" type="module"></script>
<script>
  window.gamesHubEvents = window.gamesHubEvents || []
  window.gamesHubEvents.push({ 
    name: 'initialize', 
    data: {
      // Required call - gameshub does not start without a userId
      // Pass null for anonymous users, they will receive a device-specific userid
      userId: 'USERID' | null

      // Required.
      platform: 'ios' | 'android' | 'web'

      // Required. Name of the organisation
      organisation: 'nrc' | 'mediahuis'

      // Required. Brand code within an organisation
      brand: 'tel' | 'ds' | 'indo' | ...

      // Optional. In the future we want to be able to disable features based on the subscription of a user
      // for instance, digital-only users cannot access the printed puzzles
      // A user can have multiple subscriptions, for instance 'premium' and 'digital'
      userSubscription: 'SUBNAME' | ['SUBNAME1', 'SUBNAME2'] | null

      // Optional. A/B testing version with support for multiple tests simultaneously
      // for instance, { streak: 'with', history: 'without' }
      abVersion: { 'TESTNAME': 'VERSION', ... }

      // Optional. Defaults to `default` which follows the system theme
      theme: 'darkMode' | 'lightMode' | 'default'

      // Optional. Defaults to `false` which doesn't output logging to console
      debug: true | false
    }
  })
</script>

How It Works

The script automatically scans the DOM for instances of the custom elements that are available in the Games Hub. When it detects these elements, it lazy loads the required components, ensuring that only the necessary resources are loaded.

Sending events

Next to the required initialize({...}) call, there are the following optional calls:

// Optional. Defaults to `default` which follows the system theme
window.gamesHubEvents.push({ name: 'setTheme', data: 'darkMode' | 'lightMode' | 'default' })

// Optional. Increases output logging via console.log
window.gamesHubEvents.push({ name: 'setDebug', data: true | false })

Receiving events

The GamesHub sends events to javascript or to the window parent when the GamesHub is loaded via a native app.

For javascript (setPlatform === web), you can subscribe to events like this:

window.addEventListener('gamesHubEvent', (event) => {
  const { type, data, metadata } = event.detail
})

For native apps (setPlatform !== web), you can subscribe to postMessage events that the webview emits. Pseudo code:

WEBVIEW.addEventListener('message', (event) => {
  const { type, data, metadata } = JSON.parse(event.detail)
})

The typing of event.detail is as follows:

{
  // timestamp this event was emitted
  timestamp: number
  // see below for possible options
  type: PlayerExternalEvent
  // see below for typing of Data per PlayerExternalEvent
  data?: Data
  timer?: {
    // time that has progressed since start of the game, excluding when it was paused. In milliseconds.
    ms: number
  }
  metadata: {
    // unique identifier for this puzzle.
    puzzleId?: string
    // date this puzzle was published. Usually today but can also be a historical puzzle. yyyy-MM-dd
    puzzleDate?: string
    // type of puzzle: wordle | headline | sudoku | etc...
    gameType?: string
    // name of this puzzle: Vorto | Precies Vier | Sudoku | etc...
    gameName?: string
    // ID of this puzzle
    gameId?: string
    // ID of the user. If anonymous user, we generate one and keep it in localStorage.
    // If it's an authenticated user, the userId is prefixed with `client-`
    userId?: string
  }
}

Where PlayerExternalEvent is one of:

Message	Description	Data
`ready`	Sent when the GamesHub is ready to receive the `initialize(...)` call	None
`initialized`	Sent when the GamesHub has finished initializing	None
`started`	Sent when the user starts playing a game	`{ ms: number }` - Current playtime in milliseconds
`paused`	Sent when the user pauses a game	`{ ms: number }` - Current playtime in milliseconds
`completed`	Sent when the user completes a game	`{ unit: 'solution' \\| 'rank' \\| 'points' \\| 'attempts' \\| 'milliseconds', value: string \\| number }[]`
`visitUrl`	Sent when the user clicks a link that should be handled by the parent	`{ url: string, target: '_self' \\| '_blank' }`
`share`	Sent when the user triggers the share functionality	`{ text: string }` - Text to be shared

games-hub-overview

The games-hub-overview element provides a grid view of available games. It displays a list of games, allowing users to browse and select games to play.

Example Usage

<games-hub-overview></games-hub-overview>

games-hub-player

The games-hub-player element provides a player for a single game.

Attributes

slot: (Required) A string representing the unique identifier of the game slot to be displayed.
date: (Optional) A string representing the date of the game slot in YYYY-MM-DD format. Defaults to the current date.

Example Usage

<games-hub-player slot="12345" date="2023-10-01"></games-hub-player>

games-hub-history

The games-hub-history element provides a list of past instances of a game. The user can select a past instance to play again.

Attributes

slot: (Required) A string representing the unique identifier of the game slot.
date: (Optional) A string representing the date of the game slot in YYYY-MM-DD format. Defaults to the current date.

Example Usage

<games-hub-history slot="12345" date="2023-10-01"></games-hub-history>