Bắt đầu

Trao đổi session token

Luồng trao đổi hai bước biến license key thành session token trình duyệt có thể dùng an toàn — và lý do vì sao nó cần hai bước, không phải một.

This guide hasn't been translated into English yet, showing the Vietnamese version.

Switch to the Vietnamese version of this page

License key của bạn chỉ nên nằm trên server — không bao giờ được đưa ra trình duyệt. Để có được session token hoạt động cần hai request riêng biệt, không phải một: server của bạn yêu cầu một mã trao đổi ngắn hạn trước, sau đó chính trình duyệt đổi mã đó lấy session token thật. Việc tách ra như vậy giúp Comnoira tự xác nhận độc lập rằng request thực sự đến từ website của bạn trước khi cấp bất cứ thứ gì dùng được.

Bước 1 — server của bạn yêu cầu mã trao đổi

curl -X POST https://api.comnoira.com/viewer/session \
  -H "X-License-Key: $COMNOIRA_LICENSE_KEY" \
  -H "Content-Type: application/json"

Phản hồi trả về không phải một session token dùng được ngay — đó là một mã trao đổi chỉ dùng được một lần:

{
  "exchangeToken": "exch_9f2c...",
  "expiresAt": "2026-08-06T12:01:00Z"
}

Mã này hết hạn sau 60 giây và chỉ đổi được một lần. Hãy lấy mã mới ở mỗi lần tải trang — đừng cache lại, và đừng thử lại với mã đã đổi rồi.

Bước 2 — gửi cho trình duyệt, để SDK hoàn tất trao đổi

Trả về exchangeToken từ route backend của bạn. Callback getSessionToken trong script nhúng nên trả về giá trị này — dù tên gọi vậy, ở bước này nó đang trả về mã trao đổi, chưa phải session token cuối cùng:

<div id="comnoira-viewer"></div>
<script src="https://cdn.comnoira.com/sdk/v1/comnoira.min.js"></script>
<script>
  function getSessionToken() {
    return fetch('/your-backend-route')
      .then((res) => res.json())
      .then((data) => data.exchangeToken);
  }

  Comnoira.init({
    target: '#comnoira-viewer',
    model: 'your-model-id',
    getSessionToken,
  });
</script>

Từ đó, SDK gọi thẳng tới Comnoira từ trình duyệt của người mua để hoàn tất trao đổi — đây mới là bước thực sự tạo ra session token dùng được:

POST https://api.comnoira.com/viewer/session/exchange
{ "exchangeToken": "exch_9f2c..." }

Comnoira kiểm tra header Origin thật của trình duyệt so với các domain đã đăng ký cho mã nhúng, và xác nhận license của bạn còn active — chỉ khi cả hai đều đúng thì mới cấp session token và trả về cho trình duyệt. SDK sau đó dùng token đó để khởi động iframe trình xem.

Nếu mã nhúng lỗi âm thầm, không có lỗi console nào, nguyên nhân phổ biến nhất là origin không khớp — domain của trang chưa được đăng ký cho mã nhúng bạn đang dùng. Kiểm tra điều này đầu tiên, trong dashboard Comnoira, trước khi làm gì khác.

Vì sao cần hai bước thay vì một

Nếu để trình duyệt nhận thẳng phản hồi từ server của bạn, nghĩa là phải tin tưởng bất kỳ domain nào mà server nói là nó đang phục vụ — điều rất dễ sai qua redirect, domain staging, hay bản deploy preview. Để trình duyệt tự hoàn tất trao đổi nghĩa là Comnoira kiểm tra đúng domain mà request thực sự đến từ đó, chứ không chỉ tin lời server. Nó cũng có nghĩa mã trao đổi và session token mà nó tạo ra có thể hết hạn và bị thu hồi độc lập với nhau.

Nếu trình xem khởi động nhưng hiện khung trắng, gần như luôn là do session token đã hết hạn hoặc đã dùng rồi — hãy lấy mã trao đổi mới và tải lại.