How to insert webcomponents in an app? - Datanumia Developer Portal

General information

To display any of the HOME Interfaces Web Components, please follow these requirements and guidelines :

Import the scripts associated with the HOME Interfaces Web Components.
Authenticate the logged-in user using the authentication web component (more details in this documentation).
Place the web component’s tag in your codebase.

In a Web App

To use our web components, please follow the following steps for production or qa environment. The variable BASE_URI_ENVIRONMENT has to be replaced with one of the following value from desired environment.

Production
QA

BASE_URI_ENVIRONMENT : https://static.home.datanumia.com

BASE_URI_ENVIRONMENT : https://new-front-intersi.qa.datanumia.com

Step 1 : Import the pre-prepared JavaScript files and stylesheets

You will need to import the JavaScript modules used to instantiate the HOME Interfaces Web Component.

Important !

The polyfill script must be placed BEFORE the import of the main.js script for each offer.

Simply import them in the standard way :

Don’t forget to replace the variable BASE_URI_ENVIRONMENT from the needed environment.

<head>
  <!-- snips -->

  <!-- BEGIN OF MODIFICATION -->
  <!-- Loading socle offer's resources -->
  <link rel="stylesheet" href="<BASE_URI_ENVIRONMENT>/socle/fr/styles.css">
  <!-- /!\ Import polyfills.js before main.js -->
  <script src="<BASE_URI_ENVIRONMENT>/socle/fr/polyfills.js" type="module"></script>
  <script src="<BASE_URI_ENVIRONMENT>/socle/fr/main.js" type="module"></script>

  <!-- Loading authentication resources -->
  <!-- /!\ Import polyfills.js before main.js -->
  <script src="<BASE_URI_ENVIRONMENT>/basis/polyfills.js" type="module"></script>
  <script src="<BASE_URI_ENVIRONMENT>/basis/main.js" type="module"></script>
  <!-- END OF MODIFICATION -->
</head>

Step 2 : Configure authentication with our dedicated component

Once you have completed the previous steps, please authenticate using the dtn-integration-requirements web component you just imported. This custom element is provided by the basis import. In this example, we’ve chosen to use a Datanumia token. If you prefer to use your own application token, that’s possible and explained in detail in the dedicated section. You can find more details on this specific step in the “Security” section.

<dtn-integration-requirements token="<datanumia-token>">
</dtn-integration-requirements>

Step 3 : Use the web components wherever you want

To finalize the web app implementation, simply place the web component wherever you prefer. For example, if you choose to place it on your main page (i.e., in the index.html file), you will have the following code:

<!-- index.html -->

<dtn-consumption-monitoring></dtn-consumption-monitoring>

Internationalization

The HOME Interfaces web components handle internationalization, which mean that they support multiple languages. To load a specific language, please refer to the RFC5646 format of the desired language.

If the language is not supported yet, you may enconter a 404 http status when trying to load the javascript module.

Here is the list of the currently supported languages :

fr: French language (France)
en-GB: English language (Great britain)

Link for each language

This following import will load the dtn-consumption-monitoring web component in dedicated language.

FR

<!-- BASIS has no traduction since there is no UI -->
<script src="<BASE_URI_ENVIRONMENT>/basis/polyfills.js" 
        type="module"></script>
<script src="<BASE_URI_ENVIRONMENT>/basis/main.js" 
        type="module"></script>

<!-- SOCLE -->
<link rel="stylesheet" href="<BASE_URI_ENVIRONMENT>/socle/fr/styles.css">
<script src="<BASE_URI_ENVIRONMENT>/socle/fr/polyfills.js" type="module"></script>
<script src="<BASE_URI_ENVIRONMENT>/socle/fr/main.js" type="module"></script>

en-GB

<!-- BASIS has no traduction since there is no UI -->
<script src="<BASE_URI_ENVIRONMENT>/basis/polyfills.js" 
        type="module"></script>
<script src="<BASE_URI_ENVIRONMENT>/basis/main.js" 
        type="module"></script>

<!-- SOCLE -->
<link rel="stylesheet" href="<BASE_URI_ENVIRONMENT>/socle/en-GB/styles.css">
<script src="<BASE_URI_ENVIRONMENT>/socle/en-GB/polyfills.js" type="module"></script>
<script src="<BASE_URI_ENVIRONMENT>/socle/en-GB/main.js" type="module"></script>

In a Mobile App

The implementation details depend on the targeted system. In the following section, we will focus on the Android and iOS environments using native applications, built respectively with Java (or Kotlin) and Swift. The implementation demonstrated will be based on WebView technology, which allows developers to display web content inside a native application. Some specific configurations are required to enable the use of HOME Interfaces Web Component inside these WebViews.

Loading the web components

Please create an HTML page to be used as the WebView content. This page should be built using the guidelines previously mentioned in the web application section. If you want to serve the same web page to multiple applications, you can use a distant html page.

Authentication in Android WebView

You can update the authentication token using the evaluateJavascript method provided by the WebView objects. This allows the dtn-authentication web component to receive a token as specified in the documentation about security in the HOME Interfaces context.

Android (Java)
IOS (Swift)
IONIC

Application authorizations

In an Android environment, you will need to grant specific authorizations to both the WebView and the application itself.

Android application permissions

Internet: To retrieve the static resources needed to display the HOME Interfaces, the application must be allowed to make network requests.

Permissions for the WebView integrating the HOME Interfaces

JavaScript: The HOME Interfaces rely on web components technology, which requires JavaScript execution.
DOM Storage: The HOME Interfaces components use browser storage mechanisms.
Allow file access: Required if you plan to use a local index.html file.

To finish, you may activate the cookie manager to allow the application to handle cookies. This is required for authentication to work properly.The following code grants the WebView all required permissions:

WebSettings webSettings = mWebView.getSettings();
webSettings.setJavaScriptEnabled(true);
webSettings.setDomStorageEnabled(true);
webSettings.setAllowFileAccess(true);

Application authorizations

By default, the WebKit WebView (or WKWebView) authorizes the execution of JavaScript. The only permission required to display HOME Interfaces web components is the WKHTTPCookieStore permission for authentication purposes.

Home Basic

​General information

​In a Web App

​Step 1 : Import the pre-prepared JavaScript files and stylesheets

​Important !

​Step 2 : Configure authentication with our dedicated component

​Step 3 : Use the web components wherever you want

​Internationalization

​Link for each language

​FR

​en-GB

​In a Mobile App

​Loading the web components

​Authentication in Android WebView

​Application authorizations

​Android application permissions

​Permissions for the WebView integrating the HOME Interfaces

​Application authorizations

​Application authorizations

General information

In a Web App

Step 1 : Import the pre-prepared JavaScript files and stylesheets

Important !

Step 2 : Configure authentication with our dedicated component

Step 3 : Use the web components wherever you want

Internationalization

Link for each language

FR

en-GB

In a Mobile App

Loading the web components

Authentication in Android WebView

Application authorizations

Android application permissions

Permissions for the WebView integrating the HOME Interfaces

Application authorizations

Application authorizations