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

TLDR

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>
<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>
<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 || []
</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

Send events to the GamesHub by pushing messages to the window.gamesHubEvents object. Native apps can use this same logic by injecting the below javascript code into the webview.

// Required call - gameshub does not start without a userId. 
// Pass null for anonymous users, they will receive a device-specific userid.
window.gamesHubEvents.push({ name: 'setUserId', data: 'USERID' | null })

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

// Optional. Defaults to `web`
window.gamesHubEvents.push({ name: 'setPlatform', data: 'ios' | 'android' | 'web' })

// Optional. Defaults to the language configured for the customer (nrc = NL, independent = EN, etc.)
window.gamesHubEvents.push({ name: 'setLanguage', data: 'nl' | 'en' | 'de' })

// Optional. Name of the brand, so GamesHub can distinguish for different clients
window.gamesHubEvents.push({ name: 'setTitle', data: 'nrc' | 'telegraaf' | 'standaard' | ... })

// 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
window.gamesHubEvents.push({ name: 'setUserSubscription', data: 'SUBSCRIPTIONNAME' | null })

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 } = JSON.parse(event.data)
})

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

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

Events

Message Description Data
initialized Sent when the GamesHub has finished initializing None
visitUrl Sent when the user clicks a link that should be handled by the parent { url: string, target: '_self' \| '_blank' }
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 }[]
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>