Developer Docs

JSON Import Blueprint

Automate content onboarding with our structured JSON importer. This guide outlines the schema, tooling, and QA steps required to batch load HTML5 games into sheworldbest.

Payload schema

`title`

Requirement: String, 80 characters max. Required.

Notes: Displayed on cards, SEO snippets, and leaderboard listings.

`category`

Requirement: String, must match one of our active taxonomy slugs (e.g., action, puzzle). Required.

Notes: Used to populate category hubs and faceted navigation.

`iframe_url`

Requirement: Valid HTTPS URL. Required when remote hosting.

Notes: If omitted, provide `file_path` for local uploads instead.

`thumbnail`

Requirement: HTTPS image URL or base64 data URI. Required.

Notes: We auto-store it under /thumbs/ when importing.

`with_ads_flag`

Requirement: Boolean. Optional.

Notes: Set true for titles containing internal ad breaks so we can balance on-site placements.

Developer preparing JSON payload for game imports

Sample payload

[
    {
        "title": "Neon Drift Rally",
        "category": "racing",
        "description": "Slide through neon-soaked city circuits. Master boost timing to reach the hall of fame.",
        "iframe_url": "https://cdn.example.com/games/neon-drift/index.html",
        "thumbnail": "https://cdn.example.com/thumbs/neon-drift.jpg",
        "tags": [
            "racing",
            "retro",
            "drift"
        ],
        "with_ads_flag": true
    },
    {
        "title": "Meteor Shield",
        "category": "arcade",
        "description": "Defend orbital stations with precision taps and chain combos.",
        "iframe_url": "https://cdn.example.com/games/meteor-shield/index.html",
        "thumbnail": "https://cdn.example.com/thumbs/meteor-shield.jpg",
        "feature": false
    }
]

Need a template? Download the starter bundle from the remote add toolkit and update the values above.

Import workflow

Upload JSON bundle

Place your payload under /admin/uploads/imports/ or provide a remote URL accessible to PHP. Files up to 5 MB are accepted.

Run the importer script

Execute php admin/import_json.php --file=/path/to/payload.json. The script validates schema, downloads thumbnails, and writes to games + language tables.

Review the log output

Success entries echo new game IDs. Warnings highlight missing thumbnails or duplicate titles. Re-run with --dry-run to test mapping without committing.

Validate before you load

Run the importer with --dry-run to preview insert counts, thumbnail downloads, and monetisation flags. Pair it with scheduled fetches from the auto-fetch pipeline for end-to-end automation.

Request onboarding support