Integrating DLV into Third-Party Systems

Open management provides a unified key for embedding multiple screens into third-party applications, avoiding the need to maintain the mapping between a screen and a key when a user adds or deletes a screen.

Prerequisites

Before using AppKey to integrate a screen into a third-party application, ensure that the screen is in the published state and token verification has been enabled during screen publishing.

Creating Applications

Log in to the DLV console.
In the navigation tree on the left, choose Control Center > Open Management.
On the Open Management page, click Create Application.

In the Create Application dialog box, set the following parameters and click OK.

**Table 1** Application parameters
Parameter	Description
Name	An application name can contain only letters, digits, underscores (_), and hyphens (-), and cannot exceed 32 characters.
Authorized Service Type	The default value is screen.
Resource	The default value is All.
Remarks	Enter application description.

Figure 1 Creating an application

Viewing the AppKey and Key of an Application

Log in to the DLV console.
In the navigation tree on the left, choose Control Center > Open Management.
In the application list on the Open Management page, find the required application and view the AppKey and secret of the application. To copy them, mouse over the AppKey or secret and click .

Figure 2 Application list

Generating a URL for Integrating a Screen with a Third-Party System

A screen URL for integrating a third-party system must contain the AppKey and secret of the application. DLV screens and combined screens can be integrated into third-party systems. The following uses a DLV screen as an example to describe how to generate the URL of the screen integrated into a third-party system.

Publish the screen by following the instructions in section Publishing Screens. During the publishing, enable token authentication and obtain the link to the screen. The link format is as follows:

https://xxx/dlv/vision/share/?id=a33b74ac5c6343cab47ae3386efdfcb4&locale=zh-cn&region=xxx

The link address of the screen to be embedded in the third-party system needs to add some extra parameters. The format of the embedded link address is as follows:

https://xxx/dlv/vision/share/?id=a33b74ac5c6343cab47ae3386efdfcb4&dlv_time={current system time}&app_id={AppKey on the Open Management page}&dlv_signature={signature}&locale=zh-cn&region=xxx

id: indicates the share ID. When publishing a screen, obtain the ID next to share in the screen sharing link, as shown in the red box in Figure 3.
Figure 3 Obtaining shareId
dlv_time: current system time, which can be obtained by calling a system function in the application code.
```
long time = System.currentTimeMillis();
```
app_id: AppKey of the application. For details about how to obtain the AppKey, see Viewing the AppKey and Key of an Application.
dlv_signature: signature. The signature must be generated through code. The procedure for generating the signature is as follows:
Use the application key to generate a signature using the HMACSHA256 encryption algorithm.
```
String data = shareID + "|" + time + "|" + appId;
String signature = HMACSHA256(data.getBytes(), token.getBytes());
```
1. Use vertical bars (|) to separate id (variable shareID), dlv_time (variable time), and app_id (variable appId) as the data for generating the signature.
2. On the Open Management page, obtain the application key and define it as the variable token in the application code.
  For details about how to obtain the AppKey and key, see Viewing the AppKey and Key of an Application.
locale: language identifier. zh-cn indicates Chinese and en-us indicates English.
region: region where the service is used. Set this parameter based on the region where the screen is located.

If you need to integrate a combined screen into a third-party system, publish the combined screen by referring to the instructions in Publishing Combined Screens. During the publishing, enable token verification and obtain the link to the combined screen. Set dlv_time and app_id parameters to obtain the link address of the combined screen to be integrated with the third-party system.

Integrating a DLV Screen into a Third-Party System (Using Java Sample Code)

The following is Java sample code for integrating a DLV screen into a third-party system. For details about how to generate a screen URL in the code, see Generating a URL for Integrating a Screen with a Third-Party System.

public static void main(String[] args) {
    String token = "**********************";
    String shareId = "**********************";
    String appId = "**********************";
    System.out.println(getShareUrlWithToken(shareId, token, appId));
}

public static String getShareUrlWithToken(String shareID, String token, String appId){
    long time = System.currentTimeMillis();
    String data = shareID + "|" + time + "|" + appId;
    String signature = HMACSHA256(data.getBytes(), token.getBytes());
    String url = "https://xxx/dlv/vision/share/?id="+ shareID +
"&dlv_time="+time+"&dlv_signature="+ signature+"&region=xxx" + "&app_id=" + appId;
    return url;
}

public static String HMACSHA256(byte[] data, byte[] key) {
try  {
    SecretKeySpec signingKey = new SecretKeySpec(key, "HmacSHA256");
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(signingKey);
    byte[] var1 = mac.doFinal(data);
    String var2 = byteArrayToHexString(var1);
    return var2;
} catch (NoSuchAlgorithmException e) {
    e.printStackTrace();
} catch (InvalidKeyException e) {
    e.printStackTrace();
}
    return null;
}

public static String byteArrayToHexString(byte[] b) {
    StringBuilder strBuilder = new StringBuilder();
    String tmp;
    for (int n = 0; b!=null && n < b.length; n++) {
        tmp = Integer.toHexString(b[n] & 0XFF);
        if (tmp.length() == 1)
        strBuilder.append('0');
        strBuilder.append(tmp);
    }
    return strBuilder.toString().toUpperCase();
}

DLV SDK Introduction

DLV provides two SDK packages: dlv.js and dlv.min.js. The two SDK packages implement the same functions in different ways.

