Colorfulstan

api documentation
[collection] the missing parts

29 posts in this topic

Just starting to collect some things that are missing in the API documentation or quirks.
Feel free to join in, Ill try to keep it somewhat organized whenever I find something or find the time to integrate posts.
If there is interest in it, we might transition to a wiki which is a better format for something like this, but for now I just want to collect things in here and see if there is any interest.

Documentation Errors / Possible Pitfalls
API Quirks
overwolf.windows.sendMessage behaviour

 

07.07.2016

30.07.2016

  • API Quirks overwolf.windows.sendMessage() added
  • overwolf.games.onGameInfoUpdated bug added

31.07.2016

  • added overwolf.audio.media.create with url from overwolf.utils.openFilePicker (Thread from goodbyte) [Bug]

05.09.2016

  • Smite / Warface Event Documentation / Serialization errors added

07.09.2016

Edited by Colorfulstan

Share this post


Link to post
Share on other sites

Documentation Errors

overwolf.games.events.getInfo()

  • if object passed to callback has status 'error' there is another property 'reason' available to tell you more about the error

overwolf.extensions.showDevTools(appUID, windowName) [missing in documentation]

  • enables opening the dev-tools for a window programmatically

overwolf.extensions.launch(UID, parameters)

  • Missing documentation on how parameters can be used within the launched app

overwolf.extensions.getService(id, callback)

  • Documentation on how to define such a service and what built-in services are available

League of Legends

CS:GO

Warface

  • On 5.9.2016 at 3:38 AM, goodbyte said:
    • The list of Warface's events is incomplete, kill, sniper_down, shield_bearer_down are missing, among others...

Smite

  • overwolf.games.events.onNewEvents - invalid JSON as event data
    On 5.9.2016 at 3:04 PM, BobDev said:

    The reason for this is most likely that c# to string conversion.
    Try send a json using sendMessage that contains bool value, like {visible: true} you will find out that recipient window will get {visible: True} which is what you would get if you would do toString on bool object in c#. 

  •  

Possible Pitfalls

  • Window states not as expected in angular (not sure if applicable to other uses) [angular]
    When relying on a check for window-states in your Code, always make sure you wait for the next digest-cycle before checking the window-states. This might be related to having overwolf wrapped within a service but might be something to keep in mind anyways.
    Consider following angular scenario:
  • // owWindows is basically a wrapper around overwolf.windows
    // to offer promise-based handling of the methods and additional convenience methods
    owWindows.openAndWaitUntilClosed = function (windowName) {
      $log.debug('window.openAndWaitUntilClosed(): opening Window %s and waiting for it to close again', windowName);
      return $q(function (resolve, reject) {
    
      owWindows.open(windowName) // resolved when opening is successful, rejected otherwise
        .then(function WaitForClose(window) {
          var onStateChangeListener = function (/** ODKWindowStateChangedData */ stateChangedData) {
          if (stateChangedData.window_name === windowName && stateChangedData.window_state === 'closed') {
            $log.debug('window.openAndWaitUntilClosed(): Window got closed, resolving Promise');
            owWindows.onStateChanged(onStateChangeListener, true); // removes the listener
              resolve(stateChangedData);
            }
          };
          $timeout(function () {
            // without timeout, the listener might get registered 
            // in the same digest-cycle that tries to open the window and for some reason executing 
            // before the window_state was changed from 'closed'
            owWindows.onStateChanged(onStateChangeListener);
          });
        })
        .catch(function (err) { reject(err); })
      });
    };

     

  • updating content in inactive window / communicating between windows [angular]
    When working with multiple html-windows, some data might be updated that is displayed within another window (calling it "background window" for reference).
    This display will not be updated automatically until the window gets the focus back and angular does its magic through a new digest cycle.
    To make sure that updated data in localstorage for example is used, we might have to trigger a digest-cycle manually.

    • Poll-approach
      for easy implementation if window will not exist too long, for example if waiting for an update that tells it to close.
      Not recommended if window will be polling during the whole lifetime of the app.
       

      // somewhere within background-window
      $interval(function(){
      	// since $interval() triggers a new digest-cycle anyways on every execution, 
      	// this might theoretically even be just an empty function
      	$rootScope.$apply();
      }, 100)

       

    • overwolf message approach
      event-driven approach overwolf-specific - useful if messages are sent to the window anyways
       

      // somewhere within background-window
      overwolf.windows.onMessageReceived.addListener(function(){
      	// will trigger digest-cycle whenever window receives a message
      	$timeout(function(){
                // waiting for the current digest-cycle to end, in case the update is done within the current Window
                // like with $interval, the $rootScope.$apply() is not really neccessary here
                $rootScope.$apply();
          })
      })
      
      // after updating something important for background-window within another window
      overwolf.windows.sendMessage('background-window-idOrName', messageId, content, callback);

       

    • localstorage-event approach
      event-driven approach universal - can be adapted for worker usage etc. - useful for an implementation more decoupled from overwolf
       

      // somewhere within background-window
      $window.addEventListener('storage', function(storageEvent){
        	// will be called whenever something happens with storage
        	// (localStorage, SessionStorage)
        	// in ANOTHER window
      	$timeout(function(){
                // waiting for the current digest-cycle to end, in case the update is done within the current Window
                // like with $interval, the $rootScope.$apply() is not really neccessary here
                $rootScope.$apply();
          })
      })
      
      // within another window:
      $localstorage.something = 'whatever';

       

