Skip to main content

overwolf.extensions API

Change or retrieve the information of an Overwolf app or respond to events in the app’s lifecycle.

Special Overwolf URLs​

You can use the following helpful URLs to retrieve an extension file content or icons:

  • overwolf://extension-resources/<extension uid>/icon
    A URL that can be used as a source for an IMG tag or a DIV background. This path will display the icon of the stated extension.

  • overwolf://extension-resources/<extension uid>/icon_gray
    A URL that can be used as a source for an IMG tag or a DIV background. This will present the gray icon of the stated extension.

  • overwolf-extension://<extension uid>/<path to extension file>
    Returns the content of a file in an app's library.

Methods Reference​

Events Reference​

Types Reference​

launch(uid, parameter)​

Version added: 0.78​

Launch an extension by unique ID.

ParameterTypeDescription
uidstringExtension unique ID
parameterObject (optional)A parameter passed to the extension. The extension may or may not use this parameter

Retrieve a service object by ID, which will usually provide external APIs.

ParameterTypeDescription
idstringService ID
callbackfunctionA function called with the service, if found, and a flag indicating success or failure

setInfo(info)​

Version added: 0.91​

Sets a string for other extensions to read.

ParameterTypeDescription
infoObjectAn object to post

getInfo(id, callback)​

Version added: 0.91​

Returns an extension’s info string.

ParameterTypeDescription
idstringID of the extension to get info for
callbackfunctionCalled with the info
callback(Result: GetInfoResult) => voidCalled with the info

registerInfo(id, eventsCallback, callback)​

Version added: 0.91​

Requests info updates for an extension. Will also be called when the extension launches or closes.

ParameterTypeDescription
idstringID of the extension to get updates for
eventsCallbackfunctionA callback to receive info updates
callback(Result) => voidReturns with the result

unregisterInfo(id, callback)​

Version added: 0.91​

Stop requesting info for an extension.

ParameterTypeDescription
idstringID of the extension to stop getting updates for
callback(Result) => voidReturns with the result

getManifest(id, callback)​

Version added: 0.91​

Returns the requested extension’s manifest object.

ParameterTypeDescription
idstringID of the extension to get the manifest for
callback(Result: GetManifestResult => void)Result of the request

getRunningState(id, callback)​

Version added: 0.91​

Gets the running state of an extension.

ParameterTypeDescription
idstringID of the extension to get updates for
callbackResult: GetRunningStateResult => void)
Result of the request

relaunch()​

Version added: 0.112​

Relaunch the current app.

updateExtension(callback)​

Version added: 0.133​

Attempts to download an update for the calling extension.

This function allows apps to check and perform an update without having to wait for Overwolf to do so automatically.

Please read our Recommended extension update flow.

