manifest.json

Welcome to the manifest.json file

This JSON-formatted file is responsible for describing the aspects of your app. This ranges from the name of the app and its author to the size of the window or if it is transparent. This is a mandatory file for all apps and has to exist in the root folder for your app. Here is the base version of the manifest.json
{
    "manifest_version": 1,
    "type": "WebAp",
    "meta": {
        "name": "Demo_App",
        "version": "1.0.0",
        "author": "Developer_Name",
        "icon": "IconMouseOver.png",
        "icon_gray": "IconMouseNormal.png",
        "description": "Demo App"
    },
    "data": {
        "start_window": "MainWindow",
        "windows": {
    	    "MainWindow": {
                "file": "Files/index.html",
                "transparent": true,
                "resizable": true,
                "size": {"width": 400, "height": 300},
                "min_size": {"width": 200, "height": 200},
                "max_size": {"width": 600, "height": 500}
            }
        }
    }
}

 

Field summary

The following code shows the supported manifest fields for Overwolf apps, with links to the section that discusses each field.

{
    //Mandatory
    "manifest_version": 1,
    "type": "WebApp",
    //Mandatory, The app metadata
    "meta": {
        "name": "Name of your app",
        "dock_button_title": "Short name of your app",
        "version": "versionString",
        "minimum-overwolf-version": "versionString",
        "author": "Author name",
        "icon": "icon.png",
        "icon_gray": "icon_gray.png",
        "description": "A plain text description"
    },
    //An array of permissions that the app requires
    "permissions": [...],
    //Mandatory, a list of additional meta-data on the app.
    "data": {
	//A map from window names to window settings
	"windows": {
            "windowName": {
                //Mandatory. Points to the file to be loaded inside the window
		"file": "name.html",
                "show_in_taskbar": true,
                "transparent": true,
                "resizable": false,
                "show_minimize": true,
                "clickthrough": false,
                "disable_rightclick": false,
                "forcecapture": false,
                "show_only_on_stream": false,
                "ignore_keyboard_events": false,
                "in_game_only": false,
                "desktop_only": false,
                "disable_restore_animation": false,
                "grab_keyboard_focus": false,
                "size": {...},
		"min_size": {...},
		"max_size": {...},
                "start_position": {...},
                "topmost": false,
		"block_top_window_navigation": true,
		"keep_window_location": true,
		"use_os_windowing": false,
		"background_optimization": true,
                "mute": true,
                "mute_excluded_hosts": ["..."],
                "popup_blocker": false
            },
	//The name of the window (from the “windows” list) initially loaded when the app starts
	"start_window": "windowName",
	//External URLs the web app should be able to access
        "externally_connectable": {
            "matches": [...]
        },
	//Override the relative protocol with a preferred one
        "protocol_override_domains": {"url.com": "http"},
	//Causes links in the app to be opened using the user’s default browser ("user") or Overwolf’s browser ("overwolf")
        "force_browser": "user"/"overwolf",
	//A list of game ids for which game events are required
	"game_events": [...],
	//Allows the access of custom plugin dlls
        "extra-objects": {...},
	//Hotkey feature name and it’s settings
        "hotkeys": {...},
	//A list of content scripts to be loaded for specific windows
        "content_scripts": [...],
	//A list of events causing the app to launch
        "launch_events": [...],
        "user_agent": null
        }
    }
}

Validate your manifest.json

To help you make sure that your manifest file is correct and complete, validate it against this schema file.

  1. Go to www.jsonschemavalidator.net
  2. Copy-paste the schema’s and your manifest.json code into the “Schema” and “Input JSON” windows, respectively.
  3. Check for any errors or missing data.

Technical information about the manifest.json

There are many features that are enabled through this file. Some are mandatory (marked accordingly), and others are optional. Here is a description of the many features you can activate through the manifest.json

