Improving User Experience Scenarios with Custom Events

When using web components, a number of events occur at certain points of user interaction. These events allow utilities to develop strategies to react to these events that improves the user experience of embedded widgets.

For example, users selecting a link commonly causes a full webpage refresh when using a deep link. The utility can override this behavior by listening for link events, and then directing the user to the content without requiring a webpage refresh. You can employ this strategy along with delaying widget loading on a page to embed multiple widgets on a single page while also improving performance and customer engagement.

On this page:

• Improving User Experience Scenarios with Custom Events
• Linking to Widget Content
• Providing Access Tokens and Authenticating Customers in Support of OpenID Connect
• Improving Widget Load Performance
• Tracking User Interaction Analytics

Linking to Widget Content

Widgets support an opower:link event which can be used to configure the link behavior. By default, links can cause full webpage refreshes. However, if the widget being linked to is on the same webpage, this behavior can be modified to redirect to the widget content on the page without requiring a refresh. This improves performance and the overall user experience when embedding multiple widgets on a single webpage. This example, along with other performance-related configurations, is covered in Improving Widget Load Performance.

Note: The opower:link event supports widget-to-widget linking behavior. For information on design considerations related to supporting external links to embedded widgets, see External Links to Widgets.

Widget Links

The following table summarizes the link events that can be triggered by embedded widgets. This includes the experience name that is part of the opower:link event that is triggered when a customer interaction triggers a link. You can use the techniques described in Avoiding Webpage Refreshes to listen for these events and direct the customer to the applicable webpage, or location on the current webpage such as opening a tab. If instead you choose to rely on the default link behavior, customers are directed to the content listed for the link events below, but this could cause unnecessary webpage refreshes.

Note: The Next Best Action widget consists of banners that link to other web content, including embedded widgets, to give customers more detailed, actionable information. The links in the banners are dependent on which banners and actions you choose to configure for your customers. Work with your Delivery Team to review which widgets your banners link to.

Back to Top

Event Detail

When a user clicks a link for a widget, the opower:link event is triggered. Details on the intended navigation action, as well as widget name containing link, are included in the example below.

Example

Copy

{
// Widget that includes the triggered link
widgetName: 'widget-data-browser',
experienceName: 'energyUseDetails',
url: {
  protocol: 'https:',
  slashes: true,
  auth: null,
  host: 'util.opower.com',
  port: null,
  hostname: 'util.opower.com',
  hash: null,
  search: '?fixtures=true',
  pathname: '/ei/x/energy-use-details',
  path: '/ei/x/energy-use-details?fixtures=true',
  href: 'https://util.opower.com/ei/x/energy-use-details?fixtures=true',},
  target: '_self'
}

Back to Top

Providing Access Tokens and Authenticating Customers in Support of OpenID Connect

When authenticating using OpenID Connect, an access token must be provided by the utility. The access token is used by Oracle Utilities to issue a GET request to the UserInfo endpoint to retrieve the user's account details.

Note: The event listeners described below can be excluded if a widget is embedded in support of a pre-authenticated experience. No authentication is required to display the pre-authenticated experience to customers.

Providing Access Tokens

Embedded widgets require access tokens when they are initially loaded on the page, as well as if the widget requires the access token again but the access token has expired. You can provide access tokens by listening for and handling the opower:unauthorized event.

The code example below shows a simple synchronous handler.

