Embed charts in web or mobile applications

If you want to show the result of your data visualization outside the DoubleCloud console, you can embed a supported chart into your web page or a mobile product. If you want to know more about the process of embedding, see Secure embedding.

To securely embed a chart from DoubleCloud Visualization into your website or product, you need to complete the following steps:

• Create an embedding key
• Create an embedding entity
• Create a signed link
• Configure the size and border of the embedded chart iFrame

Let's start.

Create an embedding key

To create an embedding key for your workbook:

1. Open the Visualization page in the console.

2. Open the workbook for which you want to create an embedding key.

3. In the upper-right corner of the page, click Embedding keys. You'll see the following window:

   

4. Click + Create key.

5. Name your key and click Create. You'll see your key in the following dialog:

   

   Save your private key

   Your private key is generated and shown to you only once, DoubleCloud doesn't store or log it anywhere. Please save it in a safe place.

6. Copy or download file with key.

Now that you have an embedding key, create an embedding entity for the chart you want to integrate into your product.

Create an embedding entity

An embedding entity describes the following:

• The chart that needs to be embedded

• Chart dependencies - (dataset and connection)

• Parameters that can be changed in the URL without the need to sign the request again.

To create an embedding entity:

1. Open the wizard for the chart you want to embed.

2. On top of the page to the right of the breadcrumbs, click → Embedding settings. You'll see the following window:

   

3. Click + Create embed. You'll see the following dialog:

   

4. In the Create embed dialog:

   1. Name your embedding entity.

   2. From the dropdown menu, select the embedding key with which you want to sign the requests to Visualization.

   3. Under Unsigned parameters, specify the unsigned parameters you want to apply to your chart. These chart parameters can be later on the client side without regenerating the embedding token.

   4. Review the Dependencies for the chart.

   5. Click Create. You'll see the Embed created window with the usage example:

      

5. Copy the link example for future use and click Close.

6. You'll see your embed ID on the list:

   

Now you have both the entity and the key to sign for it with. The final step is to generate the link signed with a JWT token.

Create a signed link

To create a signed link:

1. Prepare the token payload:

   • Get your private key issued when creating the Embedding key.

   • Create a JWT payload with the following parameters:

     • embedId from the embedding entities list.

     • dlEmbedService: "doublecloud", the static service identifier.

     • iat, token issue time, in the UNIX timestamp format.

     • exp, token expiration time, in the UNIX timestamp format. Please note that the total token lifespan can't exceed 10 hours.

     • (optional) params Additional parameters: signed_param1: string | number.

     Example:

     {
     "embedId": "<your_embed_id>",
     "dlEmbedService": "doublecloud",
     "iat": number, // Time of token creation, UNIX timestamp,
     "exp": number, // Time of token expiration, UNIX timestamp. Total token lifespan can't exceed 10 hours.
     "params": { // Optional signed parameters
        "signed_param1": string | number,
        "signed_param2": string | number,
        ...
        },
     }
     

2. Sign your token payload using your private key. Use the PS256 algorithm.

   Warning

   Use the private key value starting from the -----BEGIN RSA PRIVATE KEY----- line.

3. Use the code examples below to create a JWT token:

   Python

   Go

   NodeJS

   import time
   import jwt
   import json
   ​
   private_key = b"""<your_private_embedding_key>"""
   ​
   now = int(time.time())
   payload = {
      
   'embedId': "<your_embedId>",
   'dlEmbedService': "doublecloud",
   'iat': now,
   'exp': now + 360,
   "params": {  }}
   ​
   # JWT generation.
   encoded_token = jwt.encode(
      payload,
      private_key,
      algorithm='PS256',
      )
   
   print(encoded_token)
   

   package main
   
   import (
      "fmt"
      "time"
   
      "github.com/golang-jwt/jwt/v5"
   )
   
   func main() {
      privateKey, err := jwt.ParseRSAPrivateKeyFromPEM([]byte(`<your_private_embedding_key>`))
   
      now := time.Now().Unix()
      payload := jwt.MapClaims{
         "embedId":        "<your_embedId>",
         "dlEmbedService": "doublecloud",
         "iat":            now,
         "exp":            now + 360,
         "params":         map[string]interface{}{},
      }
   
      token := jwt.NewWithClaims(jwt.SigningMethodPS256, payload)
      signedToken, err := token.SignedString(privateKey)
      if err != nil {
         fmt.Println("Error generating token:", err)
         return
      }
   
      fmt.Println(signedToken)
   }
   

   Package requirements

   To run the above code, make sure you have the jwt-go package installed.

   If you don't have it on your system, run the following to install it:

   go install github.com/golang-jwt/jwt/v5@latest
   

   const privateKey = `<your_private_key>`;
   
   const now = Math.floor(Date.now() / 1000);
   const payload = {
   embedId: '<your_embedId>',
   dlEmbedService: 'doublecloud',
   iat: now,
   exp: now + 360,
   params: {},
   };
   
   const jwt = require('jsonwebtoken');
   
   const encodedToken = jwt.sign(payload, privateKey, {
   algorithm: 'PS256',
   });
   
   console.log(encodedToken);
   

   Package requirements

   To run the above code, make sure you have the jsonwebtoken package installed.

   If you don't have it on your system, run the following to install it with npm :

   npm install jsonwebtoken
   

4. Compose the embedding URL:

   https://app.double.cloud/embeds/chart?__dl_embed_token=<TOKEN>
   

Configure the size and border of the embedded chart iFrame

Your chart will be displayed inside an iFrame. Make sure you configure its size to fit your needs:

1. Set the height and width of the chart in pixels.

2. Define the width of the frameborder around the chart in pixels.

It should look as follows:

<iframe src="https://app.double.cloud/embeds/chart?__dl_embed_token=<TOKEN>" width="600" height="400" frameborder="0">
</iframe>

Now you can try and open the embedded chart in your browser.

See also

• Charts reference
• Use Visualization API