Embedding private charts
Note
This feature is only available with the Business service plan.
You can securely embed private charts into a website or app using special links with a JWT token
Embedding private charts only works in the new DataLens object model at the workbook level and is only available to the workbook administrator.
How to embed a private chart
-
Create a key for embedding:
Note
You can use one key to embed multiple objects.
-
Go to the DataLens home page
. -
In the left-hand panel, select
Collections and workbooks. -
Open the workbook where the chart to embed is located.
-
At the top of the screen, click
and select Keys for embedding. -
In the window that opens:
-
Click
Create key. -
Enter the key name and click Create.
-
At the bottom, click Download key file or copy the key value.
Warning
After you close the window, all data from it will be lost.
The new key for embedding will appear in the list.
-
-
-
Configure the embedding for a private chart:
Note
You can configure multiple embeddings for each chart.
-
In the row with the required chart, click
and select Embedding settings. -
In the window that opens, click
New embedding. -
In the settings window, specify:
- Name: Enter a name for the embedding.
- Key: Select a previously created key for embedding.
- Unsigned parameters: Specify unsigned parameters that can be provided in the link for embedding.
-
Click Create. In the ID column, copy the ID of the object to embed, and then click Close.
-
-
Create a token:
-
Prepare a payload for the token, i.e., information about the object to embed. The payload contains the following fields:
-
embedId
: ID of the object to embed. -
iat
: JWT token's issue time in Unix Timestamp format. -
exp
: Token expiration time in Unix Timestamp format.Warning
Tokens with a difference of more than 10 hours between
exp
andiat
are considered invalid. -
dlEmbedService
: Service ID string constant,YC_DATALENS_EMBEDDING_SERVICE_MARK
. -
params
: Optional property that defines signed chart parameters transferred as part of the token. They cannot be changed without regenerating the token.Example:
{ "embedId": "ieez7********", "iat": 1516239022, "exp": 1516240822, "dlEmbedService": "YC_DATALENS_EMBEDDING_SERVICE_MARK", "params": { "param1": "value1", "param2": "value2" } }
-
-
To create a JWT token, sign the prepared payload with the private key you got earlier when creating the key for embedding.
Note
Use the
PS256
algorithm when creating the JWT.To create a JWT token, use these code samples:
PythonNode.jsGoInstall the
cryptography
module to use thePS256
algorithm:pip3 install cryptography
Run the following code:
import time import jwt import json private_key = b"""<private_key>""" now = int(time.time()) payload = { 'embedId': "<ID_of_object_to_embed>", 'dlEmbedService': "YC_DATALENS_EMBEDDING_SERVICE_MARK", 'iat': now, 'exp': now + 360, "params": { }} # JWT generation. encoded_token = jwt.encode( payload, private_key, algorithm='PS256', ) print(encoded_token)
Install the jsonwebtoken
package using npm :npm install jsonwebtoken
Run the following code:
const privateKey = `<private_key>`; const now = Math.floor(Date.now() / 1000); const payload = { embedId: '<ID_of_object_to_embed>', dlEmbedService: 'YC_DATALENS_EMBEDDING_SERVICE_MARK', iat: now, exp: now + 360, params: {}, }; const jwt = require('jsonwebtoken'); const encodedToken = jwt.sign(payload, privateKey, { algorithm: 'PS256', }); console.log(encodedToken);
Install the jwt-go
package:go install github.com/golang-jwt/jwt/v5@latest
Run the following code:
package main import ( "fmt" "time" "github.com/golang-jwt/jwt/v5" ) func main() { privateKey, err := jwt.ParseRSAPrivateKeyFromPEM([]byte(`<private_key>`)) now := time.Now().Unix() payload := jwt.MapClaims{ "embedId": "<ID_of_object_to_embed>", "dlEmbedService": "YC_DATALENS_EMBEDDING_SERVICE_MARK", "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) }
-
Generate a link for embedding:
https://datalens.yandex.cloud/embeds/chart#dl_embed_token=<token>
Where
<token>
is the JWT token.
-
-
Add an embedding link to your website or app, for example:
<iframe src="https://datalens.yandex.cloud/embeds/chart#dl_embed_token=<token>" width="600" height="400" frameborder="0"></iframe>
Where:
src
: Embedding URL<token>
: JWT tokenwidth
: Chart widthheight
: Chart heightframeborder
: Chart boarder (yes or no)
Unsigned parameters
When creating an object to embed, you can specify one or more unsigned parameters. These parameters are not added to the token. You can provide them directly in the URL before the token hash. This allows you to change some widget parameters on the client side without recreating the token.
For example, if the chart uses the from
and to
parameters to filter by time, add the same unsigned parameters when creating the object. You can provide these parameters in the embedding link before the token hash:
<iframe src="https://datalens.yandex.cloud/embeds/chart?from=2022-01-01&to=2023-02-05#dl_embed_token=<token>" width="600" height="400" frameborder="0"></iframe>
Where:
src
: Embedding URL<token>
: JWT token.from=2022-01-01&to=2023-02-05
: Unsigned parameters specified when setting up the embedding.