The Manifest file

The manifest.json file is the core configuration file for your Overwolf app. It defines essential app properties including metadata, permissions, window configuration, game targeting, and runtime behavior. The file is mandatory and must be located in the root folder of your app.

info

For a complete, working example of a manifest.json file, see the Overwolf sample app.

Minimum manifest.json example

This example shows a minimal, valid manifest.json file with required fields only:

{
    "manifest_version": 1,
    "type": "WebApp",
    "meta": {
        "name": "My App",
        "author": "My Company",
        "version": "1.0.0",
        "minimum-overwolf-version": "0.170.0",
        "description": "A brief description of my app",
        "icon": "assets/icon.png"
    },
    "data": {
        "start_window": "main",
        "windows": {
            "main": {
                "file": "index.html"
            }
        }
    }
}

note

This is the minimum required to pass schema validation. For Appstore submission you also need dock_button_title, icon_gray, launcher_icon, and window_icon — see the meta properties table for details.

Validate your manifest.json

To ensure your manifest file is correct and complete, validate it against the official schema. Read the schema validation best practices for detailed validation instructions.

Access the manifest from your app

You can read the manifest.json file from your app's code using the overwolf.extensions.getManifest() function.

Top-level manifest properties

These are the primary properties defined at the root level of your manifest file:

Property	Type	Required	Description	Version
manifest_version	integer	✓	Specifies the manifest schema version. Currently always 1.	0.78
type	string	✓	App type declaration. Currently only "WebApp" is supported.	0.78
meta	Meta Object	✓	App metadata including name, version, author, and icon information.	0.78
permissions	string[]		Array of permission strings required by the app.	0.78
data	WebApp Settings Object	✓	App configuration including windows, game targeting, and behavior settings.	0.78
max_rotation_log_files	integer		Log file rotation limit (10-40, defaults to 10). Higher values store more log history.	0.78

Permissions array

To access most Overwolf APIs, your app must declare the required permissions in the manifest. The Overwolf client will request user approval for sensitive permissions.

"permissions": ["Streaming", "Hotkeys", "GameInfo"]

Permission	Description	Required for API
Camera	Access to webcam devices	Camera APIs
Microphone	Access to microphone devices	Audio capture APIs
Logging	Deprecated - Access to overwolf.log API	overwolf.log
Extensions	Launch or retrieve information about other Overwolf apps	overwolf.extensions
Streaming	Enable game streaming functionality	overwolf.streaming
DesktopStreaming	Enable desktop streaming (streaming desktop content)	overwolf.streaming
Profile	Access user profile information and perform login/account actions	overwolf.profile
Clipboard	Read/write clipboard content	overwolf.utils.Clipboard
Hotkeys	Register and respond to hotkey combinations	overwolf.settings.hotkeys
Media	Access media library (videos, screenshots)	overwolf.media
GameInfo	Get current game information and ID	overwolf.games
GameControl	Send keyboard input to the game (requires overwolf.utils.sendKeyStroke())	overwolf.utils
FileSystem	Access local file system (only enforced permission)	overwolf.io
LogitechLed	Access Logitech LED hardware	overwolf.logitech.led
LogitechArx	Access Logitech ARX hardware	overwolf.logitech.arx
OwWebview	Allow the app to use Overwolf's built-in web view components (e.g. for rendering embedded web content in a managed iframe).	Overwolf web views
VideoCaptureSettings	Appear as video capture extension in Overwolf settings; configure capture settings	overwolf.streaming
Web	Access external web APIs	overwolf.web
Tray	Create and manage system tray icons	overwolf.os.tray

Meta object

The meta object contains essential metadata about your app, including branding, versioning, and icon assets.

Meta properties

✓ = required for the app to function. Store = optional technically, but required for Overwolf Appstore submission.