Name Type Description Since
manifest_version int Mandatory. Targets the manifest version you are working on. Currently there is only one version, therefore this value is always “1”. 0.78
type string Mandatory. Declares the type of application. Can only be “WebApp”. 0.78
meta App Metadata Mandatory. The app metadata. See documentation below. 0.78
permissions Permission Options An array of permissions that the app requires.
"permissions": ["Streaming","Hotkeys","GameInfo"]
0.83
data object Mandatory. App data. Changes between different apps types. Currently can only be webapp settings. 0.78

Permissions Options

To use most overwolf.* APIs, your Overwolf app must declare its intent in the permissions field of the manifest.json

Permission Description
"Camera" Access the webcam
"Microphone" Access the microphone
"Logging" Access the logging system APIs
"Extensions" Run or get information about other apps
"Streaming" Enable game streaming
"DesktopStreaming" Enable desktop streaming
"Profile" Access profile information and perform actions such as login and modifications
"Clipboard" Access the clipboard
"Hotkeys" Get hotkeys information for the current app
"Media" Access the media library
"GameInfo" Access current game information
"GameControl" Allows controlling the game through the app
"FileSystem" Allows accessing files from the local file system
"LogitechLed" Allows accessing Logitech LED APIs
"LogitechArx" Allows accessing Logitech Arx APIs
"OwWebview" Allows using the owwebview tag

 

App Metadata

Name Type Description Since
name string Mandatory. Name of your app * 0.78
author string Mandatory. Who developed the app * 0.78
version Version

Mandatory. One to four dot-separated integers identifying the version of this app. Needs to be in the format of X.X.X where the X’s are numbers.
Here are some examples of valid versions:

  • "version": "1"
  • "version": "1.0"
  • "version": "2.11.3"
  • "version": "4.1.2.345"
0.78
minimum-overwolf-version Version Mandatory. Minimum version of the Overwolf Client with which the app is compatible. The format is similar to the version field. 0.78
description string Mandatory. The description of your app on the Appstore tile. Limited to 180 characters. 0.78
dock_button_title string Short name of your app. Provide a short title that will fit in the dock button area – 18 chars max. 0.79
icon string A relative path from the app folder to the icon’s png file. Mandatory. This is the mouse-over (multi-colored) version of the icon that will be displayed on the Overwolf dock. The icon dimensions should be 256×256 pixels. More details on app icons can be found here. 0.78
icon_gray string A relative path from the app folder to the icon’s png file. This is the grayscale version of the icon that will be displayed on the Overwolf dock. The icon dimensions should be 256×256 pixels. 0.78

* Each app has a unique id (UID) that is generated out of the “name” and “author” strings. Once an app is published on the Appstore, its UID can’t be changed, so please choose your app and author names wisely before submitting your app.  

App settings

A list of additional meta-data on the app.

Name Type Description Since
windows Map of string to WindowData

Mandatory. A map from window names to window settings.

Example:

"windows": {
            "index": {
                "file": "index.html",
                "show_in_taskbar": true,
                "transparent": true,
                "resizable": false,
                "show_minimize": true,
                "clickthrough": false,
                "use_os_windowing": false,
                "disable_rightclick": false,
                "forcecapture": false,
                "show_only_on_stream": false,
                "ignore_keyboard_events": false,
                "in_game_only": false,
                "desktop_only": false,
                "disable_restore_animation": false,
                "grab_keyboard_focus": false,
                "size": {
                    "width": 910,
                    "height": 560
                },
                "start_position": {
                    "top": 10,
                    "left": 10
                },
                "topmost": false
            }
        }
