Skip to content
This repository was archived by the owner on Sep 1, 2024. It is now read-only.

extensions.mdx

Latest commit

 

History

History
433 lines (310 loc) · 21.3 KB

extensions.mdx

File metadata and controls

433 lines (310 loc) · 21.3 KB
id extensions
image /img/embed/api-docs.jpg
title overwolf.extensions API
sidebar_custom_props
overwolf_platform electron_platform
true
false

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.

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 any game is active, which makes sure no updates are downloaded automatically whilst the user is playing. Only if the updateExtension() is called through a user action, like pressing a button for example, does it force the download.

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 process_name 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

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().


    

  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. 

  2. 

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

    3. 

  3. 

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

    4. 

  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.
    

    5. 



Note


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