> For the complete documentation index, see [llms.txt](https://docs.datasuite.vn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.datasuite.vn/chia-se-va-quan-ly-truy-cap/nhung-bao-cao-len-web-app-ben-ngoai.md).

# Nhúng báo cáo lên web/app bên ngoài

Data Suite hỗ trợ biểu diễn báo cáo trên website hoặc app của khách hàng theo hình thức nhúng code bảo mật (Secured Embedded Report).

<figure><img src="/files/zN8I5BtUcfRsakLKWblY" alt=""><figcaption></figcaption></figure>

### Sơ đồ luồng kết nối

<figure><img src="/files/GMxVuQnZB17rPcW98Orc" alt=""><figcaption></figcaption></figure>

### Chuẩn bị

* Cần có đội ngũ kỹ thuật từ phía khách hàng để tích hợp luồng xác thực và nhúng báo cáo vào website hoặc ứng dụng của khách hàng.
* Người thao tác tạo App Token và lấy mã nhúng cần có quyền Admin ở Organization.

### Hướng dẫn tích hợp

{% stepper %}
{% step %}

#### Chọn báo cáo Data Suite cần nhúng

Truy cập báo cáo ⇒ Menu \[⋮] ⇒ Get Embed Code, sau đó làm theo hướng dẫn. Luồng tích hợp gồm 3 bước:

1. Tạo App Token
2. Tích hợp luồng xác thực & tạo Session Token (cần có App Token)
3. Nhúng (embed) báo cáo vào web/app của khách hàng (cần có Session Token)

<figure><img src="/files/SF8bQR2L2Owp0LL4aPuS" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/mS3fIIDnGlvdBQjyGBTO" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Tạo App Token

Truy cập màn hình quản lý App Token (nhấn vào link ở Step 1, hoặc vào Manage Organization ⇒ App Tokens) ⇒ Nhấn Create App Token để tạo mới.

<figure><img src="/files/oAFPdnRHta9qij8Zv47w" alt=""><figcaption></figcaption></figure>

Lưu ý: App Token chỉ hiển thị 01 lần, người dùng cần lưu trữ ở nơi an toàn và không để lộ token.

<figure><img src="/files/DozdzjCv5DK3Cg1as03J" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Tạo Session Token bằng App Key (Yêu cầu code)

Tại project web/app của khách hàng, viết code tạo Session Token bằng cách gọi API của Data Suite.

Input:

* App Token để xác thực app.
* Email của người dùng đang xem (Current User/Logged In User) để kiểm tra quyền.

Output:

* Session Token, dùng để truyền vào URL param của iframe ở bước (4) Nhúng báo cáo.

<figure><img src="/files/FtYfcnSRjmQvDoSN18Ac" alt=""><figcaption></figcaption></figure>

Gợi ý: Khách hàng có thể tham khảo đoạn code tại Step 2 của Wizard hướng dẫn (tương thích với app ReactJS), hoặc sử dụng cURL tùy nhu cầu.
{% endstep %}

{% step %}

#### Nhúng báo cáo lên web/app (Yêu cầu code)

Sau khi đã tạo được Session Token, khách hàng copy đoạn code iframe tại Step 3 của Wizard hướng dẫn vào vị trí muốn hiển thị báo cáo, thay **\<embedToken>** bằng Session Token đã tạo.

<figure><img src="/files/zN8I5BtUcfRsakLKWblY" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Lưu ý: **Session Token có hiệu lực trong 30 phút.** Sau khi đã render thành công báo cáo trong iframe, các tương tác của người dùng cũng, hệ thống Data Suite vẫn sẽ verify Session Token, sau khi hết hiệu lực, giao diện báo cáo sẽ thông báo Token expired và không cho phép thao tác tiếp. Do đó, **khách hàng cần chủ động thiết lập thời gian tự động rotate Session Token/reload trang** để re-authen trước khi đến hạn.
{% endhint %}

### Nhúng nhiều báo cáo khác nhau

Khách hàng có nhu cầu nhúng nhiều báo cáo khác nhau, không nhất thiết phải viết code tạo Session Token nhiều lần, mà chỉ cần quan tâm request body sẽ gửi trong API call:

```
{
    viewerEmail: currentUser.email,
    tenantId: ***,
    projectId: ***,
    dashboardId: ***,
    pageId: ***
}
```

Khi Data Suite tạo snippet nhúng, chỉ khác nhau phần body này để định danh báo cáo. Tương tự với iframe sẽ khác nhau ở thuộc tính src:

```
<iframe
  src="https://<datasuite_domain>/embed/tenant/***/project/***/dashboard/***/page/***?embedToken=<embedToken>"
  />
```

### Phân quyền xem báo cáo nhúng

Báo cáo Data Suite luôn kiểm tra quyền dựa vào người dùng đang truy cập (logged in user), vì vậy khi nhúng báo cáo vào môi trường nằm ngoài Data Suite, bắt buộc phải truyền định danh của người dùng (email) để xác định quyền. Khi đó, người dùng xem báo cáo nhúng trên web/app của khách hàng, cũng giống như chính người dùng đó đang đăng nhập và xem báo cáo trực tiếp trên Data Suite.

Phạm vi phân quyền được áp dụng:

* **Access Control:** Người dùng có quyền xem báo cáo này hay không
  * Share báo cáo cho từng người dùng (role Viewer trở lên)
  * Gán role hệ thống cho người dùng (role Viewer trở lên)
  * Share báo cáo cho nhóm người dùng (User Group) và thêm người dùng vào nhóm
* **Row-level Security (RLS):** Người dùng được xem những dữ liệu nào trên báo cáo này
  * Gán người dùng vào các Data Role trong Data Model

### Đồng bộ danh sách người dùng

Để Embedded Report hoạt động chính xác và hiệu quả, khách hàng cần thêm người dùng (email) vào Organization và Workspace của mình, phân quyền cho người dùng đó trên Data Suite trước khi cho phép người dùng xem báo cáo trên web/app của khách hàng.

Ví dụ 1: Hệ thống khách hàng có 50 user, nếu muốn cho 50 user này xem được báo cáo nhúng, cần thêm 50 user này vào Organization trên Data Suite và phân quyền AC/RLS cho họ.

Ví dụ 2: Trường hợp khách hàng có 50 user, nhưng chỉ có 10 user được quyền xem báo cáo nhúng, thì chỉ cần thêm và phân quyền cho 10 user này.

### Quản lý embed session

Tại mục Manage Organization ⇒ App Tokens, khách hàng có thể theo dõi số lượt tải báo cáo thông qua môi trường Embed (iframe).

<figure><img src="/files/oyFgtyDpshzqO8bZOAgC" alt=""><figcaption></figcaption></figure>

Trường hợp App Token đã không còn dùng hoặc bị lộ, khách hàng cần revoke ngay để hạn chế rủi ro bảo mật dữ liệu.