Passo 1
La pagina principale si carica iframe
Il tuo sito visualizza un iframe che punta a /embed/{gameSlug}/frame/ con tenantId e parametri di query opzionali mode o campaignId.
Embed API documenti
Inizia con la demo live, osserva gli eventi della pagina principale, quindi copia i pattern iframe e listener nel tuo sito. Lo stesso flusso funziona per ogni gioco Games I Know iframe.
Ottieni una chiave embedEffettua una mossa in Tic Tac Toe iframe. Il registro eventi mostra GAME_STARTED, gli eventi di gioco e i payload di completamento esattamente come li riceve una pagina padre.
Contratto per eventi a livello di piattaforma
Games I Know invia eventi embed per ogni gioco sulla piattaforma: Tic Tac Toe, Four in a Row, Bingo e I Know oggi, e ogni nuovo gioco embed che aggiungeremo in futuro. Non è necessaria un'integrazione separata per ogni titolo. Crea un listener per la pagina principale in base al contratto standard (ready, GAME_STARTED, eventi di gioco, completamento con dati del vincitore e risultati firmati) e riutilizzalo per tutti i giochi embed attuali e futuri.
Utilizza questo percorso quando sai già dove il gioco deve apparire sul tuo sito web.
Utilizza /embed/{gameSlug}/frame/ con il tuo tenantId. Non utilizzare iframe la landing page SEO.
Vai al passaggioFiltra in base a data.source === "gamesiknow", quindi gestisci gli eventi GAME_STARTED, GAME_COMPLETED e gli eventi di gioco della versione 1.
Vai al passaggioInvia resultId e signedToken al tuo backend prima di assegnare crediti, premi o sbloccare contenuti.
Vai al passaggioUtilizza il tuo vero tenantId che trovi nella dashboard del partner.
<iframe
src="https://gamesiknow.com/embed/tic-tac-toe/frame/?tenantId=YOUR_TENANT_ID"
title="Tic Tac Toe by Games I Know"
width="100%"
height="640"
style="border:0;border-radius:16px;max-width:420px;display:block;margin:0 auto;"
loading="lazy"
allow="fullscreen"
referrerpolicy="no-referrer-when-downgrade"
allowfullscreen
></iframe>Un Games I Know embed è un iframe in ambiente sandbox sul tuo dominio. Convalida il tuo tenant e il tuo dominio rispetto al API, quindi comunica con la tua pagina principale tramite window.postMessage.
Passo 1
Il tuo sito visualizza un iframe che punta a /embed/{gameSlug}/frame/ con tenantId e parametri di query opzionali mode o campaignId.
Passo 2
La chiamata iframe effettua il GET /embed/config (o /api/embed/config). Games I Know verifica il tuo account partner, il dominio consentito, l'accesso al gioco e la quota AI. Viene registrato un evento di analisi embed_loaded lato server.
Passo 3
Il iframe invia un evento ready alla pagina padre in modo da poter mostrare uno stato di caricamento o ridimensionare il frame utilizzando payload.embedHeight.
Passo 4
Quando inizia il gioco, ogni gioco embeddable invia GAME_STARTED alla pagina principale e registra game_started lato server automaticamente. Non è necessario chiamare alcun servizio di analisi API dal tuo sito web.
Passo 5
Durante la partita, gli eventi di gioco della versione 1, come il movimento e il cambio di modalità, aggiornano l'interfaccia utente o le analisi interne.
Passo 6
Al termine, ogni gioco embeddable invia GAME_COMPLETED al genitore con risultato, vincitore e giocatori in modo che la tua pagina possa mostrare i risultati immediatamente. Il iframe firma anche il risultato tramite POST /embed/results e include resultId e signedToken in GAME_COMPLETED quando la firma ha successo. Il tuo backend può verificare questi token con una chiave del server partner prima di assegnare le ricompense.
Due formati di postMessaggio
Eventi del ciclo di vita utilizzare un oggetto piatto con event: "GAME_STARTED" or event: "GAME_COMPLETED". Eventi di gioco avvolgi i dati in version: 1 con annidati payload. Filtro sempre attivo data.source === "gamesiknow".
La maggior parte delle integrazioni si basa su quattro decisioni: registrare il dominio, generare un token, installare iframe e infine rimanere in ascolto degli eventi di inizio e completamento.
Aggiungi ogni dominio che ospiterà un Games I Know embed. I domini sono normalizzati in modo che example.com e www.example.com vengano gestiti in modo coerente.
Crea un token embed separato per ogni sito web. Questo mantiene puliti i dati analitici e prepara l'account per futuri prezzi basati sul dominio.
Copia il wrapper iframe o il wrapper responsivo nel blocco HTML personalizzato del tuo CMS, nell'area embed del generatore di siti web o nel template frontend personalizzato.
Gestisci gli eventi postMessage GAME_STARTED e GAME_COMPLETED sulla tua pagina principale per mostrare lo stato della partita e i dettagli del vincitore. Verifica i risultati firmati dal tuo backend con una chiave del server del partner prima di assegnare i premi.
Larghezza
Utilizzare il 100% in modo che embed riempia la colonna del contenuto disponibile.
Altezza
640px per la maggior parte dei giochi. Tic Tac Toe funziona anche a 600px. Usa payload.embedHeight dagli eventi ready per ridimensionare automaticamente.
Giochi
Usa /embed/tic-tac-toe/frame/, /embed/four-in-a-row/frame/, /embed/bingo/frame/ o /embed/i-know/frame/.
Modalità
Ometti la modalità per la scelta del giocatore, oppure passa mode=ai quando vuoi che embed richieda prima AI.
Il giocatore sceglie il tipo di partita all'interno della partita quando è disponibile la quota AI.
<iframe
src="https://gamesiknow.com/embed/tic-tac-toe/frame/?tenantId=TENANT_ID"
width="100%"
height="640"
style="border:0;border-radius:16px;max-width:420px;display:block;margin:0 auto;"
allow="fullscreen"
loading="lazy"
title="Tic Tac Toe by Games I Know"
></iframe>Richiede prima AI. Quando la quota è esaurita, passa automaticamente a PvP senza alcun messaggio di errore.
<iframe
src="https://gamesiknow.com/embed/tic-tac-toe/frame/?tenantId=TENANT_ID&mode=ai&campaignId=homepage-widget"
width="100%"
height="640"
style="border:0;border-radius:16px;max-width:420px;display:block;margin:0 auto;"
allow="fullscreen"
loading="lazy"
title="Tic Tac Toe vs AI by Games I Know"
></iframe>Gli URL dei frame utilizzano /embed/{gameSlug}/frame/. Pagine di destinazione SEO senza gameplay pubblicate su /embed/{gameSlug}/.
| Parametro | Necessario | Descrizione |
|---|---|---|
| tenantId | SÌ | Il tuo ID tenant partner dalla dashboard partner Games I Know. Accettato anche come partnerId per le integrazioni legacy. |
| modalità | NO | Impostato su ai per richiedere la modalità forzata AI. Le regole relative alle quote lato server e al dominio rimangono valide. In caso di indisponibilità di AI, si torna alla modalità giocatore contro giocatore. |
| ID campagna | NO | Etichetta di campagna opzionale riprodotta negli eventi postMessage e memorizzata negli strumenti di analisi dei partner per test A/B o segmentazione a livello di pagina. |
Lo stesso contratto si applica a Tic Tac Toe, Four in a Row, Bingo, I Know e alle prossime versioni di embed.
Regola 1
Fonte del filtro
Ignora i messaggi a meno che data.source non sia gamesiknow.
Regola 2
Gestire il ciclo di vita
Utilizzare GAME_STARTED e GAME_COMPLETED per visualizzare lo stato della partita, il nome del vincitore e l'esito.
Regola 3
Verifica per ottenere premi
Inoltra resultId e signedToken al tuo backend prima di assegnare le ricompense.
| Evento | Quando spara | Formato | Campi chiave |
|---|---|---|---|
| pronto | Embed inizializzato e configurazione caricata. | Gameplay (versione 1) per tutti i giochi, oppure flat per alcuni wrapper del ciclo di vita. | matchId, modalità, embedAltezza |
| GIOCO_INIZIATO | Ogni partita embed disponibile (attuale e futura). Si attiva all'inizio di una partita (ad esempio, la prima mossa o l'inizio del round AI). | ciclo di vita piatto | game, partnerId, campaignId, mode, matchId (implicito tramite flusso di gioco) |
| GIOCO COMPLETATO | Ogni partita embeddable al termine di un incontro. Include risultato, vincitore, nome del giocatore vincitore e giocatori, in modo che la pagina principale possa mostrare i risultati immediatamente. Include anche resultId e signedToken quando la firma lato server ha successo. | ciclo di vita piatto | risultato, vincitore, nomeGiocatoreVincitore, IDGiocatoreVincitore, giocatori, punteggio, durataSecondi, IDRisultato, tokenFirmato |
| MODIFICA INCORPORA_A_SCHERMO_INTERO | Il giocatore attiva/disattiva la modalità a schermo intero. | ciclo di vita piatto | payload.active booleano |
Forma: { source, game, version: 1, event, payload }
Ogni post di gioco embeddable GAME_COMPLETED al genitore con outcome, winner, E players quando una partita finisce. Quando la firma va a buon fine, GAME_COMPLETED include anche resultId E signedToken per la verifica del backend.
{
"source": "gamesiknow",
"event": "GAME_STARTED",
"game": "tic-tac-toe",
"partnerId": "partner_your_tenant",
"campaignId": "homepage-widget",
"mode": "ai"
}{
"source": "gamesiknow",
"event": "GAME_COMPLETED",
"game": "tic-tac-toe",
"resultId": "res_abc123xyz",
"partnerId": "partner_your_tenant",
"campaignId": "homepage-widget",
"status": "completed",
"outcome": "player_1",
"score": 100,
"durationSeconds": 24,
"winnerPlayerId": "player_1",
"winnerPlayerName": "Player X",
"winner": {
"playerId": "player_1",
"participant": "player_1",
"type": "human",
"label": "Player 1",
"name": "Player X",
"score": 100
},
"players": [
{
"playerId": "player_1",
"participant": "player_1",
"type": "human",
"label": "Player 1",
"name": "Player X",
"score": 100,
"status": "winner"
},
{
"playerId": "player_2",
"participant": "ai_bot",
"type": "ai",
"label": "AI BOT",
"name": "AI Bot",
"score": 60,
"status": "lost"
}
],
"signedToken": "eyJ..."
}giocatore_1
Il primo giocatore umano ha vinto.
giocatore_2
Il secondo giocatore umano ha vinto.
bot_ai
L'avversario ha vinto.
disegno
Nessun vincitore.
Supportato solo su Tic Tac Toe e Four in a Row. Seleziona la contentWindow iframe con lo slug del gioco e l'azione.
// Parent page -> iframe (Tic Tac Toe or Four in a Row)
const iframe = document.querySelector("iframe");
iframe.contentWindow.postMessage(
{ game: "tic-tac-toe", action: "reset" },
"https://gamesiknow.com"
);
iframe.contentWindow.postMessage(
{ game: "tic-tac-toe", action: "get_state" },
"https://gamesiknow.com"
);Copia questo listener nella pagina che ospita il tuo iframe. Gestisce lo stato di pronto, l'avvio del gioco, gli eventi di gioco, il completamento firmato e i cambiamenti a schermo intero.
Filtra per origine, gestisci GAME_STARTED e GAME_COMPLETED per l'interfaccia utente del vincitore e gli eventi di gioco durante la partita.
/**
* Games I Know embed listener (parent page)
* Handles lifecycle events (GAME_STARTED, GAME_COMPLETED) and
* version 1 gameplay events (move, mode_change, ...).
*/
const TRUSTED_ORIGIN = "https://gamesiknow.com"; // or your self-hosted origin
window.addEventListener("message", (event) => {
if (TRUSTED_ORIGIN !== "*" && event.origin !== TRUSTED_ORIGIN) return;
const data = event.data;
if (!data || data.source !== "gamesiknow") return;
// --- Lifecycle events (flat top-level event name) ---
if (data.event === "GAME_STARTED") {
console.log("Match started", {
game: data.game,
mode: data.mode,
partnerId: data.partnerId,
campaignId: data.campaignId,
});
return;
}
if (data.event === "GAME_COMPLETED") {
const winnerLabel = data.winner?.name ?? data.winnerPlayerName ?? null;
console.log("Match completed", {
game: data.game,
outcome: data.outcome, // player_1 | player_2 | ai_bot | draw
winner: data.winner,
winnerName: winnerLabel,
players: data.players,
});
if (winnerLabel) {
document.getElementById("game-winner")!.textContent = `${winnerLabel} won!`;
} else if (data.outcome === "draw") {
document.getElementById("game-winner")!.textContent = "Draw";
}
// For rewards: send resultId + signedToken to YOUR backend (never call verify from the browser)
if (data.resultId && data.signedToken) {
fetch("/api/reward-winner", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({
resultId: data.resultId,
signedToken: data.signedToken,
userId: currentUserId,
}),
});
}
return;
}
if (data.event === "EMBED_FULLSCREEN_CHANGE") {
document.body.classList.toggle("embed-fullscreen-active", Boolean(data.payload?.active));
return;
}
// --- Gameplay events (version 1 envelope) ---
if (data.version === 1 && typeof data.event === "string") {
switch (data.event) {
case "ready":
resizeEmbed(data.payload?.embedHeight);
break;
case "mode_change":
console.log("Mode changed", data.payload?.mode);
break;
case "move":
console.log("Move", data.payload);
break;
default:
console.log("Gameplay event", data.event, data.payload);
}
}
});
function resizeEmbed(height) {
const iframe = document.querySelector('iframe[src*="/embed/"]');
if (iframe && typeof height === "number") iframe.style.height = `${height}px`;
}Lista di controllo per l'integrazione
Utilizza GAME_COMPLETED nella pagina principale per mostrare chi ha vinto. Per i premi, verifica i risultati firmati dal tuo backend con una chiave del server partner: non chiamare mai la funzione di verifica API dal browser JavaScript.
Solo lato server. Utilizzare resultId e signedToken da GAME_COMPLETED con autorizzazione: Bearer gik_psk_…
POST https://api.gamesiknow.com/embed/results/verify
Authorization: Bearer gik_psk_your_secret_key
Content-Type: application/json
{
"resultId": "res_abc123xyz",
"signedToken": "signed_token_from_game_completed"
}
Call from your backend server only. The partner server key must belong to the same tenant as the signed result. Browser requests are rejected.{
"ok": true,
"resultId": "res_abc123xyz",
"partnerId": "partner_your_tenant",
"gameSlug": "tic-tac-toe",
"outcome": "player_1",
"score": 100,
"durationSeconds": 24
}Il tuo backend riceve i token dalla pagina principale, li verifica con Games I Know e quindi assegna la ricompensa.
// Example: Node.js / Express handler on YOUR server
app.post("/api/reward-winner", async (req, res) => {
const { resultId, signedToken, userId } = req.body;
const verify = await fetch("https://api.gamesiknow.com/embed/results/verify", {
method: "POST",
headers: {
"content-type": "application/json",
authorization: `Bearer ${process.env.GAMESIKNOW_PARTNER_SERVER_KEY}`,
},
body: JSON.stringify({ resultId, signedToken }),
});
if (!verify.ok) return res.status(403).json({ error: "Invalid result" });
const result = await verify.json();
if (result.outcome !== "player_1") {
return res.status(400).json({ error: "Player did not win" });
}
await grantReward(userId, result);
return res.json({ ok: true });
});Games I Know registra automaticamente questi eventi quando il tuo iframe viene caricato e i giocatori interagiscono. Questi eventi vengono visualizzati nella dashboard del partner. Per importare gli stessi dati nel tuo database, crea una chiave server partner nella pagina di installazione ed esegui la chiamata GET /partners/analytics solo dal tuo server backend.
Genera una chiave server partner in Partner Dashboard → Installa. Salvala come segreto del server. Utilizza i parametri di query seguenti per filtrare l'esportazione.
GET https://api.gamesiknow.com/partners/analytics
Autorizzazione: Bearer gik_psk_your_secret_key
Parametri di query opzionali:
domain Nome host del sito web registrato (example.com)
campaignId Valore dal parametro campaignId iframe
gameSlug tris | quattro in fila | bingo | i-know
da Data di inizio in UTC (AAAA-MM-GG)
a Data di fine in UTC (AAAA-MM-GG)
Esempio:
/partners/analytics?domain=www.example.com&gameSlug=tic-tac-toe&from=2026-05-01&to=2026-05-31
Esegui la chiamata solo dal tuo server backend. Non esporre mai la chiave del tuo server partner nel browser JavaScript.Ogni gioco embeddable invia gli stessi eventi principali. Confronta tempi e funzionalità extra per ogni titolo qui sotto.
| Gioco | GIOCO_INIZIATO | Segnale di completamento | Firmato | Forzato AI | Height | Comandi genitori |
|---|---|---|---|---|---|---|
| Tic Tac Toe | Prima mossa o AI inizio | GIOCO COMPLETATO | SÌ | SÌ | 640px | ripristina, ottieni_stato |
| Four in a Row | Prima mossa o AI inizio | GIOCO COMPLETATO | SÌ | SÌ | 640px | ripristina, ottieni_stato |
| Bingo | Inizia la partita (AI o PvP) | GIOCO COMPLETATO | SÌ | SÌ | 640px | Nessuno ancora |
| I Know | Inizia la partita (AI o PvP) | GIOCO COMPLETATO | SÌ | SÌ | 640px | Nessuno ancora |
Questa pagina è il riferimento tecnico. Utilizza queste guide quando hai bisogno di istruzioni di installazione specifiche per la piattaforma o di consigli sul posizionamento verticale. Tutte le guide utilizzano lo stesso iframe e lo stesso modello di eventi documentati sopra.
Framework-specific iframe placement, event listeners, and production notes.
Copy-paste embed guides for no-code and low-code site builders.
Placement and UX recommendations for common website types.
Cerchi pagine di panoramica generale come giochi iframe, widget HTML5 o giochi embed gratuiti? Sfoglia tutto embed guide sull'hub.
Risposte relative ai dettagli di integrazione, al supporto dei giochi attuali, ai comandi, ai risultati firmati e alla compatibilità con i giochi futuri.
Sì. Games I Know embed utilizzano HTML standard iframe, quindi funzionano nei blocchi HTML personalizzati di WordPress, negli elementi embed di Webflow, nelle aree di codice personalizzate di Wix e Squarespace, nell'HTML statico, in React, Next.js e in altri siti personalizzati. Registra prima il dominio del sito web nella tua dashboard partner, quindi incolla lo snippet del frame generato nella pagina in cui dovrebbe apparire il gioco.
/embed/{gameSlug}/ è la pagina di destinazione pubblica per un gioco embed. /embed/{gameSlug}/frame/ è il runtime iframe che deve essere incollato nel tuo sito web. Usa sempre l'URL /frame/ nel codice iframe perché carica il gioco giocabile, convalida il tuo tenant e il dominio e invia gli eventi della pagina principale.
Sì. I giochi Games I Know iframe sono progettati per browser mobili, tablet, laptop e desktop. Utilizza width="100%" e un'altezza consigliata di circa 640px per la maggior parte dei embed. Puoi anche ascoltare l'evento ready e utilizzare payload.embedHeight se desideri che la pagina principale ridimensioni automaticamente il iframe.
Games I Know iframe embed sono gratuiti durante la beta di embed. Non è richiesta alcuna carta di credito per iniziare e gli attuali embed beta non includono pubblicità. Crea un account partner gratuito, registra il tuo dominio e genera lo snippet iframe dalla dashboard.
Sì. Un account partner ti fornisce un ID tenant e uno snippet iframe con restrizioni di dominio. Lo snippet iframe invia l'ID tenant con l'URL del frame in modo che Games I Know possa convalidare il partner, il dominio consentito, l'accesso al gioco, la quota AI, la campagna di analisi e il flusso di verifica dei risultati.
Il embed è soggetto a restrizioni di dominio. Se qualcuno copia il tuo snippet iframe su un sito web non autorizzato, Games I Know verifica l'origine della richiesta rispetto ai domini configurati per il tuo account partner e blocca l'utilizzo non approvato. Utilizza ID campagna separati quando desideri analisi più precise per sito web o campagna.
Tic Tac Toe, Four in a Row, Bingo e I Know supportano iframe embed oggi. Ogni gioco invia il contratto di evento embed standard per lo stato di pronto, l'avvio del gioco, il gameplay, il completamento, i dati del vincitore, le analisi e la verifica del risultato. Si prevede che i nuovi giochi compatibili con embed seguano lo stesso schema di eventi, in modo che i partner non debbano ricostruire la loro integrazione.
Ogni gioco embeddable utilizza due formati postMessage. Gli eventi del ciclo di vita utilizzano una forma piatta con origine: gamesiknow e valori evento come ready, GAME_STARTED, GAME_COMPLETED e EMBED_FULLSCREEN_CHANGE. Gli eventi di gioco utilizzano la versione: 1 con nomi di eventi annidati come ready, mode_change, move, reset, undo e state. Filtra sempre su data.source === "gamesiknow".
Sì. Ascolta l'evento GAME_STARTED all'inizio di una partita, utilizza gli eventi di gioco come move e mode_change durante la partita e GAME_COMPLETED alla fine di una partita. GAME_COMPLETED include outcome, winner, players, score, duration e identificatori del risultato laddove la firma sia disponibile. Le analisi lato server registrano anche caricamenti, avvii, completamenti, tentativi bloccati e clic sulle CTA.
Utilizza GAME_COMPLETED al termine di una partita. Ogni gioco embeddable invia questo evento del ciclo di vita con risultato, vincitore, nome del giocatore vincitore e giocatori. Quando GAME_COMPLETED include resultId e signedToken, inoltrali al tuo backend e chiama POST /embed/results/verify con la chiave del tuo server partner prima di assegnare premi o crediti.
Aggiungi window.addEventListener("message", handler) alla pagina che ospita iframe. Nell'handler, ignora i messaggi a meno che event.data.source === "gamesiknow". Esegui un salto su event.data.event per gli eventi del ciclo di vita, oppure su event.data.event più event.data.version === 1 per gli eventi di gioco. Facoltativamente, convalida event.origin rispetto all'origine Games I Know consentita.
Utilizza GAME_COMPLETED nella pagina principale per mostrare immediatamente chi ha vinto (risultato, vincitore, nome del giocatore vincitore, giocatori). Per i premi, invia resultId e signedToken da GAME_COMPLETED al tuo backend, quindi chiama POST /embed/results/verify con Authorization: Bearer gik_psk_… utilizzando una chiave del server partner dalla tua dashboard. L'endpoint di verifica è solo lato server: non chiamarlo mai dal browser JavaScript. Assegna i premi solo dopo che la verifica è andata a buon fine.
Obbligatorio: tenantId (l'ID del tuo partner tenant). Facoltativo: mode=ai per richiedere la modalità forzata AI quando la quota lo consente, e campaignId per segmentare le analisi. Gli URL dei frame seguono /embed/{gameSlug}/frame/?tenantId=YOUR_TENANT_ID.
Sì. Aggiungi mode=ai all'URL iframe per richiedere prima la modalità AI. Le regole relative alle quote e al dominio lato server rimangono valide, quindi embed può ripiegare sulla scelta del giocatore o sul giocatore contro giocatore quando la modalità AI non è disponibile o la quota è esaurita.
Tic Tac Toe e Four in a Row accettano messaggi parent con il gioco impostato sullo slug del gioco e l'azione impostata su reset o get_state. iframe risponde con un evento di gioco di stato. Altri giochi embed non espongono ancora i comandi parent.
Prima di generare un token, verifica che il dominio del sito web sia attivo.
Utilizzare un token o un campaignId separato per ogni sito web o gruppo di campagne.
Ascolta i messaggi GAME_STARTED e GAME_COMPLETED sulla pagina principale.
Mantenere visibile il marchio Games I Know all'interno di embed.
Verifica i risultati firmati nel tuo back-end prima di assegnare premi o crediti.
Il test impone la modalità AI e il fallback a PvP quando la quota di AI è esaurita.
Condividi il sito web, il CMS e il posizionamento desiderato del gioco. Possiamo esaminare insieme il cablaggio dell'evento embed.