0.78
start_window string Mandatory. The name of the window (from the “windows” list) initially loaded when the app starts. 0.78
externally_connectable ExternallyConnectable A definition of external URLs the web app should be able to access. Read more here. 0.78
protocol_override_domains string Overwolf apps run under a custom url protocol and domain (overwolf-extension://[app-id]).
This means that protocol-relative urls (//ajax.googleapis.com…) will try to load from a 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/http). Example:
"protocol_override_domains" : {"ajax.googleapis.com": "https", "domain.com": "http"}

This will swap the overwolf-app protocol with https for ajax.googleapis.com domain requestsand with http for domain.com requests.

 
force_browser eOpenLinksInBrowser Causes links in the app to be opened using the user’s default browser or Overwolf’s browser. Takes ‘user’ and ‘overwolf’ (case insensitive). 0.91.200
game_events int[]

A list of game ids for which game events are required.

Example:

"game_events": [7764, 5426, 7314]
0.92.100
extra-objects string

Allows the access of custom plugin dlls – see https://github.com/overwolf/overwolf-plugins

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.SimpleIOPlugin"
   }
}

You then use overwolf.extensions.current.getExtraObject(“simple-io-plugin”, function…)
to get an instance.

0.81
hotkeys Map of string to hotkey The map between the hotkey feature name and it’s settings. 0.78
content_scripts content_script[]

A list of content scripts to be loaded for specific windows. For instance, for this json, when loading the index window, myscript.js will be loaded and when encountring https://google.com, mystyles.css and myscript2.js will be loaded.

Example:

"content_scripts": [ { "windows": [ "index" ], "js": [ "myscript.js" ] },
 { "matches": [ "https://google.com/" ], "css": [ "mystyles.css" ], "js": [ "myscript2.js" ] } ]
0.78
launch_events launch event settings[]

A list of events causing the app to launch. It is enough that one of the events will occur to launch the app.

Example:

"launch_events": [
    {
        "event": "GameLaunch",
        "event_data": {
            "game_ids": [1136]
        },
        "start_minimized": true
    }
]
0.82
user_agent string A custom user agent for the app to use when creating http requests. Note that using ‘navigator.userAgent’ will not return the custom user agent, but the default one. 0.86

App Window Data

Name Type Description Since
file string Mandatory. Points to the file to be loaded inside the window. 0.78
show_in_taskbar bool Define if the window is displayed in the Windows taskbar and alt-tab window selection menu. 0.78
transparent bool Indicates whether the window will be transparent and borderless. If set to false a standard Overwolf window will be created 0.78
resizable bool Indicates whether the window can be resized. 0.78
show_minimize bool Indicates whether to show the window minimize button. Only relevant when not in transparent mode. 0.79
clickthrough bool Indicates whether the window will not receive clicks in-game, instead, the clicks will be passed on to the game. 0.80
disable_rightclick bool When set to true, disable right clicks entirely for this window. 0.92.0
forcecapture bool Indicates whether this window should always be included in recordings, overriding any other setting. 0.78
show_only_on_stream bool Indicates whether this window is visible only in streams (not visible to the streamer), overriding any other setting. 0.78
ignore_keyboard_events bool Indicates whether the window will not receive keyboard events. Instead, the keyboard events will be passed on to the game. 0.83
in_game_only bool Indicates whether the window will be visible only in game and not on the desktop. 0.78
desktop_only bool Indicates whether the window will be visible only on the desktop and not while in game. 0.89.50
disable_restore_animation bool Indicates whether the window will animate on minimize/restore while in game. 0.89.50
grab_keyboard_focus bool Indicates whether the window will grab the keyboard focus automatically when it opens, or leave the keyboard focus untouched. 0.82
grab_focus_on_desktop bool Indicates whether the window will grab the focus automatically when it opens, or leave the focus untouched. Default value = true.
Only relevant when in the desktop – for in-game focus behavior, use “grab_keyboard_focus”. 
0.99
size size

Defines the size of the window in pixels.

"size": {"width": 400, "height": 300}
0.78
min_size size Defines the minimum size of the window in pixels. 0.78
max_size size Defines the maximum size of the window in pixels. 0.78
start_position point

The default start position of the window in pixels from the top left corner.

Example:

"start_position": {
                    "top": 10,
                    "left": 10
                }
