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

Với JavaScript Consumer SDK, ứ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 dựa trên nền tảng web bản đồ. Nhờ đó, người dùng tiêu dùng có thể xem tiến trình giao hàng của họ. Hướng dẫn này giả định rằng bạn đã thiết lập Fleet Engine với Khoá API và dự án trên Google Cloud. Vui lòng xem Fleet Engine để biết thông tin chi tiết.

Bạn thiết lập JavaScript Consumer SDK theo các bước sau:

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

Bật Maps JavaScript API

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

Thiết lập yêu cầu uỷ quyền

Đối với các lệnh gọi phương thức API từ môi trường tin cậy thấp, Fleet Engine yêu cầu việc sử dụng Mã thông báo web JSON (JWT) được ký bằng một tài khoản dịch vụ thích hợp. Môi trường có mức độ tin cậy thấp bao gồm đ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 – một môi trường hoàn toàn đáng tin cậy. JWT được ký, mã hoá và chuyển đến ứng dụng cho các lượt tương tác máy chủ tiếp theo cho đến khi hết hạn hoặc không còn hợp lệ.

Phần phụ trợ của bạn phải xác thực và uỷ quyền dựa trên Fleet Engine bằng cách sử dụng cơ chế Thông tin đăng nhập mặc định của ứng dụng tiêu chuẩn. Nhãn hiệu sử dụng JWT đã được ký bằng một tài khoản dịch vụ thích hợp. Để biết danh sách vai trò của tài khoản dịch vụ, hãy xem các vai trò của tài khoản dịch vụ Fleet Engine trong phần Kiến thức cơ bản về Fleet Engine.

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

Ngược lại, phần phụ trợ của bạn phải xác thực và uỷ quyền dựa trên Fleet Engine bằng Thông tin đăng nhập mặc định của ứng dụng tiêu chuẩn cơ chế cụ thể.

Việc uỷ quyền hoạt động như thế nào?

Việc uỷ quyền bằng dữ liệu của Công cụ quản lý đội xe 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 bạn thiết lập tính năng xác thực và uỷ quyền trong ứng dụng dựa trên web, máy chủ phụ trợ của bạn phải có khả năng phát hành Mã thông báo web JSON cho ứng dụng dựa trên web để truy cập vào Công cụ của đội xe. Ứng dụng dựa trên web của bạn sẽ gửi các JWT này cùng với các yêu cầu để Công cụ xe nhận ra các yêu cầu đó đã đượ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 phần Kiến thức cơ bản về công cụ của Fleet.

Cụ thể, hãy lưu ý những điều sau đây đối với SDK Người 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 Người dùng JavaScript, SDK này sẽ yêu cầu mã thông báo từ máy chủ bằng trình tìm nạp mã thông báo uỷ quyền. Lệnh này thực hiện việc này khi bất kỳ trường hợp nào sau đây xảy ra:

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

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

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

Nếu không, SDK Người 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.

    • Một 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 vượt qua ngày hết hạn thời gian tính bằng giây, kể từ thời điểm tìm nạp đến thư viện như được hiển thị 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. Chiến dịch này URL (SERVER_TOKEN_URL) phụ thuộc vào cách triển khai chương trình phụ trợ của bạn. URL mẫu 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ã thông báo xác thực

Các ví dụ sau đây cho thấy 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,
  };
}

Các bước tiếp theo