Plain HTML5 Upload Guide

Back to guides

Preparing Your HTML5 Game

Plain HTML5 games are the simplest to prepare for our platform. They use standard HTML, CSS, and JavaScript without any specific framework.

Create Your Project Structure

Set up a basic project structure:

my-game/
  ├── index.html       # Main entry point
  ├── styles.css       # CSS styles
  ├── main.js          # Main JavaScript file
  ├── game.js          # Game logic
  └── assets/          # Game assets (images, sounds, etc.)
      ├── images/
      ├── audio/
      └── ...

Note: The most important file is index.html, which must be in the root directory.

Create Your HTML File

Your index.html file should include all necessary references to your CSS and JavaScript files:

                       


    
    
    My HTML5 Game

Organize Your JavaScript

For better maintainability, organize your JavaScript code into separate files:

main.js - Initialization and setup

// Initialize game when the window loads
window.addEventListener('load', function() {
    // Initialize your game here
    initGame();
});

function initGame() {
    const canvas = document.getElementById('game-canvas');
    const ctx = canvas.getContext('2d');
    
    // Start the game
    const game = new Game(canvas, ctx);
    game.start();
}

game.js - Game logic and mechanics

class Game {
    constructor(canvas, ctx) {
        this.canvas = canvas;
        this.ctx = ctx;
        this.isRunning = false;
        // Initialize game properties
    }
    
    start() {
        this.isRunning = true;
        this.gameLoop();
    }
    
    gameLoop() {
        if (!this.isRunning) return;
        
        // Clear canvas
        this.ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
        
        // Update game state
        this.update();
        
        // Render game
        this.render();
        
        // Request next frame
        requestAnimationFrame(this.gameLoop.bind(this));
    }
    
    update() {
        // Update game logic here
    }
    
    render() {
        // Render game objects here
    }
}

Handle Assets Properly

Make sure all your assets use relative paths:

// Loading an image
const playerImage = new Image();
playerImage.src = 'assets/images/player.png';

// Loading audio
const backgroundMusic = new Audio('assets/audio/background.mp3');

Important: Always use relative paths (not absolute paths) for all assets to ensure they work correctly when deployed.

Test Your Game Locally

Before uploading, test your game locally using a simple web server:

# Using Node.js http-server
npx http-server

# Using Python
python -m http.server

# Using PHP
php -S localhost:8000

Check that all game features, assets, and interactions work as expected.

Zip Your Game

Compress your entire game folder into a ZIP file:

# On macOS/Linux
zip -r my-game.zip index.html styles.css *.js assets/

# On Windows
# Right-click the folder > Send to > Compressed (zipped) folder

Note: Make sure your index.html file is at the root of the ZIP file.

Common Issues and Solutions

Missing Assets

If your game assets (images, sounds, etc.) aren't loading:

Check that the paths to your assets are correct
Ensure you're using relative paths (e.g., 'assets/images/player.png')
Verify that all asset files are included in the ZIP file

Cross-Browser Compatibility

To ensure your game works across different browsers:

Test your game in multiple browsers (Chrome, Firefox, Safari, Edge)
Use feature detection instead of browser detection
Consider using polyfills for newer JavaScript features
Use vendor prefixes for CSS properties that need them

Mobile Compatibility

To make your game work well on mobile devices:

Use responsive design principles
Implement touch controls for mobile users
Test on various screen sizes and orientations
Consider using the viewport meta tag to control scaling

Performance Optimization

To improve your game's performance:

Minimize the use of DOM manipulation
Use requestAnimationFrame for animation loops
Optimize asset sizes (compress images, use sprite sheets)
Consider using a canvas for rendering instead of DOM elements

Implementing Game Session Tracking

All games uploaded to our platform must implement session tracking functionality. This allows us to track player sessions and maintain leaderboards for your game.

Important: Your game bundle must include API calls to our session tracking endpoints. Our validation system will check for these calls during the upload process. Games without proper session tracking implementation will be rejected.

Option 1: Use Our SDK (Recommended)

The easiest way to implement session tracking is to use our JavaScript SDK. You can download the SDK here or view an example implementation.

Include the following script in your game:

<script src="/sdk/game-session-tracker.js"></script>

Then initialize and use the tracker in your game:

// Initialize the tracker - it will automatically detect the subdomain
const tracker = new GameSessionTracker();

// When the game ends, call endSession with the player's score
function gameOver(score) {
  tracker.endSession(score)
    .then(response => {
      console.log("Session recorded successfully", response);
    })
    .catch(error => {
      console.error("Failed to record session", error);
    });
}

// To display a leaderboard
function showLeaderboard() {
  tracker.getLeaderboard(10) // Get top 10 scores
    .then(response => {
      const leaderboard = response.data.leaderboard;
      // Display leaderboard in your game
    })
    .catch(error => {
      console.error("Failed to fetch leaderboard", error);
    });
}

Option 2: Custom Implementation

If you prefer to implement session tracking yourself, follow these steps:

1. Parse URL parameters when your game loads:

const urlParams = new URLSearchParams(window.location.search);
const token = urlParams.get('token') || generateRandomToken();
const appVersion = urlParams.get('appVersion') || '1.0.0';
const language = urlParams.get('language') || 'en';
const sessionStartTime = new Date();

2. When the game ends, send session data to our API:

function endSession(score) {
  const sessionEndTime = new Date();
  
  const sessionData = {
    token: token,
    session_start_time: sessionStartTime.toISOString(),
    session_end_time: sessionEndTime.toISOString(),
    score: score,
    app_version: appVersion,
    language: language
  };

  // Get the subdomain from the current hostname
  const hostname = window.location.hostname;
  const parts = hostname.split('.');
  const subdomain = parts.length > 2 ? parts[0] : '';
  
  // REQUIRED: This exact endpoint must be called when a game session ends
  fetch(`/api/v1/games/${subdomain}/session-ended`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(sessionData)
  })
  .then(response => response.json())
  .then(data => {
    console.log("Session recorded successfully", data);
  })
  .catch(error => {
    console.error("Failed to record session", error);
  });
}

Testing Your Implementation

Before uploading, test your session tracking implementation:

Use our example implementation at /sdk/example-implementation.html as a reference
Add URL parameters to your local development URL (e.g., http://localhost:8000/index.html?token=test123&appVersion=1.0.0&language=en)
Use browser developer tools to verify network requests are being made correctly

In browser developer tools, check that the POST request to /api/v1/games/:subdomain/session-ended is being made with all required parameters.

Uploading to Jiran Games

Log in to Your Account

Create a New Game

Click on "Add New Game" and fill in the required information:

Game Name
Description
Game Logo (recommended size: 512x512px)
Tags (to help users find your game)
Subdomain (this will be your game's URL: yourgame.jiran.games)

Upload Your Game Bundle

Select the ZIP file containing your HTML5 game and upload it.

Note: Our system will validate that your ZIP file contains at least an index.html file and some JavaScript files.

Submit for Review

After uploading, your game will be marked as "pending_review". Our team will review it to ensure it meets our guidelines.

The review process typically takes 1-2 business days.