Property	Type	Required	Description	Version
name	string	✓	Your app's name. Note: This is used (along with author) to generate a unique app ID that cannot be changed after publishing.	0.78
author	string	✓	The developer/company name. Note: Used to generate unique app ID.	0.78
version	string	✓	Current app version. Format: X.X.X or X.X.X.X (up to 4 dot-separated integers). Examples: "1", "1.0", "2.11.3", "4.1.2.345"	0.78
minimum-overwolf-version	string	✓	Minimum Overwolf client version required. Format: same as version. Important: Use only released versions to avoid user compatibility issues.	0.78
minimum-gep-version	string		Minimum Game Events Provider version required. Format: same as version. Only set if your app uses game event data.	0.134
minimum-gs-version	string		Minimum Game Summary (GS) version required. Format: same as version. Only set this if your app integrates with or depends on the Game Summary feature.	—
description	string	✓	Short app description for the Overwolf Appstore. Limited to 180 characters.	0.78
dock_button_title	string	Store	Short name displayed in the Overwolf dock. Maximum 18 characters.	0.79
author_display	string		Override the displayed author name (useful if you want to hide the actual author name). If not set, author field is displayed.	0.78
icon	string	✓	Relative path to the main app icon (colored, multi-colored version). Shown in dock on hover. Format: PNG, 256×256px at 72 PPI, resized to 37×37px, max 30KB.	0.78
icon_gray	string	Store	Relative path to the grayscale icon (default state). Shown in dock when not hovered. Format: PNG, 256×256px at 72 PPI, resized to 37×37px, max 30KB.	0.78
launcher_icon	string	Store	Relative path to the desktop shortcut icon. Format: ICO file. This is the colored icon for the Windows desktop shortcut.	0.78
tray_icon	string		Relative path to the system tray icon. Format: ICO file. Defaults to launcher_icon if not specified.	0.201
splash_image	string		Relative path to the splash/loading screen image. Format: PNG, 256×256px. If omitted, the icon image will be used.	0.116
window_icon	string	Store	Relative path to the window title bar and taskbar icon. Format: PNG, 256×256px.	0.116

App ID Generation

Each Overwolf app has a unique ID (UID) generated from the name and author fields. Once published, this UID cannot be changed. Choose these values carefully before submission. You can use author_display to hide the actual author name if needed.

WebApp settings object

The data object contains all runtime configuration for your app, including windows, game targeting, permissions, and special behaviors.

Top-level data properties

