Come ospitare un gioco HTML5 sul proprio sito web

Come ospitare un gioco HTML5, in una frase: caricate il contenuto della sua cartella game/ su qualsiasi hosting che serva file statici, mantenete le sottocartelle esattamente come sono e aprite l'indirizzo della cartella in un browser. La cartella game/ pronta per l'hosting di ogni edizione del nostro marketplace funziona così com'è: niente PHP, niente database, niente fase di build e niente account, quindi l'hosting deve solo consegnare file al browser del giocatore.

Questo è tutto il lavoro quando va tutto bene. Questa guida riguarda gli altri giorni: una schermata bianca, errori 404, un messaggio sul tipo MIME, un iframe che non vuole mostrare nulla. Vendiamo noi questi template, quindi leggetela come un manuale operativo per i nostri pacchetti. Abbiamo servito copie di Gridspark e Velvet Pool da un server locale usa e getta, abbiamo rotto Gridspark di proposito in diversi modi e abbiamo letto i manuali pubblici di altre edizioni. Quando un'affermazione viene da un manuale invece che da una nostra prova, lo diciamo.

Che cosa comporta davvero ospitare un gioco HTML5

Un hosting statico conserva i file e li consegna ai browser su richiesta. Non esegue mai il vostro gioco: lo fa il browser del giocatore. Per questo i requisiti delle nostre edizioni sono così semplici: un browser aggiornato, un hosting che serva file statici via HTTP o HTTPS, e nessun PHP, database o account per giocare. La cartella game/ è già compilata, quindi pubblicarla non richiede npm né fase di build.

Due limiti da conoscere prima di iniziare. Alcune edizioni hanno parti facoltative che non sono statiche: Zabum e Ricopop elencano una classifica facoltativa che richiede PHP 7.4 o successivo e una cartella scrivibile, e le edizioni TypeScript (Beep Out, Pinloop, Trimora, Twirldrop, Riffvolt, Sunset Rally, Tenguin, Mochi Monsters, Deepforge, Barricade Z e Zabum) richiedono Node.js solo se volete modificare il sorgente e ricompilare; ogni manuale indica la versione. Velvet Pool, Puttide, Ricopop e Gridspark includono JavaScript semplice, senza passaggi di compilazione tra le vostre modifiche e i file che caricate. Niente di tutto questo serve per pubblicare il gioco così com'è consegnato. E l'hosting in sé non fa parte dell'acquisto. I termini dello store elencano hosting e installazione sul vostro server tra i servizi separati che quotiamo prima di qualsiasi lavoro; l'assistenza copre le domande sull'installazione e sull'uso dei file forniti.

Che cosa va online e che cosa resta sul vostro computer:

• Caricate tutto ciò che sta dentro game/: index.html, script, stili, immagini, suoni e font.
• Lasciate fuori source/ (la copia modificabile per sviluppatori), documentation/ (il manuale) e lo ZIP stesso. Il manuale di Zabum indica il caricamento di source/ per errore tra le cause di errori 404 come main.tsx.
• Conservate accanto al vostro prodotto le note di licenza di terzi incluse nel pacchetto, come chiedono i termini.

Vedete Gridspark, l'edizione che usiamo come esempio

Come ospitare un gioco HTML5: il percorso breve dallo ZIP alla pagina giocabile

Questi passaggi seguono i capitoli di installazione dei manuali di Velvet Pool, Puttide, Gridspark e Sunset Rally, più i controlli che abbiamo aggiunto dopo i nostri test. Gridspark è l'esempio perché è l'edizione che abbiamo servito e rotto più spesso.

