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-widget-neighbor-comparison>
 </div>
 <div>
  <opower-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-[WidgetName]>
```
Where WidgetName is the name of the applicable widget. If you are embedding the Home Energy Analysis, you must also define the opower-instance attribute. The full list of widget names is provided above. An example of embedding the Bill Comparison widget is shown below:
```
<div>
<opower-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 and Authenticating Customers in Support of 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 User Experience Scenarios 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-[WidgetName]>
```
Where WidgetName is the name of the applicable widget. If you are embedding the Home Energy Analysis, you must also define the opower-instance attribute. The full list of widget 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 and Authenticating Customers in Support of 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.