Property	Type	Required	Description	Version
game_targeting	GameTargeting Object		Declare which games your app targets (all, dedicated, or none).	0.78
start_window	string	✓	Name of the window to load on app startup (must match a window defined in windows).	0.78
request_referrer_force	RequestReferrerForce[]		Array of rules to force specific HTTP Referer headers for requests.	0.78
windows	ExtensionWindowData Object	✓	Map of window definitions ("windowName": {...}). At least one window must be defined.	0.78
enable_top_isolated_sites_console	boolean		Enable/disable console logging for ads and isolated content. Default: false.	0.115
externally_connectable	ExternallyConnectable Object		Define external URLs/domains the app can communicate with. Enables CORS and postMessage.	0.78
protocol_override_domains	ProtocolOverrideDomains Object		Override relative protocols (e.g., //cdn.example.com) with explicit protocols (https, http).	0.78
force_browser	string		Force links to open in user's default browser ("user") or Overwolf's browser ("overwolf").	0.91
enable_osr_acceleration	boolean		Deprecated - Enable OSR/GPU acceleration. No longer supported or maintained.	0.126
game_events	integer[]		Array of game IDs that require real-time game event data. See Game IDs list.	0.92
disable_log_limit	boolean		Disable the 1000-line log file limit. Only enable with Overwolf approval.	0.12
extra-objects	ExtraObjects Object		Define custom plugin DLLs to load. See Overwolf plugins.	0.81
hotkeys	Hotkeys Object		Define hotkey/keybind combinations that trigger app actions.	0.78
content_scripts	ContentScript[]		Array of JavaScript/CSS files to inject into specific windows or URLs.	0.78
launch_events	LaunchEvent[]		Array of events that automatically launch the app (e.g., GameLaunch, LaunchWithOverwolf).	0.82
disable_dt	boolean		Disable opening developer tools with Ctrl+Shift+I. Default: false.	0.118
service_providers	ServiceProviders Object		Flexible data for external service providers (e.g., Game Summary extensions).	0.137
developer	DeveloperSettings Object		Development-only settings (auto-reload, file watching). Only active in dev mode or unpacked extensions.	0.127
disable_cleanup	boolean		Prevent app's localStorage from being deleted on uninstall. Default: false.	0.147
process_name	string		Custom process name shown in Task Manager (instead of default OverwolfBrowser.exe). Defaults to app name.	0.153
logging	Logging Object		Configure console log filtering for external domains/iframes.	0.217
url_protocol	UrlProtocol Object		Define custom URL schemes to launch your app from browser links (e.g., myapp://action).	0.236
uninstall_window	UninstallWindow Object		Define a window to run during uninstall for cleanup tasks.	0.187
auto_relaunch_on_crash	boolean		Automatically relaunch the app if it crashes (up to 7 consecutive crashes). Default: false.	0.191

Game targeting object

Declare which games your app targets. This determines where your app can show overlays and receive game data.

Property	Type	Required	Description	Version
type	string	✓	Targeting scope: "all" (all games), "dedicated" (specific games), or "none" (no games).	0.78
game_ids	integer[]	(if type: "dedicated")	Array of game IDs your app supports. Wildcard * not supported.	0.78

Example:

"game_targeting": {
    "type": "dedicated",
    "game_ids": [5426, 7764]  // League of Legends, CSGO
}

info

• Set game_events array if your app needs real-time game events for these games.
• Set launch_events if your app should auto-launch when these games start.

Request referrer force object

Force specific HTTP Referer headers for matching requests. Useful when external APIs require specific referer values.

Property	Type	Description
rule	string	URL pattern or link to match (regex supported). Can match videos, images, APIs, etc.
domain	string	Domain to report as the forced Referer header for matching requests.

Example:

"request_referrer_force": [
    {
        "rule": "https://api.example.com/data",
        "domain": "example.com"
    },
    {
        "rule": "https://cdn.*.example.com/*",
        "domain": "cdn.example.com"
    }
]

Extension window data object

Configuration for each window in your app. Define one or more windows in the windows object.

Window basics

Property	Type	Required	Description	Version
file	string	✓	Points to a local HTML file to be loaded inside the window. If you wish to host your app in a remote web-site, you'll have to have a local page that redirects to that remote website. In such cases, you need to make sure that the block_top_window_navigation property is set to false.	0.78
show_in_taskbar	boolean		Show/hide in Windows taskbar and Alt+Tab. Default: true.	0.78
transparent	boolean		Enable transparent/borderless window. Parts with background: transparent; CSS become see-through. Default: false.	0.78
override_on_update	boolean		Reset window size/location/opacity to manifest values after app update. Default: false.	0.119
resizable	boolean		Allow user to resize window. Default: true.	0.78
show_minimize	boolean		Show minimize button (non-transparent windows only). Default: true.	0.79
show_maximize	boolean		Show maximize button (non-transparent windows only). Default: false.	0.106
clickthrough	boolean		Window ignores clicks; passes them to game instead. Default: false.	0.80
style	string		Input behavior: "inputPassThrough" allows both window and game to receive input simultaneously.	0.174
disable_rightclick	boolean		Disable right-click entirely for this window. Default: false.	0.92
isInputPassThrough	boolean		Makes an overlay window invisible to mouse and keyboard interactions, allowing all user clicks and keystrokes to pass straight through it to the game running underneath. Default false.

Window visibility & streaming

Property	Type	Description	Version
forcecapture	boolean	Always include in game recordings, overriding user settings. Default: false.	0.78
show_only_on_stream	boolean	Only visible in stream/recording, not to streamer. Default: false.	0.78
show_background_layer	boolean	Show black overlay behind window when visible. Default: false.	0.280

Keyboard & focus behavior

Property	Type	Description	Version
ignore_keyboard_events	boolean	Window ignores keyboard input; passes keys to game. Default: false.	0.83
grab_keyboard_focus	boolean	In-game window steals keyboard focus on open. Default: false.	0.82
grab_focus_on_desktop	boolean	Desktop window grabs focus on open. Default: true.	0.99
focus_game_takeover	string	Control exclusive mode behavior: "ReleaseOnHidden" or "ReleaseOnLostFocus". See exclusive mode guide.	0.107
focus_game_takeover_release_hotkey	string	Hotkey name to display when entering exclusive mode. Only with focus_game_takeover: "ReleaseOnHidden".	0.110
is_alt_f4_blocked	boolean	Block Alt+F4 closing. Triggers onAltF4Blocked event. Default: false.	0.113

Size & positioning

Property	Type	Description	Version
size	Size Object	Initial window dimensions in pixels. Resizable windows remember size on close.	0.78
min_size	Size Object	Minimum window size. Default: 100×100. Set to 0×0 for smaller windows.	0.78
max_size	Size Object	Maximum window size.	0.78
start_position	Point Object	Initial window position (pixels from top-left).	0.78
topmost	boolean	Window always on top of other Overwolf windows. Use carefully. Default: false.	0.89
bottommost	boolean	Window always behind other Overwolf windows. Use carefully. Default: false.	0.180
keep_window_location	boolean	Prevent window from moving when game focus changes. Default: false.	0.101
restrict_to_game_bounds	boolean	Keep window within game window bounds while dragging. Default: false.	0.158

Game window specific

Property	Type	Description	Version
in_game_only	boolean	Window only accessible while in-game (not on desktop). Default: false.	0.78
desktop_only	boolean	Window only on desktop (not in-game). Required for native_window: true. Default: false.	0.89
disable_restore_animation	boolean	Disable minimize/restore animation in-game. Default: false.	0.89
use_os_windowing	boolean	Enable OS maximize (full-screen) and taskbar minimize. Only with desktop_only: true. Default: false.	0.102

Performance & rendering

Property	Type	Description	Version
background_optimization	boolean	Enable JS engine background optimization. Default: true.	0.103
mute	boolean	Mute sounds in this window. Default: false.	0.102
mute_excluded_hosts	string[]	Hosts that play sound even when mute: true. Example: ["youtube.com", "twitch.tv"].	0.103
popup_blocker	boolean	Block automatic popup windows opened via JavaScript. Default: true.	0.103
disable_blur	boolean	Window never loses focus; onblur never fires. Default: false.	0.106
native_window	boolean	Use native CEF window for better performance. Only with desktop_only: true. Default: false.	0.107
disable_hardware_acceleration	boolean	Disable GPU acceleration. Default: false. Note: Use this flag mainly for native windows that run as a second-screen with fps intensive games. It improves the performance of the game by reducing usage of the GPU while you are playing.	0.159

Advanced settings

Property	Type	Description	Version
is_background_page	boolean	This flag MUST be used with background/hidden controller windows. Note: With this flag set to true, there's no need to set window related properties such as size, focus, transparency, etc. Default: false.	0.107
allow_local_file_access	boolean	Allow accessing files outside app folder. Default: false.	0.109
block_top_window_navigation	boolean	Prevent non-target="_blank" links from taking over the whole window. Default: true.	0.100
disable_auto_dpi_sizing	boolean	Disable DPI-aware sizing (native windows only). Default: false.	0.148
dev_tools_window_style	boolean	Open dev tools in a separate window. Default: false.	0.117
debug_url	string	Local server URL for debugging (e.g., http://localhost:3000). Only for unpacked extensions and localhost/127.0.0.1.	0.127
optimize_accelerate_rendering	boolean	Deprecated - Enable accelerated rendering. Not supported.	0.127
dpi_unaware	boolean	Manage in-game windows without DPI calculations. Default: false.	—
open_dev_tools	boolean	Auto-open dev tools when window opens (for debugging). Default: false.	0.191
enable_top_isolation	boolean	Runs this window in isolated iframe process, so if some iframe is misbehaving (e.g. memory leak, etc.) it won't crash your app and will only crash the iframe process. Useful with Overwolf ads that run in an iframe. Default: true (from parent setting).	0.110

Externally connectable object

Define external URLs your app can communicate with. Enables CORS requests and postMessage() with iframes.

Property	Type	Description
matches	string[]	Array of URL patterns to allow. Supports * for subdomain matching.

Important notes:

• Use * to match any subdomain: https://*.example.com
• Do NOT include trailing slashes: https://example.com ✓ (not https://example.com/)

Example:

"externally_connectable": {
    "matches": [
        "http://*.mysite.com",
        "https://*.mysecuredsite.com",
        "https://api.google.com",
        "my-protocol://"
    ]
}

Protocol override domains object

Overwolf apps run under a custom URL protocol and domain (www.overwolf.com://[app-id]). This means that protocol-relative URLs (e.g. //ajax.googleapis.com/…) will try to load from the Overwolf app protocol. Unless you want this to happen, you can use protocol_override_domains to override the relative protocol with a preferred one (e.g. https or http).

Example:

"protocol_override_domains": {
    "ajax.googleapis.com": "https",
    "cdn.example.com": "http"
}

Game events array

Array of game IDs for which real-time game events are required. See complete game IDs list.

"game_events": [7764, 5426, 7314]  // CSGO, League, Dota 2

warning

• Wildcards not supported - list all game IDs explicitly.
• Use with game_targeting if you need overlay windows.
• Use with launch_events if you want auto-launch.

Extra objects object

Define custom native plugin DLLs. See Overwolf plugins repo.

Property	Type	Description
file	string	Relative path to plugin DLL file.
class	string	Namespace entry point (class path) in the DLL.

Example:

"extra-objects": {
    "my-plugin": {
        "file": "plugins/my_plugin.dll",
        "class": "MyPlugin.EntryPoint"
    },
    "simple-io-plugin": {
        "file": "plugins/simple-io-plugin.dll",
        "class": "overwolf.plugins.simpleio.SimpleIOPlugin"
    }
}

Access from your app:

overwolf.extensions.current.getExtraObject("my-plugin", callback);

Hotkeys object

Define keyboard shortcuts that trigger app actions. See hotkeys best practices guide.

Property	Type	Required	Description	Version
title	string	✓	Display name in Hotkey settings.	0.78
action-type	string		"toggle" or "custom". Default: "custom".	0.78
default	string		Default key combination (e.g., "Shift+F9", "Ctrl+Shift+F9").	0.78
passthrough	boolean		Allow keys to pass through to game. Default: false.	0.78
custom_modifier_key	number		Custom modifier key code (e.g., 192 for backtick).	0.208
game_ids	number[]		Restrict hotkey to specific games.	0.221
hold	boolean		Fire event while key is held (not just on press). Default: false.	0.142

Example:

"hotkeys": {
    "show_overlay": {
        "title": "Show Overlay",
        "action-type": "custom",
        "default": "Shift+F9",
        "passthrough": true
    },
    "save_clip": {
        "title": "Save Clip",
        "action-type": "custom",
        "default": "Ctrl+Shift+S"
    },
    "league_hotkey": {
        "title": "League Command",
        "action-type": "custom",
        "default": "Ctrl+G",
        "game_ids": [5426]  // League only
    }
}

Content scripts array

Inject JavaScript/CSS files into specific windows or external URLs.

Property	Type	Description
windows	string[]	Window names to inject into.
matches	string[]	URL patterns to inject into (regex supported).
js	string[]	JavaScript files to inject.
css	string[]	CSS files to inject.

Example:

"content_scripts": [
    {
        "windows": ["main"],
        "js": ["scripts/main.js"],
        "css": ["styles/main.css"]
    },
    {
        "matches": ["https://google.com/"],
        "js": ["scripts/google.js"]
    }
]

Works with iframes hosted in Overwolf windows as well.

Launch events array

Automatically launch your app when specific events occur. To enable auto-launch, add a launch_events array to your data object and define at least one event. The app will launch automatically whenever that event fires — no user interaction required.

Enable app auto-launch

Set "event": "GameLaunch" with the relevant game_ids to auto-launch when a specific game starts. Use "LaunchWithOverwolf" to launch whenever Overwolf itself starts.

Property	Type	Required	Description	Version
event	enum	✓	One of: "GameLaunch", "AllGamesLaunch", or "LaunchWithOverwolf". Only these fixed values are accepted.	0.82
event_data	LaunchEventData Object		Game IDs and framerate requirements.	0.82
include_launchers	boolean		Launch when game launcher detected (with AllGamesLaunch). Default: false.	0.103
tracked	boolean		Launch when game ID detected (even without injection). Default: false.	0.132
track_all_games	boolean		With tracked: true, launch for all games including "Unsupported". Default: false.	0.195
start_minimized	boolean		Start app window minimized. Default: false.	0.82

Example:

"launch_events": [
    {
        "event": "GameLaunch",
        "event_data": {
            "game_ids": [5426],
            "wait_for_stable_framerate": 30
        },
        "start_minimized": true
    },
    {
        "event": "LaunchWithOverwolf"  // Launch when Overwolf starts
    }
]

LaunchWithOverwolf important notes

warning

If your app uses "LaunchWithOverwolf", it must not show any windows until:

• A game is launched, OR
• User explicitly opts in, with clear opt-out option

Launch event object

Property	Type	Description
game_ids	integer[]	Game IDs that trigger launch.
wait_for_stable_framerate	integer	Wait until game reaches this FPS before launching.

Developer settings object

Development-only settings for auto-reloading and file watching. Only active in dev mode or with unpacked extensions.

Property	Type	Default	Description	Version
enable_auto_refresh	boolean	true	Auto-reload app when files change.	0.127
reload_delay	integer	1000	Delay (ms) before reloading on file changes.	0.127
filter	string	*.*	File pattern to watch (e.g., *.json;*.html).	0.127

Example:

"developer": {
    "enable_auto_refresh": true,
    "reload_delay": 2000,
    "filter": "*.json;*.html;*.ts"
}

Service providers object

Provide flexible data to external service providers (other Overwolf apps). Wrap data with the target service provider's UID.

Example:

"service_providers": {
    "nafihghfcpikebhfhdhljejkcifgbdahdhngepfb": {  // Game Summary UID
        "custom_setting": "value",
        "another_prop": 123
    }
}

Logging object

Configure console log filtering to exclude external domain logs.

Property	Type	Description
allowed_domains	string[]	Domains allowed to log. No wildcards.
ignore_externally_connectable	boolean	Block all externally_connectable domains. Default: false.
disable_blocking	boolean	Disable all log filtering. Default: false.

info

content.overwolf.com and google-analytics.com are always blocked unless disable_blocking: true.

Example:

"logging": {
    "allowed_domains": ["api.mysite.com", "cdn.mysite.com"],
    "ignore_externally_connectable": false,
    "disable_blocking": false
}

URL protocol object

Define custom URL schemes to launch your app from external links.

Property	Type	Deprecated?	Description	Version
scheme	string	✓ Yes	Deprecated - use schemes instead.	0.158
schemes	string[]		Array of custom URL schemes (e.g., ["myapp", "myapp-action"]).	0.236

Example:

"url_protocol": {
    "schemes": ["outplayed", "outplayed-highlight"]
}

This enables links like:

• outplayed://watch/12345
• outplayed-highlight://game/csgo

URL launch behavior

• App closed: Custom link launches app.
• Overwolf closed: Custom link launches Overwolf + app.
• App open: Custom link fires onAppLaunchTriggered event with "urlscheme" origin.

Extra parameters passed in URL appear in onAppLaunchTriggered event:

{ origin: "urlscheme", parameter: "outplayed%3a%2f%2fsomething" }

Uninstall window object

Define a window to run during app uninstallation. Typically used for cleanup (removing DLLs, files, etc.) or showing an uninstall survey.

Property	Type	Required	Description	Version
file	string	✓	HTML file to load. Window runs in background.	0.187
required_runtime	integer		How long to keep running (ms). Default: 10000 (10s). Max: 60000 (1 minute).	0.187

Important:

• Window runs in background - don't show UI.
• Can open browser for surveys.
• Prevents uninstall until runtime expires.

Example:

"uninstall_window": {
    "file": "uninstall.html",
    "required_runtime": 5000  // 5 seconds
}

Supporting objects

Size object

Defines width and height in pixels.

"size": {
    "width": 800,
    "height": 600
}

Point object

Defines top-left position in pixels.

"start_position": {
    "top": 100,
    "left": 200
}

Best practices

1. Always validate your manifest against the schema before submission.
2. Test with multiple Overwolf versions - ensure compatibility with your minimum-overwolf-version.
3. Minimize permissions - request only what your app needs.
4. Use proper icon dimensions - 256×256 PNG at 72 PPI for best results.
5. Set realistic version numbers - use semantic versioning (X.X.X).
6. Keep descriptions under 180 characters for app store compatibility.
7. Test window behavior on both desktop and in-game contexts.
8. Document custom hotkeys for users in your app's settings.