1. Decomprimete il pacchetto sul vostro computer. Troverete game/ (la cartella che pubblicate), source/ (la copia modificabile) e documentation/ (il manuale).
2. Facoltativo ma economico: provatelo in locale. Aprite un terminale dentro game/, eseguite python -m http.server 8765 e visitate http://localhost:8765/. Se gira lì, i file sono a posto e qualsiasi problema successivo dipende dall'hosting.
3. Scegliete subito l'indirizzo finale, per esempio https://your-site.example/games/gridspark/. Una sottocartella funziona perché i percorsi dentro il gioco sono relativi; il manuale di Gridspark suggerisce public_html/games/gridspark/.
4. Caricate il contenuto di game/ in quella cartella con il file manager dell'hosting o un client FTP, mantenendo ogni sottocartella. index.html deve finire direttamente dentro la cartella, non un livello più in profondità.
5. Aprite l'indirizzo della cartella in https, con la barra finale. In Gridspark toccate la schermata iniziale (i browser aspettano un tocco o un clic prima di consentire l'audio) e premete Play.
6. Fate una mossa, ricaricate la pagina e controllate che il menu ora offra Continue. Dimostra che il browser sta salvando i progressi per il vostro indirizzo.
7. Collegate la cartella dal vostro sito, oppure incorporatela in una pagina (vedete la sezione sull'iframe più sotto).

Una cartella Gridspark completa contiene index.html, style.css, gridspark.config.js, src/ e assets/ affiancati, e il manuale chiede di tenerli insieme. Altre edizioni hanno una struttura diversa (Velvet Pool ha css/ e assets/ invece di un unico foglio di stile), ma la regola è la stessa: caricate la cartella come arriva.

Perché il doppio clic su index.html dà una pagina bianca

Le edizioni che abbiamo aperto caricano il loro codice come moduli ES, e i browser rifiutano di caricare moduli da indirizzi file://. Abbiamo aperto Gridspark direttamente da disco in Chromium e abbiamo ottenuto una schermata scura e vuota. La console diceva che lo script era bloccato dalla policy CORS, con il motivo «Cross origin requests are only supported for protocol schemes» come http e https. La stessa cartella servita da un server web locale mostrava subito la schermata iniziale. I manuali di Velvet Pool, Puttide, Sunset Rally e Gridspark dicono tutti la stessa cosa: non aprite il gioco da file://.

• Non funziona: file:///C:/Users/you/games/gridspark/index.html
• Funziona: http://localhost:8765/ da un server di prova locale, oppure https://your-site.example/games/gridspark/ sul vostro hosting.

Abbiamo provato solo Chromium. I manuali descrivono il blocco come qualcosa che fanno i browser più diffusi, quindi prevedetelo ovunque.

Incorporare il gioco in una pagina con un iframe

Per mostrare il gioco dentro una pagina che avete già, puntate un iframe alla cartella caricata. Questo è il tag che abbiamo provato:

<iframe src="https://your-site.example/games/gridspark/" title="Gridspark" allow="fullscreen; autoplay" width="960" height="540" style="border:0"></iframe>

• src: l'indirizzo completo della cartella, con https e la barra finale.
• title: un nome breve. Gli screen reader lo usano per descrivere il riquadro.
• allow="fullscreen; autoplay": i manuali dicono di consentire schermo intero e riproduzione automatica in un iframe quando serve. Nel nostro test un riquadro da un altro indirizzo senza questo attributo aveva lo schermo intero disattivato, e Gridspark nascondeva semplicemente il suo pulsante di schermo intero. Il vecchio attributo allowfullscreen dava lo stesso risultato di allow. Un riquadro sullo stesso indirizzo della pagina ottiene lo schermo intero in ogni caso.
• Nessun attributo sandbox. Con sandbox="allow-scripts" da solo, Gridspark non partiva mai: il riquadro riceve un'origine nulla, il browser bloccava lo script del gioco e il local storage generava un errore di sicurezza. Aggiungere allow-same-origin lo fa funzionare, ma MDN avverte che questa coppia su un riquadro della stessa origine elimina la protezione, quindi per un gioco che ospitate voi stessi, lasciate perdere sandbox.

Dimensionarlo per i telefoni

Un riquadro fisso 16:9 va bene su desktop e male su un telefono. A 390 px di larghezza, un iframe con aspect-ratio 16/9 è alto solo 219 px, e il menu di Gridspark veniva tagliato sotto il pulsante Daily challenge. Dando al riquadro un'altezza di 75svh, tre quarti dell'altezza dello schermo, il menu si vedeva per intero. Anche la vostra pagina ha bisogno di un meta tag viewport; i sei pacchetti che abbiamo aperto ne hanno uno nel proprio index.html, ed è per questo che il gioco si adatta quando lo aprite direttamente.

Il gioco funziona al proprio indirizzo senza nessuna pagina intorno, quindi un semplice link che apre quell'indirizzo è sempre una soluzione di ripiego valida.

Vedete Velvet Pool, un'edizione 3D che si incorpora allo stesso modo

WordPress e altri site builder

Ospitare la cartella e mostrarla in una pagina sono due lavori distinti, e in WordPress usano due strumenti diversi. Tutto ciò che segue viene dalla documentazione e dal riferimento per sviluppatori di WordPress, non dal fatto di aver usato WordPress noi stessi.

1. Caricate la cartella con il file manager dell'hosting o con FTP, nell'albero delle cartelle del sito (per esempio una cartella games/ accanto alle cartelle di WordPress). Non tramite la Libreria multimediale: il codice di WordPress toglie .html e .js dai tipi di caricamento consentiti, a meno che l'utente abbia la capacità unfiltered_html.
2. Aprite l'indirizzo della cartella da solo prima di toccare qualsiasi pagina. Le regole Apache predefinite documentate da WordPress inviano una richiesta a index.php solo quando non esiste alcun file o cartella corrispondente (è ciò che verificano le condizioni !-f e !-d), quindi una cartella caricata viene servita così com'è.
3. Aggiungete l'iframe in un blocco HTML personalizzato. WordPress documenta che per gli utenti senza la capacità unfiltered_html, un Collaboratore per esempio, i tag iframe vengono rimossi al salvataggio dell'articolo. Se il riquadro sparisce dopo il salvataggio, controllate chi ha modificato la pagina.

Altri site builder e CMS: non li abbiamo provati e non facciamo affermazioni su nessuno di essi. Il gioco ha bisogno ovunque delle stesse due cose, un posto per la cartella caricata e un elemento di incorporamento che accetti un iframe. Se un builder non offre nessuno dei due, ospitate la cartella ovunque si servano file statici e collegate il suo indirizzo.

Quando non parte: un elenco per la risoluzione dei problemi

Aprite gli strumenti per sviluppatori del browser (F12 nella maggior parte dei browser desktop) e guardate le schede Console e Network prima di cambiare qualsiasi cosa. Ognuno dei guasti qui sotto lascia lì una riga rossa, e il nome del file al suo interno di solito indica la causa.

Una schermata bianca

Controllate in quest'ordine: l'indirizzo inizia con http:// o https://; la Console non ha righe rosse; i nomi dei file mantengono esattamente maiuscole e minuscole; e, per le edizioni 3D, WebGL2 è disponibile (il manuale di Velvet Pool dice di attivare l'accelerazione hardware). Gli host Linux trattano Game.js e game.js come due file e Windows no, quindi una cartella che funzionava sul vostro PC può rompersi dopo il caricamento. I manuali di Velvet Pool e Zabum avvertono entrambi sulle maiuscole.

404 per src/main.js, font o immagini

Una parte della cartella non è arrivata, oppure è arrivata un livello troppo in profondità. L'abbiamo riprodotto caricando solo index.html, style.css e il file di configurazione: la schermata restava bianca e la scheda Network elencava 404 per src/main.js e per ogni font. Caricate le cartelle mancanti, oppure spostate il contenuto in alto in modo che index.html si trovi all'indirizzo che aprite. Se immagini o suoni mancano o sono corrotti, il manuale di Zabum suggerisce FTP in modalità binaria o automatica, oppure di caricare uno ZIP ed estrarlo nel file manager dell'hosting. Un 404 è un file mancante. Non è un problema MIME.

La pagina si carica senza stili, con icone giganti

Se una regola di riscrittura o un'impostazione di URL puliti serve la cartella senza la barra finale, i percorsi relativi si risolvono un livello più in alto. L'abbiamo riprodotto con un server di prova che restituisce la pagina della cartella senza reindirizzare. Il browser chiedeva /games/style.css e /games/src/main.js invece dei file dentro /games/gridspark/, otteneva 404 e disegnava il menu come pulsanti grezzi e icone sovradimensionate. Collegate la cartella con la barra finale, oppure puntate direttamente a index.html.

Un errore di tipo MIME su uno script modulo

Nel nostro test la console diceva: Failed to load module script: Expected a JavaScript-or-Wasm module script but the server responded with a MIME type of "text/plain". I browser sono rigorosi con gli script modulo. I manuali dicono che il server deve inviare i file .js con un tipo MIME JavaScript e .wasm come application/wasm; il manuale di Sunset Rally aggiunge .mjs. La scheda Network mostra il Content-Type di ogni file. Nelle build che abbiamo aperto, i moduli sono file .js. Se aggiungete file .mjs vostri e una vecchia configurazione di Apache non li associa, una riga in .htaccess risolve, la stessa che usa il nostro sito:

AddType text/javascript .mjs

La tabella dei tipi di Apache 2.4.62 sulla nostra macchina di prova associa già js e mjs a text/javascript e wasm ad application/wasm, quindi un'installazione standard non ha bisogno della riga. Gli altri server hanno le proprie tabelle; chiedete a chi gestisce il vostro.

Bloccato dalla policy CORS

Gli script modulo e i font caricati da un indirizzo diverso richiedono un'intestazione Access-Control-Allow-Origin da quell'indirizzo. Nel nostro test una pagina su una porta non riusciva a caricare uno script modulo da un'altra porta finché il secondo server non inviava l'intestazione. In pratica la soluzione è banale: tenere i file del gioco insieme in una cartella a un unico indirizzo, che è come sono costruiti i pacchetti. Non serve CORS per incorporare il gioco in un iframe su un altro sito, perché l'iframe carica semplicemente l'indirizzo del gioco. Un errore CORS dentro un incorporamento di solito deriva da un attributo sandbox, descritto sopra.

Contenuto misto in una pagina https

Una pagina servita in https non può caricare script o iframe in http: i browser bloccano entrambi, e MDN elenca tra i tipi bloccati anche font e richieste fetch. Usate https:// nell'src dell'iframe e in ogni indirizzo completo che avete digitato. I file del gioco usano percorsi relativi, quindi seguono lo schema dell'indirizzo che avete aperto. Se l'indirizzo https non si apre affatto, attivate prima il certificato nel pannello dell'hosting.

L'iframe dice «refused to connect»

Nel nostro test Chromium registrava questa riga, con l'indirizzo del riquadro bloccato tra i primi apici: Refused to display 'https://game-host.example/' in a frame because it set 'X-Frame-Options' to 'sameorigin'. Il server che ospita il gioco inviava quell'intestazione. SAMEORIGIN consente l'incorporamento solo dallo stesso indirizzo, e DENY non lo consente mai; una regola frame-ancestors in un'intestazione Content-Security-Policy ha una funzione simile. Cambiate l'intestazione per la cartella del gioco, oppure servite la pagina e il gioco da un unico indirizzo.

Nessun audio all'inizio

I browser bloccano l'audio fino al primo tocco o clic, ed è per questo che Gridspark si apre su una schermata «tocca per iniziare». Toccate una volta, poi controllate il volume e i permessi del browser.

Vedete Puttide, l'edizione di golf con una build pronta per l'hosting

Aggiornare il gioco senza servire una versione mezza vecchia

I browser mettono in cache gli script, quindi dopo un caricamento voi o un giocatore potete ancora vedere il vecchio gioco. Il manuale di Gridspark dà la regola: fate un backup delle vostre modifiche, sostituite i file giocabili come un unico insieme, provate e fate un aggiornamento forzato se l'hosting mette in cache i vecchi moduli. Non mischiate moduli vecchi e nuovi. Un gioco fatto di molti piccoli file che si importano a vicenda è la cosa sbagliata da aggiornare a metà.

Le edizioni con un service worker mantengono una propria cache. Zabum è una PWA: dopo un aggiornamento, fate un aggiornamento forzato (Ctrl o Cmd più Maiusc più R). Se avete sostituito file audio, cambiate il nome della cache in sw.js (l'esempio del manuale passa da zabum-v5 a zabum-v6) e caricate quel file. Se il vostro sito sta dietro una CDN, svuotate anche la sua cache. Dei manuali che abbiamo letto, Zabum è l'unica PWA; i manuali di Velvet Pool e Puttide dicono apertamente che la loro non è un'app offline installabile.

Leggete il changelog prima di sostituire i file e conservate una copia di tutto ciò che avete modificato. I salvataggi vivono nel browser di ciascun giocatore, non nella cartella che caricate, quindi sostituire i file non li cancella.

Vedete Zabum, l'edizione PWA con una classifica PHP facoltativa

Dove vengono salvati i progressi e cosa fa la cancellazione dei dati del browser

Queste edizioni non hanno account né un database sul server. Impostazioni, lingua, la partita in corso e i record personali stanno nel local storage del browser, e nulla viene inviato a Polar Games. Il manuale di Gridspark nomina le chiavi gridspark.standalone.v1.*; dopo una mossa abbiamo visto gridspark.standalone.v1.best e gridspark.standalone.v1.save.

Lo storage appartiene all'indirizzo (protocollo, host e porta), non alla cartella. L'abbiamo verificato in tre modi. Una copia di Gridspark in un'altra cartella dello stesso indirizzo leggeva gli stessi valori salvati. Lo stesso gioco aperto come localhost invece di 127.0.0.1 partiva vuoto, e così lo stesso indirizzo su un'altra porta. Il manuale di Zabum aggiunge che http e https, www e non-www, e i sottodomini hanno ciascuno il proprio storage.

• Cancellare i dati del sito o i cookie elimina la partita salvata e i record. In una finestra privata i progressi possono durare solo per la sessione; il gioco continua a girare quando lo storage è bloccato.
• Un altro browser o un altro dispositivo parte da zero. Non c'è sincronizzazione né un account a cui accedere.
• Cambiare l'indirizzo azzera tutti: da http a https, da www a non-www, un nuovo dominio.
• Spostare il gioco in un'altra cartella dello stesso indirizzo mantiene i salvataggi, come ha mostrato il nostro test con Gridspark.

Una checklist di prova prima di condividere il link

1. Aprite l'indirizzo finale nei browser che usano i vostri giocatori: uno basato su Chromium (Chrome o Edge), Firefox e Safari. I nostri test sono stati eseguiti solo in Chromium, quindi questo è l'elenco che dovete eseguire voi.
2. Apritelo su un telefono vero, prima all'indirizzo del gioco e poi dentro la vostra pagina, in entrambi gli orientamenti.
3. Limitate la connessione negli strumenti per sviluppatori e osservate il primo caricamento. Gridspark, servito senza compressione dal nostro server locale, ha richiesto circa 0,5 MB e 26 richieste per raggiungere la schermata iniziale. Con Chromium limitato a 1,6 Mbit/s e 150 ms di latenza, la schermata è comparsa dopo circa 3 secondi. L'intera cartella game/ pesa circa 3,4 MB nella nostra copia; Velvet Pool circa 7,3 MB e Puttide circa 15 MB. Se i telefoni vecchi faticano, il manuale di Zabum suggerisce di verificare che l'hosting comprima i file con gzip o brotli.
4. Fate una mossa, ricaricate e verificate che Continue e il record siano presenti.
5. Toccate una volta e verificate che l'audio parta. Il silenzio prima del primo tocco è normale.
6. Aprite una finestra privata. Il gioco deve comunque girare, anche se dimentica i progressi alla chiusura.
7. Leggete le schede Console e Network al primo caricamento: nessuna riga rossa, nessun 404.
8. In un incorporamento, verificate che il pulsante di schermo intero compaia e che il riquadro sia abbastanza alto su un telefono.

FAQ

Servono PHP, un database o un server speciale per ospitare un gioco HTML5?

Non per le nostre edizioni così come consegnate. Sono statiche: caricate la cartella game/ su un hosting che serva file via HTTP o HTTPS e aprite. Zabum e Ricopop hanno una classifica facoltativa che richiede PHP 7.4 o successivo e una cartella scrivibile.

Posso semplicemente fare doppio clic su index.html?

No. I browser bloccano i moduli del gioco su file://, e la pagina resta bianca. Aprite il gioco tramite un indirizzo http o https, sul vostro hosting o su un server di prova locale come python -m http.server 8765.

Serve HTTPS?

I manuali dicono di usare HTTPS per l'hosting pubblico. Il manuale di Zabum dice che Aggiungi alla schermata Home lo richiede, e una pagina https non può incorporare un iframe http perché i browser lo bloccano come contenuto misto.

Come aggiungo il gioco a una pagina WordPress?

Caricate la cartella con il file manager dell'hosting o con FTP, aprite il suo indirizzo per verificare che giochi, poi aggiungete l'iframe in un blocco HTML personalizzato. Gli utenti senza la capacità unfiltered_html si vedono rimuovere gli iframe, quindi controllate il ruolo di chi modifica la pagina.

Dove vengono salvati i progressi e cosa succede se i giocatori cancellano i dati del browser?

Nel local storage del browser, per indirizzo. Cancellare i dati del sito li elimina, un altro browser o dispositivo parte vuoto, e cambiare dominio o passare tra http e https li azzera. Non ci sono account e nulla viene inviato a noi.

Polar Games ospita il gioco per me?

No. Lo store vende i file. L'assistenza copre le domande sull'installazione e sull'uso; hosting e installazione sul vostro server sono servizi separati che quotiamo prima di qualsiasi lavoro.

Prossimo passo

Se state ancora scegliendo giochi HTML5 per il vostro sito, ogni pagina di articolo elenca i requisiti, collega il manuale e vi lascia giocare la demo prima di pagare. Leggete prima il capitolo di installazione del manuale: è la pagina che userete per il lavoro descritto in questa guida.

Sfogliate i template di giochi HTML5