Embedding a Widget

Widgets are embedded by adding scripts and tags directly in the source code of your webpages. These scripts and tags need to be set in accordance with the type of authentication required. Some widgets are embedded to require authentication, while others are embedded to not require authentication.

Caution:

Do not mix authentication modes within the same page or application context. Doing so can cause several issues.

Browser Blocking: Safari and other browsers may block content when authenticated widgets are embedded in non-authenticated pages.
Authentication Conflicts: Mixing widgets can trigger unexpected authentication workflows.

The best practice is to use the same authentication approach for all widgets on a page. Either all widgets should require OpenID Connect authentication, or all widgets should require pre-authenticated / non-authenticated contexts.

Embedding Content Requiring Authentication

The following code is an example of the basic integration of widgets on a webpage for OpenID Connect-based SSO implementations, with emphasis applied to the main integration points.

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<title>Page Title</title>
<meta name="viewport" content="width=device-width, initial-scale=1">  
<script src="https://ei-util-stage.opower.com/ei/x/embedded-api/core.js?auth-mode=oauth"></script>
</head>
<body> 
 <div> 
  <opower-widget-neighbor-comparison opower-instance="widget-neighbor-comparison"></opower-widget-neighbor-comparison>
 </div>
 <div>
  <opower-widget-data-browser opower-instance="widget-data-browser"></opower-widget-data-browser>
 </div>
</body>
</html>

The instructions below guide you through each step of the process and provide more background information about each the scripts and tags that are required.

Caution:

If you are using Oracle Infinity to track engagement analytics for your website, then you must load your Oracle Analytics Infinity CX Tag on your webpage before completing the steps below. Otherwise, analytics tracking for your widgets will not work. See Tracking User Interaction Analytics for instructions. You can ignore this step if you are not using Oracle Analytics Infinity.

To prepare a webpage for embedding content requiring authentication:

Include the main script tag for the core library within the HTML head of the webpage. A single script tag is required regardless of the number of widgets embedded in the body of the page. The script tag uses the following syntax:
```
<script src="https://[HostName]/ei/x/embedded-api/core.js"></script>
```
Where HostName is the applicable host information. When embedding on the stage environment, the format is ei-[ClientCode]-stage.opower.com, where ClientCode is the client code assigned for the utility. Contact Your Delivery Team to confirm your client code. When embedding on the production environment, the format is [ClientCode].opower.com.
Append auth-mode=oauth as a query parameter and value to the src attribute in the script tag.
Append locale as a query parameter to the src attribute in the script tag. This is an optional parameter that allows embedded widgets to reflect a locale preference change by the customer that occurs after the customer has signed in to the Energy Management Web Portal. This parameter does not affect the outbound communication locale preference for a customer. The value for the locale parameter must be defined as the locale for the page where the widget is embedded. The example below for the production tier uses a static definition of US English:
```
<script src="https://util.opower.com/ei/x/embedded-api/core.js?auth-mode=oauth&locale=en_US"></script>
```
Include the required HTML in the location on the page where the widget is to appear. This HTML includes a call to the relevant widget, which uses the following format:
```
<opower-[WidgetName] opower-instance="[InstanceName]"></opower-[WidgetName]>
```
Where WidgetName is the name of the applicable widget. You must also define the opower-instance attribute by supplying the applicable InstanceName. The full list of widget names and instance names is provided above. An example of embedding the Bill Comparison widget is shown below:
```
<div>
<opower-widget-bill-compare-enhanced opower-instance="widget-bill-compare-enhanced"></opower-widget-bill-compare-enhanced>
</div>
```
Repeat the previous step for each widget you are including on the webpage. If you embed multiple widgets on a single webpage, consider a strategy to improve the load performance of the widgets that link to other widgets on the same page, which is described in Avoiding Webpage Refreshes.
Include listeners on the webpages, where a widget displays the authenticated experience, to provide required entity IDs and access tokens. These techniques are described at Providing Access Tokens for OpenID Connect.
Send your Delivery Team a listing of all your webpage URLs that contain the embedded widgets, along with the widget names included on each webpage. Any updates to the locations where the widget is embedded must be communicated to Delivery Team in advance of deploying the widget to the new location. This information can be provided along with other configuration inputs, as instructed in the Oracle Utilities Opower Digital Self Service - Energy Management Configuration Guide.
If your website uses a Content Security Policy, configure it to allow Oracle Utilities Opower resources. Contact your Delivery Team to obtain the domains and resources that should be allowed.

