@itwin/ec3-widget-react

Copyright © Bentley Systems, Incorporated. All rights reserved.

The EC3 widget is a UI component for iTwin Viewer applications that simplifies how users (and developers) interface with the Carbon Calculation EC3 APIs. The ec3-widget-react package provides a UiProvider class, EC3Provider, which can be passed into the uiProviders prop of the iTwin Viewer's <Viewer /> component.

Getting Started

This is not a standalone UI and requires a parent iTwin Viewer application to work as intended. A guide on how to create a basic iTwin Viewer application can be found here. This package provides a viewer widget. Documentation on how to add a widget to your application can be found here.

Permissions and Scopes

The SPA client used by your iTwin viewer must have the itwin-platform scope.

Users must have the carbon_calculate and insights_view permissions assigned at either the Project or iModel level. Additional instruction on how to create roles and assign permissions can be found in the iTwin Platform Projects API documentation.

Sample usage

You first need to create an OAuth application in https://buildingtransparency.org/ec3/manage-apps/developers. Add the EC3Provider to UI providers using your Client Id and Redirect URI in App.tsx.

import { EC3Provider } from "@itwin/ec3-widget-react";
...

const overridenStrings = new Map()
  .set("defaultStringKey","customLocalizedString");

await EC3Widget.initialize({
  localization: IModelApp.localization,
  // this is an optional parameter to override the default strings
  localizationOverrides: overridenStrings
  });

<Viewer
  ...
  uiProviders={[
    new EC3Provider({
      clientId: "...",
      redirectUri: "...",
    }),
  ]}
/>

Then handle the redirect using the following code in Index.tsx.

import { handleEC3AuthCallback } from "@itwin/ec3-widget-react";

} else if (window.location.pathname === "/callback") {
  handleEC3AuthCallback({
    clientId: "...",
    redirectUri: ".../callback",
  });
} else {