@faceit/ingame-helper
v5.6.0
Published
A promise-based library for communicating with the In-Game App via postMessage.
Downloads
20
Maintainers
faceit_ltdReadme
Table of Contents
InGame Helper
The InGame Helper is a helper tool meant to be used by web game developers. It renders the InGame App and it also handles the communication with your web game.
Rendering the InGame App
Initially, the game developer needs to define a div component with faceitInGameAppContainer as id. Check the Complete HTML example.
The render method will then look for that faceitInGameAppContainer id and render the InGame App.
render method
The render method appends the InGame App to the div element with the faceitInGameAppContainer id that has previously been defined by the game developer.
The render method returns an instance of the InGame App. The InGame App instance is meant to be passed later in the connectToChild iframe param.
You can show different views with the render method depending on the params that you pass to it.
The render method is only meant to be called once, for the initial rendering of the InGame App. If you need to toggle its visibility after the initial render, you can do so by hiding/showing the div with the faceitInGameAppContainer id.
/matchmaking view
Passing only the gameId to the payload will load the /matchmaking view.
// Render Faceit InGame Application
render({
gameId: "clicker_game",
}).then((faceitIgaInstance) => {
connectToChild({
iframe: faceitIgaInstance,
methods: {
// Methods here
}
});
});After the user has found a match and all players have accepted the match, the user will be automatically redirected to the /room view.
/room view
Passing the gameId and the matchId to the payload will load the /room view.
// Render Faceit InGame Application
render({
gameId: "clicker_game",
matchId: "1-7090c4f6-7bdb-413c-a26c-9b10445f1161"
}).then((faceitIgaInstance) => {
connectToChild({
iframe: faceitIgaInstance,
methods: {
// Methods here
}
});
});The postMatch is a state of the /room view. The /room view will show the postMatch state if the match status is finished.
ref param
The optional ref param is a string that can be included in the render method. It is used for tracking purposes.
// Render Faceit InGame Application
render({
gameId: "test_game",
// optional
ref: "test_ref"
}).then((faceitIgaInstance) => {
connectToChild({
iframe: faceitIgaInstance,
methods: {
// Methods here
}
});
});Complete HTML example
<!DOCTYPE html>
<html>
<head>
<title>HTML InGame App complete example</title>
<style>
body {
height: 100vh;
margin: 0;
display: flex;
align-items: center;
justify-content: center;
}
</style>
<script src="https://unpkg.com/@faceit/[email protected]/dist/ingame_helper.min.js"></script>
<script>
document.addEventListener("DOMContentLoaded", () => {
// Render Faceit InGame Application /matchmaking view
window.InGameHelper.render({
gameId: "clicker_game",
}).then((faceitIgaInstance) => {
// Create InGameHelper child connection to the Faceit InGame Application
const connection = window.InGameHelper.connectToChild({
// Pass Faceit InGame Application instance returned by InGameHelper.render
iframe: faceitIgaInstance,
methods: {
// Expose sendRequest method to the In-Game App
sendRequest: ({ method, params }) => {
// Game handles events
switch (method) {
case "ingame_app_closed":
console.log("InGame App closed.");
return "done";
case "get_auth_config":
// Ideally you would have computed the authConfig before.
const mockedAuthConfig = {
auth_string: "gameid112233",
platform: "development",
cloud_function: null,
};
return mockedAuthConfig;
case "show_overlay":
// E.g faceit.com/en/players/foo_player/stats/bar_game →
window.open("https://www.faceit.com/en" + params.path);
return "done";
case "external_url":
window.open(params.path);
return "done";
case "match_found":
// Heppens when a match has been found (classic faceit.com trumpet).
// playMatchFoundSound();
return "done";
case "queue_joined":
// Happens when a queue has been successfully joined after the player pressed FIND
// playQueueJoinedSound();
return "done";
case "match_ready":
// {"deep_link": "https://comp.krunker.io/?game=FRA:eo7bi"}
const connectInformation = JSON.parse(
params.connect_information
);
// Perhaps you'd like to open the match in the same tab.
window.open(connectInformation.deep_link, "_self");
// OPTIONAL
if (params.is_reconnect) {
/*
Means the user is connecting to the match from a
reconnect view.
Perhaps you'd like to know when the user is reconnecting.
*/
}
return "done";
case "ui_event":
if (params.interaction_type === "mouse_enter") {
// playSoundMouseEnterSound();
}
if (params.interaction_type === "mouse_click") {
// playMouseClickSound();
}
return "done";
case "get_version":
// Return the version of your game for debugging purposes.
return "1.0.0";
default:
break;
}
},
},
// Optional, lets you see logs about handshake and events
debug: true,
});
});
});
</script>
</head>
<body>
<!-- Create div with faceitInGameAppContainer id -->
<!-- The Faceit InGame Application supports 16:9 aspect ratio resolutions -->
<div
id="faceitInGameAppContainer"
style="border: 0; width: 1280px; height: 720px"
/>
</body>
</html>