Edited by Colorfulstan
AidanDaniel97 likes this

Share this post


Link to post
Share on other sites

API Quirks / Errors

  • overwolf.games.events [inconsistent Behaviour / structure]
    On 9.8.2016 at 6:36 AM, goodbyte said:

    - overwolf.games.events.onNewEvents2 doesn't work... on the other hand, onInfoUpdates2 works as expected ( better structure, object notation ).

    • Generally unclear if neccessary to use onNewEvents or ...2 / onInfoUpdates or ...2 since for some games only one of them works, for some both, for some they differ in given data
    • With League of Legends, onNewEvents fires the events, onNewEvents2 does not
  • overwolf.games.events.getInfo() [missing status]
    • object passed to the callback contains "status": "status" on success
    • result.res.game_info.match_started evaluates to "True" and "False" instead of true/false, which have to be checked for by string-equality instead of boolean comparison. if ("False"){ // will execute } [accknowledged][Workaround]
      var gameInfo = result.res.game_info;
      if (gameInfo.match_started){ // make sure gameInfo.match_started is defined!
        var matchStarted = JSON.parse(gameInfo.match_started.toLowerCase()); 
      }
      On 5.9.2016 at 3:04 PM, BobDev said:

      The reason for this is most likely that c# to string conversion.
      Try send a json using sendMessage that contains bool value, like {visible: true} you will find out that recipient window will get {visible: True} which is what you would get if you would do toString on bool object in c#. 

  • League of Legends Events [unfavorable naming / structure]
    On 9.8.2016 at 6:36 AM, goodbyte said:

    {name: "spell", data: "spell1"} should be {name: "ability1", data: "{count: 1}"}
    {name: "spell", data: "spell2"} should be {name: "ability2", data: "{count: 1}"}
    {name: "spell", data: "ability2"} should be {name: "ability3", data: "{count: 1}"}
    {name: "spell", data: "ability4"} should be {name: "ability4", data: "{count: 1}"}
    {name: "death", data: ""} should be {name: "death", data: "{count: 1}"}
    {name: "kill", data: "{label: "kill", "count": 1}"} OK-ish ( it would be better to have a separate event for every kill streak )
    {name: "assist", data: "{label: "assist", "count": 1}"} OK-ish ( label shouldn't be present )
    {name: "match", data: "match_start"} should be {name: "match_start", data: ""}
    {name: "match", data: "match_end"} should be {name: "match_end", data: ""}

    • "respawn" does not trigger [Bug]
  • League of Legends GameInfo [Typo]
  • overwolf.games.getGameInfo(5426, function(result){console.log(result)})
    • Typo in returned argument (in actual overwolf-Object)
  • result.gameinfo.GameInfo.LuancherNames
    • Paths not normalized
      Finding things like following in there
      C:/Riot Games/League of Legends/RADS/projects/lol_air_client/releases/0.0.1.207/deploy//LolClient.exe\ (getGameInfo ProcessPath)
      C:/Games/league/RADS\..\lol.launcher.exe (getGameInfo -> LauncherPath)
      C:/Games/league/RADS\solutions\lol_game_client_sln\releases\0.0.1.138\deploy\League of Legends.exe (getRunningGameInfo -> commandLine)
  • overwolf.games.events.getInfo() [needs more investigation]
    Is sometimes not available (TypeError: ... is not a function)
  • overwolf.games.onGameInfoUpdated [Bug] [Fix announced]
    Update-Event gets triggered on already open Windows when a new Window is opened
    Consider Following Scenario:

    1. Registering a handler on overwolf.games.onGameInfoUpdated() (Ill refer to it as "InfoHandler") from one Window ( ill refer to it as "Start-Window")

    2. opening up another app-Window that previously was in status "closed" using overwolf.windows.restore().

    3. "InfoHandler" gets called on "Start-Window" with unchanged data compared to possible previous calls.

    • I assume the event is getting fired for every Window that registered a respective handler prior to opening the new window.

    • Workaround: Hold a reference to the previous changeData-object and check if the new one is the same. Very easyli done in angular, natively propably best to use underscore.js or something like that or just check properties relevant for you:

      // angular code
      var previousChangeData = null;
      owSdk.games.onGameInfoUpdated.addListener(function (/** ODKGameInfoChangeData */ result) {
        var changeData = result;
        if (angular.equals(previousChangeData, changeData)){
          return;
        }
        previousChangeData = changeData;
        // do stuff
      }

       

  • Mouseevents not fired on elements with negative z-index

     

  • overwolf.web.createServer() [Bug]

  • overwolf.logitech.led.init(callback) [unexpected Behaviour]
    On 5.8.2016 at 8:00 AM, fullbarrel said:

    overwolf.logitech.led.init(callback) - The callback returns immediately with a successful result, but in fact I can't issue commands to the api until some time has passed (~1000ms works for me). So if you want to immediately want to setLighting in the init callback, it will appear to be not working, when in fact you just have to wait before issuing commands. 

    Editor's Note: This seems to be true for lots (if not even all) of the methods, that change the state of the client (changing status of Windows for example). There often has to be a timeout used within the callback, so that the updated application state is used instead of the previous one. 
  • overwolf.logitech.led.setLighting(r, g, b, callback) [unhelpful Error Message] 
    On 5.8.2016 at 8:00 AM, fullbarrel said:

    overwolf.logitech.led.setLighting(r, g, b, callback) - If you accidentally pass a float to parameters r, g, or b, You wont get an error in the callback, but the whole function will fail with Uncaught Error: Failed to execute setLighting on Led with 4 arguments.

Share this post


Link to post
Share on other sites

This one gets it's own space for now since it's a bit longer:

  • overwolf.windows.sendMessage(windowId, messageId, messageContent, callback) [quirk or Bug] [workaround]
    • Sometimes the listening windows will not receive the message.
      Actually, the bigger problem is, the send-method will fail silently, so that the callback will not execute at all and there is no indication of the failure. In the problematic scenarios, following code would not log anything:
      console.log('trying to send message'); // 'trying to send message'
      overwolf.windows.sendMessage('validWindowIdOrName', 'meassageId', { notWorkingWithThis: '"Damn Quotation marks"' }, function (result) {
            console.info('sendMessage callback'); // not executed
      });

       

    • Found when messageContent is following object – given from anguar on $http error – result stringified before trying to send it:
      messageContent = {
        problematicProperty: JSON.stringify({"data":null,"status":-1,
            				"config":{"method":"GET","transformRequest":[null],"transformResponse":[null],
                                    	"url":"http://localhost:8080/champions",
                                       "headers":{"Accept":"application/json, text/plain, */*"}
                                     },
                           "statusText":""
                           })
      }

      method works as expected when the problematicProperty is not stringified beforehand
      Update 02.08.:
      The Problem seems to be quotation-marks.
      Trying to send following properties will fail (silently)

      {
      	nope: '""',
      	thisWontWorkToo: '\"\"'
      }

      A workaround is possible here by encoding the String as URI, but imo this encoding when sending and decoding when receiving should be done by Overwolf internally to prevent developers from having to encode / decode all there strings to be sure for it to work since it is a very common case for JS developers to use single quotations for their strings to be able to use double quotation marks within them without having to escape them. Also this will still not make it possible to send functions between windows.

      // before sending
      {
      	defusedProperty: encodeURI('problematic string with "quotation marks"')
      }
      
      // when receiving
      var defusedProperty = decodeURI(messageContent.defusedProperty);

       

    • messageContent Object can not contain Function property values. The workaround for Strings will not work here.

      messageContent = {
        // this property will be missing completely
        problematicPropertyFunction: function(){ ... },
      
        // this property will contain empty JSON object ( {} )
        proplematicPropertyNonJSONObjects : new Error('testing'),
      }

      I guess all constructors and non-JSON validated objects are not transfered

Edited by Colorfulstan

Share this post


Link to post
Share on other sites

 

League of Legends

  • InfoDB

    {"info":[{"category":"summoner_info","key":"champion","value":"ashe"}]}

    NOTE: value is equal to the key from riot's champion-data but lowercase. That makes this pretty much useless since Riot / ddragon works with case-sensitive names and this only makes it harder instead of easier to work with the data.

 

Thanks!

Will be fixed soon.

Share this post


Link to post
Share on other sites

I've made a similar post not long ago, nobody replied. Maybe I didn't express myself right, I'm not a native speaker. I'm gonna try using an image this time:

 

fWM7AkT.png

Share this post


Link to post
Share on other sites

I've made a similar post not long ago, nobody replied. Maybe I didn't express myself right, I'm not a native speaker. I'm gonna try using an image this time:

 

fWM7AkT.png

In the shown documentation the casing has changed, was that your issue and is it solved by now?

Edited by Colorfulstan

Share this post


Link to post
Share on other sites

Actually the image I've posted show how they're supposed to be, nothing have changed in the documentation yet.

 

Take a look at the GameEvents Provider source code, this video (https://youtu.be/NUxvV-a-dFI) posted by Itay show you how to access it. Click on the UID link to open the app's folder, from there you can go to games/CSGO/events.js for the entire list of events and proper casing, some of which are not even listed.

Edited by goodbyte
AidanDaniel97 likes this

Share this post


Link to post
Share on other sites

Actually the image I've posted show how they're supposed to be, nothing have changed in the documentation yet.

 

But the documentation shows the same casing as your picture!?

 

 

 

Take a look at the GameEvents Provider source code, this video (https://youtu.be/NUxvV-a-dFI) posted by Itay show you how to access it. Click on the UID link to open the app's folder, from there you can go to games/CSGO/events.js for the entire list of events and proper casing, some of which are not even listed. 

Wil add the missing once for league to the post if there are any somewhen in the near future.

Edited by Colorfulstan

Share this post


Link to post
Share on other sites

If I may chime in I would like to propose to add some things to the list. These gave me some hard time getting the Logitech Led api working, and @goodbyte helped me to work around them.

overwolf.logitech.led.init(callback) - The callback returns immediately with a successful result, but in fact I can't issue commands to the api until some time has passed (~1000ms works for me). So if you want to immediately want to setLighting in the init callback, it will appear to be not working, when in fact you just have to wait before issuing commands. 

overwolf.logitech.led.setLighting(r, g, b, callback) - If you accidentally pass a float to parameters r, g, or b, You wont get an error in the callback, but the whole function will fail with Uncaught Error: Failed to execute setLighting on Led with 4 arguments.

Colorfulstan likes this

Share this post


Link to post
Share on other sites
4 hours ago, fullbarrel said:

If I may chime in I would like to propose to add some things to the list. These gave me some hard time getting the Logitech Led api working, and @goodbyte helped me to work around them.

Sure, that's the point :)

Thanks for your contribution.

4 hours ago, fullbarrel said:

overwolf.logitech.led.init(callback) - The callback returns immediately with a successful result, but in fact I can't issue commands to the api until some time has passed (~1000ms works for me). So if you want to immediately want to setLighting in the init callback, it will appear to be not working, when in fact you just have to wait before issuing commands. 

This seems to be true for some other methods that trigger actions / execute other code.
When opening/closing/... WIndows for example the status of the window in question did sometimes not change when the callback returned, requiring at leas 100-200 MS timeout before working with the updated application state.

Share this post


Link to post
Share on other sites

- overwolf.games.events.onNewEvents2 doesn't work... on the other hand, onInfoUpdates2 works as expected ( better structure, object notation ).
- LoL events are a joke ( I just started working with them )... and the documentation... well... let's take a look at the events:

{name: "spell", data: "spell1"} should be {name: "ability1", data: "{count: 1}"}
{name: "spell", data: "spell2"} should be {name: "ability2", data: "{count: 1}"}
{name: "spell", data: "ability2"} should be {name: "ability3", data: "{count: 1}"}
{name: "spell", data: "ability4"} should be {name: "ability4", data: "{count: 1}"}
{name: "death", data: ""} should be {name: "death", data: "{count: 1}"}
{name: "kill", data: "{label: "kill", "count": 1}"} OK-ish ( it would be better to have a separate event for every kill streak )
{name: "assist", data: "{label: "assist", "count": 1}"} OK-ish ( label shouldn't be present )
{name: "match", data: "match_start"} should be {name: "match_start", data: ""}
{name: "match", data: "match_end"} should be {name: "match_end", data: ""}

respawn does not trigger.

The events are messed up, more than a half of them mistake the name with its feature key, the data with the name, and the actual data is missing. :rolleyes:

Share this post


Link to post
Share on other sites
4 hours ago, goodbyte said:

overwolf.games.events.onNewEvents2 doesn't work... on the other hand, onInfoUpdates2 works as expected ( better structure, object notation ).

This should be cleaned up, I still don't get why this was done, it's such a strange thing to do. There needs to be some clarification which one is working as intended (and at least one of them has to actually work as intended since it doesn't seem to be either one of the implementations). There isn't even an deprecation warning or something like that when using the old ones. 

4 hours ago, goodbyte said:

{name: "spell", data: "spell1"} should be {name: "ability1", data: "{count: 1}"}

You are saying that the latter is what you actually get from onInfoUpdates2 ?
I think the former is what comes back when using onInfoUpdates...:gusta:

 

Share this post


Link to post
Share on other sites

Both return the same in LoL, the examples come from onInfoUpdates2... if you want to see the structure improvements between the two, try robocraft.

Edited by goodbyte

Share this post


Link to post
Share on other sites

The list of Warface's events is incomplete, kill, sniper_down, shield_bearer_down are missing, among others...

SMITE event data is not a proper JSON string, e.g. {name: "player death", data: "playername:Guan Yu,killername:goodbyte"}... how are we supposed to parse it? by hand?

Share this post


Link to post
Share on other sites
11 hours ago, goodbyte said:

The list of Warface's events is incomplete, kill, sniper_down, shield_bearer_down are missing, among others...

SMITE event data is not a proper JSON string, e.g. {name: "player death", data: "playername:Guan Yu,killername:goodbyte"}... how are we supposed to parse it? by hand?

The reason for this is most likely that c# to string conversion.
Try send a json using sendMessage that contains bool value, like {visible: true} you will find out that recipient window will get {visible: True} which is what you would get if you would do toString on bool object in c#. 

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!


Register a new account

Sign in

Already have an account? Sign in here.


Sign In Now