0.78
topmost bool Indicates whether the window will be on top of other Overwolf windows. Handle with care as topmost windows can negatively impact user experience. 0.89.50
block_top_window_navigation bool Refrain from non _blank <a> elements from “taking-over” the entire app’s window  0.100.0
keep_window_location bool

Window location won’t be changed when game focus is changed

0.101.20
use_os_windowing bool

Note: Should only be used with desktop_only windows.

This flag – when set to true, allows your window to:

  1. have a full-screen maximize when calling the overwolf.windows.maximize function
  2. allow your window to have a real (task bar) minimize when calling overwolf.windows.minimize
0.102.1
background_optimization bool

Enables JS engine background optimization. Default value = true

0.103.3
mute bool Mute sounds in window 0.102.1
mute_excluded_hosts [string]

Excludes hosts list so a stream from these hosts origins will not get muted even if the window is on "mute": true

Example: "mute_excluded_hosts" : ["*.youtube.*", "*.twitch.*" ]

0.103.2
popup_blocker bool Prevents new browser windows being opened automatically using script. Default value = false 0.103.4

Externally Connectable

Use this to allow cross origin requests to your server from the app that runs in localhost (overwolf://). More info on CORS here.

Name Type Description Since
matches string[] Array of web page URL patterns to match with an external server URL. Use star (*) in place of subdomain to allow access to all subdomains.
"externally_connectable": {
    "matches": [
        "http://*.mysite.com",
        "https://*.mysecuredsite.com",
        "my-protocol://"
    ]
}
0.78

Hotkeys

Name Type Description Since
title string Mandatory. Name of the hotkey as it will appear in the Hotkey tab in the settings. 0.78
default string The default key combination. 0.78
action-type hotkey action type Defines the behavior of the hotkey. 0.78
passthrough bool Defines the behavior of the hotkey. 0.78

Example:

"hotkeys": {
      "replayhud_player": {
        "title": "Show Player",
        "action-type": "custom",
        "default": "Shift+F9"
      },
      "replayhud_save": {
        "title": "Save Replay for later",
        "action-type": "custom",
        "default": "Ctrl+Shift+F9"
      }
    }

Hotkey action-type options

  • toggle – Toggles application visibility (displayed/hidden). It will run and display the app if it isn’t running
  • custom – Defines a custom hotkey to be used by the app. It is up to the app to register the custom hotkeys and handle them. You will need to use the registerHotKey function to register the hotkey

ContentScript

Name Type Description
windows string The list of windows for which to apply this content script.
matches string The list of urls for which to apply this content script.
css string The list of css files to be applied in this content script.
js string The list of js files to be applied in this content script.

size

Defines a size (width and height) in pixels.

Name Type Description Since
width (optional) int Defines the width in pixels. 0.78
height (optional) int Defines the height in pixels. 0.78

point

Defines a top-left position in pixels.

Name Type Description Since
top (optional) int Defines the position in the Y axis from the top in pixels. 0.78
left (optional) int Defines the position in the X axis from the left in pixels. 0.78

launch event settings

Defines an event that launches the app in which it is defined.

Name Type Description Since
event launch event type The type name of the event. 0.82
event_data object The event data. 0.82
start_minimized bool The app’s main window will start minimized. 0.82
include_launchers bool The app will be launched when game launcher is detected. 0.103.2

Launch Event Type Options

GameLaunch
The event is fired when a game is launched. The specific game, if any, is defined in the EventData section, and its structure is defined in launch game event settings.

launch game event settings

Name Type Description Since
game_ids int[] The list of game class IDs for which the app will launch. 0.82
wait_for_stable_framerate (optional) int The app won’t start until the game’s framerate will stabilize around or above the stated framerate. 0.82

eOpenLinksInBrowser

Causes links in the app to be opened using the user’s default browser or Overwolf’s browser.

options 

(case insensitive)

  • ‘user’ – Links will be opened in the user’s default browser
  • ‘overwolf’ – Links will be opened in Overwolf browser