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
- overwolf.extensions.launch()
- overwolf.extensions.setInfo()
- overwolf.extensions.getInfo()
- overwolf.extensions.registerInfo()
- overwolf.extensions.unregisterInfo()
- overwolf.extensions.getRunningState()
- overwolf.extensions.getManifest()
- overwolf.extensions.relaunch()
- overwolf.extensions.updateExtension()
- overwolf.extensions.checkForExtensionUpdate()
- overwolf.extensions.getServiceConsumers()
Events Reference
- overwolf.extensions.onAppLaunchTriggered
- overwolf.extensions.onExtensionUpdated
- overwolf.extensions.onUncaughtException
Types Reference
- overwolf.extensions.CheckForUpdateResult Object
- overwolf.extensions.ExtensionUpdateState Enum
- overwolf.extensions.GetInfoResult Object
- overwolf.extensions.GetRunningStateResult Object
- overwolf.extensions.ServiceProvidersDataResult Object
launch(uid, parameter)
Version added: 0.78
Launch an extension by unique ID.
Parameter | Type | Description |
---|---|---|
uid | string | Extension unique ID |
parameter | Object (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.
Parameter | Type | Description |
---|---|---|
id | string | Service ID |
callback | function | A 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.
Parameter | Type | Description |
---|---|---|
info | Object | An object to post |
getInfo(id, callback)
Version added: 0.91
Returns an extension’s info string.
Parameter | Type | Description |
---|---|---|
id | string | ID of the extension to get info for |
callback | function | Called with the info |
callback | (Result: GetInfoResult) => void | Called 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.
Parameter | Type | Description |
---|---|---|
id | string | ID of the extension to get updates for |
eventsCallback | function | A callback to receive info updates |
callback | (Result) => void | Returns with the result |
unregisterInfo(id, callback)
Version added: 0.91
Stop requesting info for an extension.
Parameter | Type | Description |
---|---|---|
id | string | ID of the extension to stop getting updates for |
callback | (Result) => void | Returns with the result |
getManifest(id, callback)
Version added: 0.91
Returns the requested extension’s manifest object.
Parameter | Type | Description |
---|---|---|
id | string | ID 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.
Parameter | Type | Description |
---|---|---|
id | string | ID of the extension to get updates for |
callback | Result: 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.
Parameter | Type | Description |
---|---|---|
callback | (Result: UpdateExtensionResult => void | Result 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.
Parameter | Type | Description |
---|---|---|
callback | (Result: CheckForUpdateResult) => void | Result 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.
Parameter | Type | Description |
---|---|---|
callback | (Result: ServiceProvidersDataResult) => void | Result 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:
Parameter | Type |
---|---|
dock | Launched from the Overwolf dock |
gamelaunchevent | Auto-launched along with a game |
hotkey | Launched in-game with a hotkey |
storeapi | Launched from the store |
odk | Launched with the overwolf.extensions.launch API |
commandline | Launched from the command line using overwolf.exe -launchapp [extension id] |
tray | Launched from the tray |
startup | Launched upon startup |
after-install | Auto-launched after installation |
overwolfstartlaunchevent | Auto-launched with the client launch (when app auto-launch with Overwolf is enabled) |
urlscheme | Launched from custom link. See the url_protocol manifest flag |
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
Parameter | Type | Description |
---|---|---|
success | boolean | inherited from the "Result" Object |
error | string | inherited from the "Result" Object |
info | string | The extension info |
Example data: Success
GetRunningStateResult Object
Parameter | Type | Description |
---|---|---|
success | boolean | inherited from the "Result" Object |
error | string | inherited from the "Result" Object |
isRunning | boolean |
Example data: Success
{ "status": "success", "isRunning": true }
ServiceProvidersDataResult Object
Parameter | Type | Description |
---|---|---|
success | boolean | inherited from the "Result" Object |
error | string | inherited from the "Result" Object |
data | object |
Example data: Success
{
"data": {
"hffhbjnafafjnehejohpkfhjdenpifhihebpkhni": "{'whatever':'value'}"
},
"success": true,
"error": null
}
UpdateExtensionResult Object
Parameter | Type | Description |
---|---|---|
success | boolean | inherited from the "Result" Object |
error | string | inherited from the "Result" Object |
state | string | |
info | string | |
version | string |
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 Code | Description |
---|---|
UnknownError | error before download starts |
ExtensionNotFound | error before download starts |
ExtensionDisabled | error before download starts |
GameRunning | error before download starts |
PackageUpdaterUnavailable | error before download starts |
MinOverwolfVersionRequirementUnmet | error before download starts |
MinGepVersionRequirementUnmet | error before download starts |
MinGameSummaryVersionRequirementUnmet | error before download starts |
PackageInfoMissing | error before download starts |
AlreadyUpToDate | error before download starts |
AlreadyInstalled | error after download starts |
NoConnectivity | error after download starts |
MissingExtensionId | error after download starts |
InvalidInstallState | error after download starts |
InstallationError | error after download starts |
AppNotInstalled | error after download starts |
DownloadError | error after download starts |
CheckForUpdateResult Object
Parameter | Type | Description |
---|---|---|
success | boolean | inherited from the "Result" Object |
error | string | inherited from the "Result" Object |
status | string | deprecated. For backward compatibility only |
Reason | string | deprecated. For backward compatibility only |
state | ExtensionUpdateState enum | extension update state |
updateVersion | string | The 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
Option | Description | Notes |
---|---|---|
UpToDate | The extension is up to date. No action items are required | |
UpdateAvailable | There is an updated extension version on the OW apps store | |
PendingRestart | The extension just updated, and it's waiting for a relaunch |
Recommended extension update flow
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()
.
-
Once you get an
UpdateAvailable
state, You should offer the user an "Update" button.
The button should call updateExtension().
See also the failsafe note. -
Once the update successfully completed, you can call again checkForExtensionUpdate(),
To make sure that the state changed toPendingRestart
. -
At this point, an extension restart is required. You can offer the user a "Relaunch" button.
The button should call relaunch(). -
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
.