// synchronous handler example
window.addEventListener('opower:unauthorized', function(event) {
  var authorize = event.detail.authorize;
  var authorization = {
   accessToken: 'ABC123XYZ' // The access token string as issued by the authorization server
  }
  authorize(null, authorization); // Do not call if user is logged out
}

If additional logic is required to retrieve the access token, an asynchronous handler must be used. When using this method the event.preventDefault() function must be called to prevent synchronous execution from occurring. The code example below shows an asynchronous handler.

// asynchronous handler example
window.addEventListener('opower:unauthorized', function(event) {
  var authorize = event.detail.authorize;
  event.preventDefault(); // to instruct Opower authorization logic to wait for async callback
  fetchOpowerAuthorization(function(error, authorization) { // fetchOpowerAuthorization is an example utility defined function
    authorize(error, authorization);
  }
}

Back to Top

Providing Customer IDs to Support Multiple Premise Customers

You can provide the customer ID to further identify the customer interacting with an embedded widget. This task is accomplished by listening for and handling the opower:start event. Providing the customer ID ensures that customers with multiple premises are presented the correct experience when viewing the widget.

Note: Customer IDs passed into the opowerApi.setEntityId function must exist in the response from the UserInfo endpoint. For information on determining the customer ID for OpenID Connect implementations, refer to the Oracle Utilities Opower SSO Configuration Guide which describes creating a UseInfo endpoint.

An Opower API object is included in the event detail, and contains methods that can be called by the utility's web portal. The setEntityIds method of the Opower API must be called in order to provide the customer ID, which sets the current customer context. The setEntityIds method accepts an array of exactly one value. Once context has been set, the start method must be called. The code example below shows a simple synchronous handler.

// synchronous handler example 
            window.addEventListener('opower:start', function(event) { 
            window.opowerApi = event.detail;
            window.opowerApi.setEntityIds(['ABC-123']);
            window.opowerApi.start(); 
        });

If additional logic is required to determine the customer state, an asynchronous handler must be used. When using this method the event.preventDefault() function must be called to prevent synchronous execution from occurring. The code example below shows an asynchronous handler.

// asynchronous handler example 
            window.addEventListener('opower:start', function(event) { 
            window.opowerApi = event.detail; 
            event.preventDefault(); // to prevent synchronous start of widget
            fetchOpowerConfiguration(function(error, configuration){ // fetchOpowerConfiguration is an example utility defined function
            if (error) {
            //  handle own error. Widget content has not loaded.
            } else {
            window.opowerApi.setEntityIds(configuration.entityIds);
            window.opowerApi.start();
            }
            }); 
        });

Back to Top

Improving Widget Load Performance

It is important to consider techniques to improve the load performance when embedding widgets. The following techniques can avoid unnecessary webpage refreshes and improve load performance for customers.

Avoiding Webpage Refreshes

For webpages that include multiple widgets, you can avoid unnecessary page refreshes when one widget links to another widget. Rather than a full refresh, you can redirect the user directly to the other widget on the page, including switching tabs or opening accordions that include the widgets.

Note: Refer to Widget Links for a listing of link events that can be triggered by widgets.

Webpages can include multiple embedded widgets, and each widget can include links to other widgets. When a user interacts with these links, the focus of the webpage can be directed to the correct embedded widget within the same page. This includes switching tabs or opening accordions that include the widgets being linked to.

The code example below listens for a user selecting a link to a given widget. It prevents a full webpage refresh and instead redirects to the linked widget.

window.addEventListener('opower:link', function(event) {
  if (event.detail.experienceName === 'energyUseDetails') {
    event.preventDefault();
    $.hide(event.target);
    $.show('#energyUseDetails');
  }
});

Note: Include logic in the link redirects to animate and scroll to the widget gradually rather than redirecting the user immediately to the widget. This best practice avoids disorienting the customer during the redirect.

Back to Top

Delaying Widget Loading

By default, the embedded widget content immediately starts to download to the user's browser and begins executing. If the widgets are not the primary or initial focus of the webpage it can be beneficial to delay widget execution. From the user's perspective, this provides faster load performance for the webpage.

JavaScript can be used to load the embedded web components when they are needed, such as when a user expands an accordion or selects a tab that includes the widget. The following example adds the Data Browser widget to a tab when the user clicks on the tab, which allows the webpage to load faster due to delaying the widget loading. While this example demonstrates a tabbed implementation, similar code can be used for utility site techniques such as accordions.

The addInitializeTabListener function is a sample function that uses an HTML tab ID, tab content ID, and a string of HTML to include in the applicable tab. During a webpage load this function can be declared and called with the applicable parameters for each tab that includes embeddable widgets. When the applicable tab is clicked, the function initializes the tab content with the string of HTML. The once attribute ensures that the event is only triggered on the first click of the tab. Example HTML for the applicable tab is also included to show where the string of HTML is inserted in this scenario.

Note: The example call of the addInitializeTabListener function uses an optional heading element to display above the Data Browser widget. See Embedding a Widget Using Web Components for the widget name information, which is the required content to include an embedded widget.

Example

Copy

function addInitializeTabListener(tabId, tabContentId, html) {
  var tab = document.getElementById(tabId);
  var tabContent = document.getElementById(tabContentId);
  tab.addEventListener('click',
    function() {
      tabContent.innerHTML = html
    },
    { once: true }
  )
}

addInitializeTabListener('widget-data-browser-tab', 'widget-data-browser-content', '<h3>Data Browser</h3><opower-widget-data-browser></opower-widget-data-browser>')

<div id="widget-data-browser-tab">
  <div id="widget-data-browser-content">
    <!-- On click of the tab, the Data Browser widget is inserted here -->
  </div>
</div>

To extend this example, consider the scenario where the Neighbor Comparison widget is included in a separate tab on the same page. The function can be called to delay and insert the widget in this tab as well, as shown in the following example code. This example includes no heading element.

addInitializeTabListener('widget-neighbor-comparison-tab', 'widget-neighbor-comparison-content', '<opower-widget-neighbor-comparison></opower-widget-neighbor-comparison')

Back to Top

Tracking User Interaction Analytics

With widgets placed directly into a webpage, utilities can self-serve analytics tracking such as whether or not a user views a widget. This can be accomplished using any analytics platform you prefer.

Oracle Utilities Opower also uses the Oracle Infinity analytics platform to collect user interaction metrics. If you are already using Oracle Infinity to track engagement analytics for your website, then you must load your Oracle Infinity CX Tag in your webpage before adding any Opower-specific widget code snippets. The Oracle Infinity CX Tag is a snippet of JavaScript code that collects data from the webpages that users visit.

Note: The steps below assume you have already generated an Oracle Infinity CX Tag based on the instructions in CX Tag Quick Start > Standard.

To load your Oracle Infinity CX Tag:

1. Open the source file of the webpage where you intend to embed an Oracle Utilities Opower widget.

2. Add your Oracle Infinity CX Tag to the section of your webpage that is optimal for your website implementation. For example, in a static webpage design, you could add it to the <head> tag. For a more dynamic implementation (such as a single-page application), you may add it elsewhere. In the case of a static webpage, the simplest way to ensure the CX Tag is loaded and executed in the proper order is to use the defer script tag attribute. See the HTML5 specification for more information about the defer attribute. An example of how the attribute could look in your CX Tag is as follows:

   Copy

   <script src="https://c.oracleinfinity.io/acs/account/{Account GUID}/js/{Tag ID}/odc.js" defer></script>

   In this example, {Account GUID} and {Tag ID} are variables which are generated during the process of creating your Oracle Infinity CX Tag.

3. Ensure that the script for loading the core widget library comes after the CX Tag. Otherwise, the script for the core widget library will initialize its own Infinity Analytics handler, and will not allow another Infinity Analytics handler to be used. The example below shows that the script for the CX Tag comes first and is followed by the script for the core widget library, which also has its own defer attribute.

   Copy

   <script src="https://c.oracleinfinity.io/acs/account/{Account GUID}/js/{Tag ID}/odc.js" defer></script>
   
   <script src="https://util.opower.com/ei/x/embedded-api/core.js" defer></script>
   

4. Follow the rest of the standard steps to embed a widget as described in Embedding a Widget.

Note: The steps above are meant as an example only. Depending on your implementation, there may be other options to ensure the scripts are loaded and executed in the required order. Contact your Delivery Team if you need additional guidance.

Back to Top