Developer features

When activated via the Premium > Developer > Send completion signal when embedded setting, you can listen for the completion signal on your own website and handle it accordingly:

window.addEventListener('message', console.log)

You'll see that the event message contains a data property which contains the following payload:

{
    puzzleKey: string,
    completed: boolean
}

Whenever a puzzle is completed, it will send true and whenever the puzzle is reset while completed before, it will send false

Now that you know what the payload looks like, change the console.log to any function you like and the puzzle completion is fully under your control! :-)

More documentation on how to handle/protect the postMessage API can be found here:

MDN postMessage docs

.

To authenticate a puzzle player, Puzzel.org uses its own registration + authentication system by default. However, some systems/platforms might find it helpful to use their own authentication servers as a way to register/log in a puzzle player automatically based on their active session within a LMS/corporate website (sort of like SSO, but then automated).

This way, the puzzle results will automatically be connected to the right individual, without the player having to log-in separately for the puzzle.

To accomplish this, you will need to have/create an authentication instance on your end to provide a JWT (JSON web token) to Puzzel.org, which can be decoded following the OIDC standards.

Especially when your organisation has this in place already, it is very interesting to consider using this flow. Currently, enabling and setting up the custom auth requires a bit of manual input. If you feel like this might be the perfect solution for your organisation, email me at daan@puzzel.org and we can discuss the details.

More information about the OIDC standards can be found here:

OpenID Connect Docs

Puzzel.org offers puzzle result tracking + registration within its own ecosystem but to automate/customize the tracking a bit further, you might want to handle the saving of results yourself. To allow this, you can easily add your own webhook URL to handle the puzzle results.

Every time Puzzel.org saves a puzzle result (after a correct answer for example), it checks whether a webhook URL is enabled and if so, it will POST the data to that URL.

You can enable the webhook settings via Premium > Developer > Save puzzle results via webhook and then fill in the webhook link in the Webhook link field.

The payload will have the following json format:

{
    puzzleKey: string,
    results: object,
    account: object,
    type: "stats" | "player_info"
}

The results and payload will differ depending on the puzzle type and registration settings, so it will be helpful to check out the details of the payload when setting up and testing your webhook endpoint.

The 'type' key lets you determine what kind of result you are receiving. The "stats" value means it is a saved puzzle result while the "player_info" value is received once a player fills in their info in the completion message.

Note: The results that are sent via the webhook are protected against tampering, since the player does not actually post their result to the real webhook that you've added in your settings. It pings an intermediate Puzzel.org endpoint that queries the latest puzzle results for the given puzzle player and then posts it to your webhook.