Thiết lập SDK JavaScript cho người dùng

Với SDK JavaScript dành cho người tiêu dùng, ứng dụng dành cho người tiêu dùng của bạn có thể hiển thị vị trí của xe và các vị trí quan tâm khác được theo dõi trong Fleet Engine trên một bản đồ dựa trên web. Nhờ đó, người dùng là người tiêu dùng có thể xem tiến trình của lô hàng. Hướng dẫn này giả định rằng bạn đã thiết lập Fleet Engine bằng dự án trên đám mây Google Cloud và khoá API liên kết. Hãy xem Fleet Engine để biết thông tin chi tiết.

Bạn thiết lập SDK Người tiêu dùng JavaScript theo các bước sau:

  1. Bật Maps JavaScript API.
  2. Thiết lập quy trình uỷ quyền.

Bật Maps JavaScript API

Bật Maps JavaScript API trong dự án Google Cloud Console mà bạn dùng cho phiên bản Fleet Engine. Để biết thêm thông tin, hãy xem phần Bật API trong tài liệu về API JavaScript của Maps.

Thiết lập quy trình uỷ quyền

Fleet Engine yêu cầu sử dụng Mã thông báo web JSON (JWT) cho các lệnh gọi phương thức API từ môi trường có độ tin cậy thấp: điện thoại thông minh và trình duyệt.

JWT bắt nguồn từ máy chủ của bạn, được ký, mã hoá và chuyển đến ứng dụng để tương tác với máy chủ sau đó cho đến khi hết hạn hoặc không còn hợp lệ.

Thông tin chi tiết quan trọng

Ứng dụng dành cho người tiêu dùng của bạn phải xác thực người dùng cuối bằng vai trò delivery_consumer trong dự án trên đám mây của Google Cloud để chỉ trả về thông tin dành riêng cho người tiêu dùng. Bằng cách này, Fleet Engine sẽ lọc và loại bỏ tất cả thông tin khác trong phản hồi. Ví dụ: trong một nhiệm vụ không có sẵn, không có thông tin vị trí nào được chia sẻ với người dùng cuối. Xem vai trò của tài khoản dịch vụ đối với các tác vụ theo lịch.

Quy trình uỷ quyền hoạt động như thế nào?

Việc uỷ quyền bằng dữ liệu của Fleet Engine liên quan đến cả việc triển khai phía máy chủ và phía máy khách.

Uỷ quyền phía máy chủ

Trước khi thiết lập quy trình xác thực và uỷ quyền trong ứng dụng dựa trên nền tảng web, máy chủ phụ trợ của bạn phải có khả năng cấp Mã thông báo web JSON cho ứng dụng dựa trên nền tảng web để truy cập vào Fleet Engine. Ứng dụng dựa trên nền tảng web của bạn sẽ gửi các JWT này cùng với yêu cầu để Fleet Engine nhận ra các yêu cầu đó là đã được xác thực và được uỷ quyền truy cập vào dữ liệu trong yêu cầu. Để biết hướng dẫn về cách triển khai JWT phía máy chủ, hãy xem phần Phát hành mã thông báo web JSON trong Kiến thức cơ bản về Fleet Engine.

Cụ thể, hãy lưu ý những điều sau đây đối với SDK Người tiêu dùng JavaScript để theo dõi lô hàng:

Uỷ quyền phía máy khách

Khi bạn sử dụng SDK JavaScript cho người dùng, SDK này sẽ yêu cầu mã thông báo từ máy chủ bằng cách sử dụng trình tìm nạp mã thông báo uỷ quyền. Điều này xảy ra khi một trong các trường hợp sau đây là đúng:

  • Không có mã thông báo hợp lệ, chẳng hạn như khi SDK chưa gọi trình tìm nạp trong một lượt tải trang mới hoặc khi trình tìm nạp chưa trả về mã thông báo.

  • Mã thông báo đã hết hạn.

  • Mã thông báo sẽ hết hạn trong vòng một phút.

Nếu không, SDK Người tiêu dùng JavaScript sẽ sử dụng mã thông báo hợp lệ đã phát hành trước đó và không gọi trình tìm nạp.

Tạo trình tìm nạp mã thông báo uỷ quyền

Tạo trình tìm nạp mã thông báo uỷ quyền theo các nguyên tắc sau:

  • Trình tìm nạp phải trả về một cấu trúc dữ liệu có hai trường, được gói trong một Promise như sau:

    • Một chuỗi token.

    • Số expiresInSeconds. Mã thông báo sẽ hết hạn sau khoảng thời gian này sau khi tìm nạp. Trình tìm nạp mã xác thực phải chuyển thời gian hết hạn (tính bằng giây) từ thời điểm tìm nạp đến thư viện như trong ví dụ.

  • Trình tìm nạp phải gọi một URL trên máy chủ của bạn để truy xuất mã thông báo. URL này (SERVER_TOKEN_URL) phụ thuộc vào cách triển khai phần phụ trợ của bạn. URL ví dụ sau đây là dành cho phần phụ trợ của ứng dụng mẫu trên GitHub:

    • https://SERVER_URL/token/delivery_consumer/TRACKING_ID

Ví dụ – Tạo trình tìm nạp mã xác thực

Các ví dụ sau đây minh hoạ cách tạo trình tìm nạp mã thông báo uỷ quyền:

JavaScript

async function authTokenFetcher(options) {
  // options is a record containing two keys called
  // serviceType and context. The developer should
  // generate the correct SERVER_TOKEN_URL and request
  // based on the values of these fields.
  const response = await fetch(SERVER_TOKEN_URL);
  if (!response.ok) {
    throw new Error(response.statusText);
  }
  const data = await response.json();
  return {
    token: data.Token,
    expiresInSeconds: data.ExpiresInSeconds
  };
}

TypeScript

function authTokenFetcher(options: {
  serviceType: google.maps.journeySharing.FleetEngineServiceType,
  context: google.maps.journeySharing.AuthTokenContext,
}): Promise<google.maps.journeySharing.AuthToken> {
  // The developer should generate the correct
  // SERVER_TOKEN_URL based on options.
  const response = await fetch(SERVER_TOKEN_URL);
  if (!response.ok) {
    throw new Error(response.statusText);
  }
  const data = await response.json();
  return {
    token: data.token,
    expiresInSeconds: data.ExpiresInSeconds,
  };
}

Bước tiếp theo