dlv.js: modular SDK package, which is imported through require and import.
Download address: https://dlv-dev-tools2.obs.ap-southeast-3.myhuaweicloud.com/cli/dlv.js
dlv.min.js: non-modular SDK package, which is imported externally, for example, <script src='dlv.min.js'></script>.
Download address: https://dlv-dev-tools2.obs.ap-southeast-3.myhuaweicloud.com/cli/dlv.min.js

Currently, the DLV SDK provides only the embedded(option) method and does not return any value. Table 2 describes the input parameters.

**Table 2** option parameter description
Parameter	Mandatory	Type	Description
url	Yes	string	URL of the screen embedded in the third-party system, which is obtained by invoking the API in the preceding steps.
container	Yes	domElement	dom node where the screen is embedded.
parameters	No	object	Pass parameter of the screen. The default value of the variable is set by setting the hash parameter in the URL.
scrolling	No	string	Specifies whether the screen can be scrolled. The options are no, yes, and auto. The default value is no.
height	No	string	Percentage of the screen height (pixel) in the current container. The default value is 100%.
width	No	string	Percentage of the screen width (pixel) in the current container. The default value is 100%.

Calling the DLV SDK by a Third-Party System to Integrate a Screen (Using Node JS Sample Code)

The following uses the dlv.js SDK package as an example to describe how to call the SDK provided by DLV to integrate a DLV screen into a third-party application.

The following is an example of Node JS:

In the server code of the third-party application, create a *.js file, define an API, and generate a DLV screen URL by referring to the instructions in Generating a URL for Integrating a Screen with a Third-Party System.

The following is an example of the server code getDlvURL.js:

/* Code of the user server, defining the API /app (taking the koa framework as an example)
Input parameter:
shareId: screen sharing ID
Response:
url: URL for integrating a third-party system with a screen
*/
const router = require('koa-router')();
var CryptoJS = require("crypto-js");

router.get('/app', async (ctx) => {
var {shareId} = ctx.query; // screen sharing ID, which is transferred as a parameter when the API is called //For example, shareId = '6320803b882b4e2a91d973b3a5d71625';.
    var secret = '*******M5huvqcCpXz************'; // Application secret on the open management page
    var appId = "*******26f94c9a3016f94e7********"; // AppKey of the application on the open management page 
    var time = new Date().getTime();  // Current system time
    var data = shareId + "|" + time  + "|" + appId;    
    var hash = CryptoJS.HmacSHA256(data, secret);    
    var signature = (CryptoJS.enc.Base64.stringify(hash));  // Signature. The signature must be generated using code and the application key through the HMACSHA256 encryption algorithm.
    var url = `https://xxx/dlv/vision/share/?id=${ shareId }&dlv_time=${ time }&app_id=${ appId }&dlv_signature=${ signature }&locale=zh-cn&region=xxx`;

    ctx.body = {  //Result returned by the API
        url
    }
})

module.exports = router;

Download a DLV SDK package. For details about the download addresses, see DLV SDK Introduction. Save the downloaded SDK file (for example, dlv.js) to the directory where the third-party application client code is located.

For example, ./sdk/dlv.js.

In the code of the third-party application client, call the API defined in 1 to obtain the screen URL, and then call the DLV SDK API to embed and integrate the URL.

Currently, the DLV SDK provides only the embedded(option) method. In the API input parameters, the parameters parameter can be used to transfer the URL hash parameter of the screen and set the default value of the parameter.

The following is an example of the client code EmbedDlvSreen.js:

/*
The following is the sample code for using the DLV SDK. The dlv.js SDK package is used as an example.
*/

import DLV from './sdk/dlv.js';

// Use the AJAX of jQuery as an example. Call the API/application for obtaining the screen URL and then call the DLV SDK API to embed the URL into the screen.
$.ajax({ 
    type: "GET",
    url: "/app",
    data: { shareId: '*******882b4e2a91d9******81625' },
    dataType: "json",
    success: function(data){
        var url = data.url; 
        // options is the parameter of the embed method.
        var options = { 
            url: url, //URL for integrating a third-party system with a screen, which is obtained by calling the API in the preceding step.
            container: document.getElementById("id-test"),  // dom node where the screen is embedded
            parameters: { //Input parameter of the screen. The default value of the variable is set by setting the hash parameter in the URL.
                name: 'admin' // the value of name is 'admin', that is, `https://xxx/dlv/vision/share/?id=fb0711b3999c4548826028884e99e720&locale=zh-cn&region=xxx#name=admin`;
            },
            scrolling: "no", //Specifies whether the screen can be scrolled.
            height: "100%", //Height of the screen.
            width: "100%" //Width of the screen.
        };

       //Call the DLV SDK API to integrate with the screen.
        DLV.embed(options);
    }
});

Resetting Application Keys

Log in to the DLV console.
In the navigation tree on the left, choose Control Center > Open Management.
In the application list on the Open Management page, locate the desired application and click Reset in the Operation column.
In the displayed dialog box, click Yes.

Editing Applications

Log in to the DLV console.
In the navigation tree on the left, choose Control Center > Open Management.
In the application list on the Open Management page, locate the desired application and click Edit in the Operation column.
In the displayed dialog box, modify the configuration parameters and click OK.

Figure 4 Editing applications

Deleting Applications

Log in to the DLV console.
In the navigation tree on the left, choose Open Management.
In the application list on the Open Management page, locate the desired application and click Delete in the Operation column.
In the displayed dialog box, click Yes to delete the data.