ParameterTypeDescription
callback(Result: UpdateExtensionResult => voidResult of the request

failsafe note​

The update has a failsafe mechanism while the game is active, making sure automatic updates won't happen during play only if a user action is detected, like pressing a button, for example.

checkForExtensionUpdate(callback)​

Version added: 0.135​

Checks if an update is available for the calling extension.

The function always returns UpToDate when used on an unpacked extension.

This function allows the current app to check if there is an extension update, without having to wait for Overwolf to do so. Calling this function will not automatically update the extension, just checks if an update exists.

Please read our Recommended extension update flow.

ParameterTypeDescription
callback(Result: CheckForUpdateResult) => voidResult of the request

Note​

When releasing from the dev console a new version to production/testing environment, the checkForExtensionUpdate API will be "aware" of the new version after 2 hours or after Overwolf client restart.

getServiceConsumers(callback)​

Version added: 0.135​

return service providers manifest data.

ParameterTypeDescription
callback(Result: ServiceProvidersDataResult) => voidResult of the request

Data example​

Assuming the manifesr flag service_providers is this:

 "service_providers": {
     "nafihghfcpikebhfhdhljejkcifgbdahdhngepfb": {
       "whatever": "value"
     }
   },

The result of the call will be:

overwolf.extensions.getServiceConsumers(console.info);

// results in:
{
    "data":  {
      "hffhbjnafafjnehejohpkfhjdenpifhihebpkhni": "{'whatever':'value'}"
    },
    "success": true,
    "error" : null
}

onAppLaunchTriggered​

Version added: 0.92​

Fires when the current app is launched while already running. This is useful in the case where the app has custom logic for clicking its dock button while it is already running.

Note that this event is also fired when the app is set for auto-launch in the manifest. In this case, the "source" parameter value will be "gamelaunchevent".

The origin string​

The event returns an origin string which returns what triggered the app launch:

overwolf-extension://hffhbjnafafjnehejohpkfhjdenpifhihebpkhni/index.html?source=gamelaunchevent

The source param​

Possible values for the source parameter:

ParameterType
dockLaunched from the Overwolf dock
gamelauncheventAuto-launched along with a game
hotkeyLaunched in-game with a hotkey
storeapiLaunched from the store
odkLaunched with the overwolf.extensions.launch API
commandlineLaunched from the command line using overwolf.exe -launchapp [extension id]
trayLaunched from the tray
startupLaunched upon startup
after-installAuto-launched after installation
overwolfstartlauncheventAuto-launched with the client launch (when app auto-launch with Overwolf is enabled)
urlschemeLaunched from custom link. See the url_protocol manifest flag
tip

if you want to get origin information without registering events, you can run the window.location.href command.

onExtensionUpdated​

Version added: 0.138​

Fires when the current app's newest version has been installed. This most often means that an app relaunch is required in order for the update to apply.

onUncaughtException​

Version added: 0.133​

Called for global uncaught exceptions in a frame.

Event Data example​

The callback args return with all the available exception data:

{
"StartPosition": 4431,
"EndPosition": 4432,
"StartColumn": 4431,
"EndColumn": 4432,
"LineNumber": 1,
"Message": "Uncaught TypeError: Cannot read property 'length' of undefined",
"ScriptResourceName": "https://totalmedia2.ynet.co.il/gpt/gpt_script_ynet.js",
"SourceLine": "if(0!=dcLoadAds){var data_version={}"
}

GetInfoResult Object​

ParameterTypeDescription
successbooleaninherited from the "Result" Object
errorstringinherited from the "Result" Object
infostringThe extension info

Example data: Success​

GetRunningStateResult Object​

ParameterTypeDescription
successbooleaninherited from the "Result" Object
errorstringinherited from the "Result" Object
isRunningboolean

Example data: Success​

{ "status": "success", "isRunning": true }

ServiceProvidersDataResult Object​

ParameterTypeDescription
successbooleaninherited from the "Result" Object
errorstringinherited from the "Result" Object
dataobject

Example data: Success​

{
    "data": {
    "hffhbjnafafjnehejohpkfhjdenpifhihebpkhni": "{'whatever':'value'}"
    },
    "success": true,
    "error": null
}

UpdateExtensionResult Object​

ParameterTypeDescription
successbooleaninherited from the "Result" Object
errorstringinherited from the "Result" Object
statestring
infostring
versionstring

Example data: Success​

{
 "success": true,
 "info": "new version 25.0.12 installed, restart app to apply."
}

Example data: Failure​

{
 "success": false,
 "error": "MinOverwolfVersionRequirementUnmet",
 "info": "Overwolf version 0.125.0.2 needs to be updated to 0.126.0.11"
}

Possible error messages​

Error CodeDescription
UnknownErrorerror before download starts
ExtensionNotFounderror before download starts
ExtensionDisablederror before download starts
GameRunningerror before download starts
PackageUpdaterUnavailableerror before download starts
MinOverwolfVersionRequirementUnmeterror before download starts
MinGepVersionRequirementUnmeterror before download starts
MinGameSummaryVersionRequirementUnmeterror before download starts
PackageInfoMissingerror before download starts
AlreadyUpToDateerror before download starts
AlreadyInstallederror after download starts
NoConnectivityerror after download starts
MissingExtensionIderror after download starts
InvalidInstallStateerror after download starts
InstallationErrorerror after download starts
AppNotInstallederror after download starts
DownloadErrorerror after download starts

CheckForUpdateResult Object​

ParameterTypeDescription
successbooleaninherited from the "Result" Object
errorstringinherited from the "Result" Object
statusstringdeprecated. For backward compatibility only
Reasonstringdeprecated. For backward compatibility only
stateExtensionUpdateState enumextension update state
updateVersionstringThe latest extension version on the OW apps store. null if the extension is up to date

Example data: Success​

Possible states are "UpdateAvailable", "UpToDate" or "PendingRestart".
For more info please read our Recommended extension update flow.

{"state": "UpdateAvailable", "updateVersion": "125.0.1", "success": true, "error": null}

{"state": "UpToDate", "updateVersion": null, "success": true, "error": null}

{"state": "PendingRestart", "updateVersion": "125.0.1", "success": true, "error": null}

ExtensionUpdateState enum​

OptionDescriptionNotes
UpToDateThe extension is up to date. No action items are required
UpdateAvailableThere is an updated extension version on the OW apps store
PendingRestartThe extension just updated, and it's waiting for a relaunch

This is the recommended flow for a manual update of Overwolf extensions.

NOTE: The call to checkForExtensionUpdate() will not work when the extension was loaded unpacked.

NOTE: that regardless, the auto-update mechanism will automatically fetch available updates from Overwolf servers every few hours, or once the Overwolf client is restarted. (that includes upgrades for all the available components: extensions, GEP, Client).

TL;DR The flow is UpdateAvailable => updateExtension() => relaunch().

  1. Once you get an UpdateAvailable state, You should offer the user an "Update" button.
    The button should call updateExtension().
    See also the failsafe note.

  2. Once the update successfully completed, you can call again checkForExtensionUpdate(),
    To make sure that the state changed to PendingRestart.

  3. At this point, an extension restart is required. You can offer the user a "Relaunch" button.
    The button should call relaunch().

  4. In a case that your app depends on a sequence of game events, to avoid any app-related flow issues, it's highly recommended to notify the user and ask for a game restart as well.

Note​

In order to test the manual update scenario without initiate auto-update immediately, please delete the folder %localappdata%\PackagesCache before calling updateExtension.