This process completes the minimum required steps to embed widgets on a webpage. You can employ additional techniques to improve the performance, user interaction, and overall look-and-feel of the widgets within the website. See Improving the Embedded Widget User Experience with Custom Events for more information.

Embedding Content Not Requiring Authentication

Pre-authenticated or unauthenticated content requires a similar setup with a few important differences. The following code is an example of the basic integration of widgets on a webpage for pre-authenticated implementations, with emphasis applied to the main integration points.

<!DOCTYPE html>
<!DOCTYPE html>
<html>  
<head>  
<meta charset="utf-8" />  
<meta http-equiv="X-UA-Compatible" content="IE=edge">  
<title>Page Title</title>  
<meta name="viewport" content="width=device-width, initial-scale=1">    
<script src="https://ei-util-stage.opower.com/ei/x/embedded-api/core.js?auth-mode=none"></script>  
</head>  
<body>   
<div>
<opower-widget-survey opower-instance="widget-survey-easyopen-splash"></opower-widget-survey> 
</div>  
</body>  
</html>

The instructions below guide you through each step of the process and provide more background information about each of the scripts and tags that are required.

Caution:

To prepare a webpage for embedding content not requiring authentication:

Include the main script tag for the core library within the HTML head of the webpage. A single script tag is required regardless of the number of widgets embedded in the body of the page. The script tag uses the following syntax:
```
<script src="https://[HostName]/ei/x/embedded-api/core.js"></script>
```
Where HostName is the applicable host information. When embedding on the stage environment, the format is ei-[ClientCode]-stage.opower.com, where ClientCode is the client code assigned for the utility. Contact Your Delivery Team to confirm your client code. When embedding on the production environment, the format is [ClientCode].opower.com.
Append auth-mode=none as a query parameter and value to the src attribute in the script tag.
Append locale as a query parameter to the src attribute in the <script> tag. This is an optional parameter that allows embedded widgets to reflect a locale preference change by the customer that occurs after the customer has signed in to the Energy Management Web Portal. This parameter does not affect the outbound communication locale preference for a customer. The value for the locale parameter must be defined as the locale for the page where the widget is embedded. The example below for the production tier uses a static definition of US English:
```
<script src="https://util.opower.com/ei/x/embedded-api/core.js?auth-mode=none&locale=en_US"></script>
```
Include the required HTML in the location on the page where the widget is to appear. This HTML includes a call to the relevant widget, which uses the following format:
```
<opower-[WidgetName] opower-instance="[InstanceName]"></opower-[WidgetName]>
```
Where WidgetName is the name of the applicable widget. You must also define the opower-instance attribute by supplying the applicable InstanceName. The full list of widget names and instance names is provided above. An example of embedding the Bill Comparison widget is shown below:
```
<div>
<opower-widget-survey opower-instance="widget-survey-easyopen-splash"></opower-widget-survey>
</div>
```
Repeat the previous step for each widget you are including on the webpage. If you embed multiple widgets on a single webpage, consider a strategy to improve the load performance of the widgets that link to other widgets on the same page, which is described in Avoiding Webpage Refreshes.
Include listeners on the webpages, where a widget displays the authenticated experience, to provide required entity IDs and access tokens. These techniques are described at Providing Access Tokens for OpenID Connect.
Send your Delivery Team a listing of all your webpage URLs that contain the embedded widgets, along with the widget names included on each webpage. Any updates to the locations where the widget is embedded must be communicated to Delivery Team in advance of deploying the widget to the new location. This information can be provided along with other configuration inputs, as instructed in the Oracle Utilities Opower Digital Self Service - Energy Management Configuration Guide.
If your website uses a Content Security Policy, configure it to allow Oracle Utilities Opower resources. Contact your Delivery Team to obtain the domains and resources that should be allowed.

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:

Open the source file of the webpage where you intend to embed an Oracle Utilities Opower widget.
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:
```
<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.
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.
```
<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>
```
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.