Intel Power Web API Documentation and Examples

The Intel Power Web API provides a web app with JavaScript* access to information about the device's power and battery state.

Contents

Overview

When web apps have the ability to learn about the device's state they are able to make use of that information to create a better experience for the user.

For instance, in combination with other information about the device, a web app might use Battery level information to determine if a will be able to complete an activity - such as watching a lengthy movie or playing a game.

Browser and Device Compatibility

The table below lists some compatability notes for browser and operating system combinations. This API is currently beta quality.

If you are interested in seeing these APIs available on other device types and operating systems please let us know by leaving comments.

BrowserOperating SystemNotes
Firefox 3.5.x, 3.6.x Windows (XP, Vista, Win 7) Seems to be working well.
Chrome 4.0.x.y Windows (XP, Vista, Win 7) Seems to be working well.
Safari 4.0.x Windows (XP, Vista, Win 7) Seems to be working well.
Opera v 10.x Windows (XP, Vista, Win 7) Not currently working. It's on the debug todo list.
Internet Explorer 8.x Windows (XP, Vista, Win 7) Not supported yet. Its on the todo list though.
Firefox, Chrome, Safari Linux, MacOS Not supported yet. Linux and Mac OS porting is underway :)

A code sample to get you started

This HTML & JavaScript shows you how to embed the Intel Power Web API into your app.

  <div id="IntelWebAPIs_sample_code_status_div" 
    style="border:1px dotted red;width:640px;height:480px;overflow:auto;"></div>
  <script 
    type="text/javascript" 
    src="http://software.intel.com/sites/whatif/webapis/intelwebapis.js">
  </script>
  <script type="text/javascript">
  
    // this outer closure just to keep the sample code from cluttering up
    // the namespace with the function names etc being used
    (function() {
      
      //kick off IntelWebAPIs.init() and IntelWebAPIs.require() when
      //the page is loaded
      add_onload_handler( function() {
  
        IntelWebAPIs.init(init_result_func);
        
        //called by IntelWebAPIs.init()
        function init_result_func(result) {
          if(result.success) {
            // now bring in Intel Web APIs required by your app...
            output_status("IntelWebAPIs Connector init success");
            IntelWebAPIs.require(["power"], require_completion_func, require_progress_func);
          }
          else {
            output_status("IntelWebAPIs Connector init error: " + result.error.msg);
            //handle error condition
            //result.error.msg contains an error message
            //result.connectorInstUrl contains the url to the Intel Web API connector installer
            output_status("you may need to download the Intel Web API connector from here: " + 
              result.connectorInstUrl);
          }
        }
    
        //called by IntelWebAPIs.require()
        function require_completion_func(result) {
          if(result.success){
            //you can now use IntelWebAPIs.power properties and functions
            output_status("IntelWebAPIs." + result.installInfo.plugins[0].name + " ready for use!");
            setInterval(function(){
              // send a status message to our div every second
              output_status("Device is using AC power: " + IntelWebAPIs.power.usingExternalPowerSource);
              output_status("Device power level: " + IntelWebAPIs.power.powerLevel + " %");
              if(IntelWebAPIs.power.usingExternalPowerSource == false){
                output_status("Device battery time remaining: " + 
                  Math.round((IntelWebAPIs.power.timeRemaining / 60)) + " minutes");
              }
            },1000);
          }
          else {
            //check other result properties and handle error condition
            output_status("IntelWebAPIs error: " + result.installInfo.msg);
          }
        }
        
        //called by IntelWebAPIs.require()
        function require_progress_func(statusMsg){
          //statusMsg is a string - send this wherever
          output_status("IntelWebAPIs connector status: " + statusMsg);
        }
      
      });
      
      /* Its recommended that you wait until the document is loaded 
         before calling IntelWebAPIs.init() and IntelWebAPIs.require() 
         This utility helps with that...*/
      function add_onload_handler(addfunc, altwindow) {
        var targwindow = window;
        if(typeof(altwindow) != 'undefined'){
          targwindow = altwindow;
        }
        
        /* chain the onload functions together */
        var prevf = targwindow.onload;
        var newf  = addfunc;
        targwindow.onload = function(){
            newf();
            if(typeof(prevf) == 'function'){
              prevf();
            }
          };
      }
      
      /* utility that outputs status messages to a div*/
      function output_status(str) {
        var divout = document.getElementById("IntelWebAPIs_sample_code_status_div");
        divout.innerHTML += str + "<br/>";
        divout.scrollTop = divout.scrollHeight;
      }
    })(); // end of outer closure
  </script>

This is the result Object that is passed into init_result_func(result).
If the Intel Web API Connector is not yet installed on a user's device you can use the result.connectorInstUrl to prompt the user, in the context of your app, to install it.
Once the Intel Web API Connector is installed other apis are installed by the connector, with minimal user interruption, when your app calls IntelWebAPIs.require().

  result = { 
    success           : boolean,
    
    // these fields are valid if success != true
    connectorInstUrl  : string 
    error             : {
      msg             : string 
    } 
  }

This is the result Object that is passed into require_completion_func(result).

  result = { 
    success       : boolean,
    
    installInfo   : {
      msg         : string,
      
      plugins     : [ { 
        name      : string,
        installed : boolean,
        details   : string
        }, 
        //...
      ], 
    }
  }  

JavaScript API Details
These are the properties exposed by the Power Web API:

  IntelWebAPIs.power = {
    'version'                   : string,
    'usingExternalPowerSource'  : boolean,
    'timeRemaining'             : number,
    'powerLevel'                : number
  };

IntelWebAPIs.power.version
This is the API's version string. It is formatted as "major.minor.patch" where major and minor are numbers and patch is a string.

IntelWebAPIs.power.usingExternalPowerSource
The IntelWebAPIs.power.usingExternalPowerSource is true if the device is on AC power, false if the device is using batteries. On desktop systems where batteries are not detected this will return true.

IntelWebAPIs.power.timeRemaining
When IntelWebAPIs.power.usingExternalPowerSource == true, the IntelWebAPIs.power.timeRemaining property provides the number of seconds remaining of battery life. When IntelWebAPIs.power.usingExternalPowerSource == false this value is -1.
This value will also be -1 if unknown - if the API is unable to determine time remaining from the underlying system software.

IntelWebAPIs.power.powerLevel
The IntelWebAPIs.power.powerLevel is true provides the current charge level of the device's batteries as a percent.
This will be -1 if unknown - if the API is unable to determine the charge level from the underlying system software.


These JavaScript functions demonstrate accessing the power information:

  function output_timeRemaining(){
    alert("timeRemaining=" + IntelWebAPIs.power.timeRemaining);
  }
  
  function output_usingExternalPowerSource(){
    alert("usingExternalPowerSource=" + IntelWebAPIs.power.usingExternalPowerSource);
  }

  function output_powerLevel(){
    var selplugin = get_sel_plugin();
    alert("powerLevel=" + IntelWebAPIs.power.powerLevel);
  }



See it working in this page!
Per informazioni più dettagliate sulle ottimizzazioni basate su compilatore, vedere il nostro Avviso sull'ottimizzazione.