Lên kế hoạch tuyến đường

Đôi khi, bạn có thể muốn lập kế hoạch cho tuyến đường mà ứng dụng cung cấp cho người dùng. Khi sử dụng mã thông báo tuyến đường từ Routes API, Routes Preferred API hoặc Route Optimization API, bạn có thể chỉ định hai điều cho tuyến đường đã lên kế hoạch:

• Hình nhiều đường cho tuyến đường

• Mục tiêu của tuyến đường

Ví dụ: sau đây là một số mục tiêu định tuyến mà bạn có thể đặt ra:

• Giảm thiểu thời gian giao hàng: Một doanh nghiệp giao đồ ăn có thể muốn giảm thiểu thời gian giao đồ ăn.

• Giảm thiểu thời gian di chuyển hoặc mức tiêu thụ nhiên liệu: Một doanh nghiệp hậu cần có thể muốn nâng cao hiệu quả của tài xế và giảm chi phí nhiên liệu.

• Giảm thiểu thời gian đến đích: Hoạt động điều phối dịch vụ có thể muốn giảm thiểu thời gian đưa người vận hành đến yêu cầu công việc.

• Giảm chi phí và cải thiện mức độ an toàn: Doanh nghiệp cung cấp dịch vụ đi chung xe có thể muốn tìm một tuyến đường có chi phí thấp hơn cho người đi xe và tránh một số khu vực vì lý do an toàn.

Quan trọng: Tuyến đường mà tài xế di chuyển có thể khác với tuyến đường bạn đã lên kế hoạch. Tình trạng giao thông hoặc đường sá thay đổi, xe rời khỏi tuyến đường đã lên kế hoạch hoặc chuyển sang tuyến đường nhanh hơn có thể làm thay đổi tuyến đường trong suốt chuyến đi. Mỗi khi SDK điều hướng tính toán một tuyến đường mới, SDK này sẽ sử dụng các tuỳ chọn định tuyến được đặt trong mã thông báo tuyến đường, chẳng hạn như tránh các tuyến đường có thu phí.

Để biết thêm thông tin về cách lập kế hoạch cho tuyến đường bằng mã thông báo tuyến đường, hãy xem phần Lấy mã thông báo tuyến đường trong Routes API và Chuyển đổi hình nhiều đường và mã thông báo tuyến đường trong Route Optimization API.

Lý do nên sử dụng mã thông báo tuyến đường cho mục tiêu tuyến đường

Với mã thông báo tuyến đường từ Routes API, Routes Preferred API hoặc Route Optimization API, bạn có thể kiểm soát tốt hơn tuyến đường được cung cấp:

• Lên kế hoạch trước cho tuyến đường để SDK điều hướng sử dụng.

• Chọn tuyến đường phù hợp nhất để Navigation SDK sử dụng. Nếu yêu cầu mã thông báo tuyến đường khi tạo tuyến đường trong Routes API, bạn sẽ nhận được mã thông báo tuyến đường cho mỗi tuyến đường được tạo. Sau đó, bạn có thể chọn mã thông báo cho tuyến đường mà bạn muốn sử dụng khi truyền mã thông báo đó đến SDK Điều hướng.

• Ước tính trước giá, bao gồm cả thông tin ước tính về thời gian đến dự kiến và khoảng cách. Mặc dù chi phí và thời gian thực tế có thể khác nhau, nhưng thông tin ước tính này giúp giảm khoảng cách giữa chi phí dự kiến và chi phí thực tế của tuyến đường.

• Chỉ định các mục tiêu tuyến đường nâng cao hơn, chẳng hạn như tuyến đường thân thiện với môi trường hoặc tuyến đường ngắn nhất.

Lưu ý: Mã thông báo tuyến đường dành cho một điểm xuất phát và điểm đến cụ thể tại một thời điểm cụ thể. Bạn phải tạo một yêu cầu mới cho Routes API, Routes Preferred API hoặc Route Optimization API để nhận mã thông báo tuyến đường mới.

Cách hoạt động của mã thông báo tuyến đường

Bạn có thể sử dụng Routes API, Routes Preferred API hoặc Route Optimization API để lập kế hoạch cho một tuyến đường bằng cách sử dụng các mục tiêu của tuyến đường. Bạn có thể truyền mã thông báo tuyến đường được trả về từ bất kỳ API nào trong số này đến SDK Điều hướng để hướng dẫn cách định tuyến xe của bạn.

Sau đây là những gì xảy ra khi bạn yêu cầu và sử dụng mã thông báo tuyến đường:

1. Routes API, Routes Preferred API hoặc Route Optimization API trả về một mã thông báo tuyến đường đã mã hoá, trong đó có hình nhiều đường của tuyến đường và mục tiêu của tuyến đường.

2. Bạn truyền mã thông báo tuyến đường đến SDK Điều hướng.

3. SDK Điều hướng bắt đầu chỉ đường trên tuyến đường bạn đã lên kế hoạch, ngay cả khi có tuyến đường nhanh hơn.

4. Trong chuyến đi, nếu tình hình giao thông hoặc điều kiện đường sá thay đổi hoặc nếu xe rời khỏi tuyến đường đã lên kế hoạch, thì SDK Điều hướng sẽ tính toán một tuyến đường mới tuân theo các mục tiêu và lựa chọn định tuyến được đặt trong mã thông báo tuyến đường của bạn.

Quy trình này giúp tuyến đường thực tế gần với tuyến đường bạn đã lên kế hoạch nhất có thể.

Lý do khiến tuyến đường đã lên kế hoạch có thể không được tuân thủ chính xác

Tính năng chỉ đường bắt đầu trên tuyến đường bạn đã lên kế hoạch, nhưng tuyến đường thực tế có thể khác với tuyến đường đó trong các trường hợp như sau:

• Xe bắt đầu di chuyển từ điểm xuất phát đã lên kế hoạch.
• Tình hình giao thông hoặc điều kiện đường sá thay đổi trong chuyến đi.
• Xe rời khỏi tuyến đường đã lên kế hoạch.

Những điểm khác biệt này có thể ảnh hưởng đến quãng đường, thời gian đến dự kiến và các đặc điểm quan trọng khác của chuyến đi mà bạn đã lên kế hoạch.

Lưu ý: Bạn nên luôn yêu cầu mã thông báo tuyến đường mới mỗi khi đặt điểm đến trong SDK Điều hướng và lên kế hoạch cho một số biến thể để tránh mọi tác động đến hoạt động kinh doanh của bạn.

Lên kế hoạch cho tuyến đường bằng mã thông báo tuyến đường

Bạn có thể lập kế hoạch cho một tuyến đường bằng cách tạo mã thông báo tuyến đường rồi truyền mã đó đến SDK Điều hướng, như mô tả trong các bước sau:

Bước 1: Tạo mã thông báo tuyến đường bằng Routes API, Routes Preferred API hoặc Route Optimization API

1. Yêu cầu mã thông báo tuyến đường bằng một trong các phương thức sau:

   • Routes API: computeRoutes. Để biết thêm thông tin về cách yêu cầu mã thông báo tuyến đường trong Routes API, hãy xem bài viết Tính toán tuyến đường và Lấy mã thông báo tuyến đường.

   • Routes Preferred API: computeCustomRoutes. Để biết thêm thông tin về cách yêu cầu mã thông báo tuyến đường trong Routes Preferred API, hãy xem phần Lập kế hoạch cho tuyến đường.

   • Route Optimization API: optimizeTours hoặc batchOptimizeTours. Để biết thêm thông tin về cách yêu cầu mã thông báo tuyến đường trong Route Optimization API, hãy xem bài viết Đường đa tuyến chuyển đổi và mã thông báo tuyến đường.

2. Thiết lập yêu cầu Routes API hoặc Routes Preferred API để đáp ứng các yêu cầu về việc sử dụng mã thông báo tuyến đường:

   • Đặt travelMode thành DRIVE hoặc TWO_WHEELER.
   • Đặt routingPreference thành TRAFFIC_AWARE hoặc TRAFFIC_AWARE_OPTIMAL.
   • Không sử dụng Via điểm tham chiếu.

Lưu ý: Bạn có thể chỉ định giá trị chính xác cho điểm xuất phát và điểm đến, chẳng hạn như lối vào, bến bốc dỡ hàng hoặc khu vực đón khách được chỉ định, trong mã thông báo tuyến đường bằng cách sử dụng mã thông báo điểm điều hướng.

Bước 2: Truyền mã thông báo tuyến đường đến SDK Điều hướng

1. Lưu trữ mã thông báo tuyến đường: Trong SDK Điều hướng, hãy thiết lập một chuỗi để lưu trữ mã thông báo tuyến đường. Ví dụ:

   let routeToken = "route token returned by Routes API"
   

   Ví dụ về mã thông báo tuyến đường được trả về:

   {
   // Other fields
   "routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g",
   }
   

2. Truyền mã thông báo tuyến đường đến SDK Điều hướng bằng phương thức setDestinationsWithToken:completionHandler: của mapView.navigator. Navigation SDK lấy điểm đến và các lựa chọn định tuyến từ mã thông báo tuyến đường, vì vậy, bạn không cần truyền điểm tham chiếu.

   Phương thức di chuyển được đặt trong ứng dụng của bạn, chẳng hạn như mapView.travelMode, phải là một trong các giá trị sau:

   • .driving (GMSNavigationTravelModeDriving): Lái xe. Đây là giá trị mặc định, vì vậy hầu hết các ứng dụng không cần thay đổi giá trị này.
   • .twoWheeler (GMSNavigationTravelModeTwoWheeler): Xe hai bánh.

   Mọi phương thức di chuyển khác đều khiến yêu cầu không thành công với .travelModeUnsupported (GMSRouteStatusTravelModeUnsupported). Với một trong hai giá trị được hỗ trợ, tuyến đường sẽ sử dụng phương thức di chuyển trong mã thông báo tuyến đường của bạn. Ví dụ: nếu ứng dụng của bạn sử dụng chế độ lái xe và mã thông báo tuyến đường của bạn là dành cho tuyến đường xe hai bánh, thì SDK Điều hướng sẽ cung cấp tuyến đường xe hai bánh. Để xác nhận tuyến đường sử dụng phương tiện nào, hãy kiểm tra resolvedParameters.travelMode. Để biết thêm thông tin, hãy xem phần Các lựa chọn định tuyến đã giải quyết.

   Lưu ý: Nếu ứng dụng của bạn sử dụng phiên bản SDK Điều hướng cũ hơn phiên bản 11.3, hãy sử dụng phương thức setDestinations:routeToken:callback: không dùng nữa và truyền cùng một điểm tham chiếu đích mà bạn đã dùng để tạo mã thông báo tuyến đường.

3. Kiểm tra trạng thái tuyến đường trong trình xử lý hoàn thành. Khi SDK Điều hướng hoàn tất việc tính toán tuyến đường, SDK này sẽ truyền một GMSNavigationRouteDescription đến trình xử lý hoàn tất của bạn. Nếu tìm thấy một tuyến đường từ vị trí của xe đến các điểm đến trong mã thông báo tuyến đường, thì routeStatus của nội dung mô tả tuyến đường sẽ là .OK (GMSRouteStatusOK) và bạn có thể bắt đầu hướng dẫn. Nếu không, trình xử lý hoàn thành cũng sẽ nhận được một NSError mô tả lỗi. Ví dụ:

   mapView.navigator?.setDestinationsWithToken(routeToken) { [weak self] routeDescription, error in
     if routeDescription?.routeStatus == .OK {
       self?.mapView.navigator?.isGuidanceActive = true
     }
   }
   

Lưu ý: Nếu bạn cần di chuyển lại trên cùng một tuyến đường, hãy yêu cầu mã thông báo tuyến đường mới.

Kiểm tra xem SDK Điều hướng có áp dụng mã thông báo tuyến đường của bạn hay không

Trạng thái tuyến đường là .OK có nghĩa là SDK Điều hướng đã tìm thấy một tuyến đường, nhưng không nhất thiết là tuyến đường bạn đã lên kế hoạch. Để kiểm tra xem tuyến đường có khớp với tuyến đường bạn đã lên kế hoạch hay không, hãy làm theo các bước sau trong trình xử lý hoàn thành:

1. Xác nhận rằng routeStatus của nội dung mô tả tuyến là .OK. Navigation SDK chỉ cung cấp thông tin chi tiết về mã thông báo tuyến đường khi tìm thấy một tuyến đường. Để biết thêm thông tin, hãy xem Bước 2.

2. Lấy routeTokenExecutionDetails của nội dung mô tả tuyến đường, một đối tượng tuân thủ giao thức GMSNavigationRouteTokenExecutionDetails. Nếu máy chủ không cung cấp thông tin chi tiết về mã thông báo tuyến đường, thì thuộc tính này sẽ là nil.

3. Kiểm tra thuộc tính tokenExecutionStatus của thông tin chi tiết về quá trình thực thi. Nếu là .tokenSuccessfullyApplied, thì tuyến đường đó khớp với tuyến đường bạn đã lên kế hoạch. Mọi trạng thái khác đều có nghĩa là tuyến đường có thể khác với tuyến đường bạn đã lên kế hoạch. Để biết thêm thông tin về từng trạng thái, hãy xem phần Giá trị trạng thái thực thi mã thông báo.

4. Không bắt buộc: Nếu trạng thái là .tokenSuccessfullyApplied, hãy kiểm tra thuộc tính resolvedParameters của cùng thông tin thực thi để xem tuyến đường sử dụng lựa chọn định tuyến nào, chẳng hạn như liệu tuyến đường đó có tránh các trạm thu phí hay không. Để biết thêm thông tin, hãy xem phần Các lựa chọn định tuyến đã giải quyết.

Giá trị trạng thái thực thi mã thông báo

Nếu routeStatus là .OK, bạn có thể bắt đầu hướng dẫn bằng bất kỳ trạng thái thực thi mã thông báo nào. Trạng thái này cho bạn biết liệu tuyến đường có đi theo tuyến đường bạn đã lên kế hoạch hay không.

Trạng thái	Đi theo tuyến đường bạn đã lên kế hoạch	Mô tả
.tokenSuccessfullyApplied	Có	Navigation SDK đã áp dụng mã thông báo tuyến đường của bạn.
.tokenAppliedWithLocationMismatch	Không nhất thiết	SDK Điều hướng không thể tạo lại tuyến đường bạn đã lên kế hoạch và thiết bị cách điểm xuất phát trong mã thông báo tuyến đường của bạn hơn 25 mét. Tuyến đường vẫn sử dụng các điểm đến và lựa chọn định tuyến từ mã thông báo tuyến đường của bạn.
.tokenIgnoredOther	Không nhất thiết	SDK Điều hướng không thể tạo lại tuyến đường bạn đã lên kế hoạch vì một lý do khác, chẳng hạn như do một con đường trên tuyến đường bạn đã lên kế hoạch bị đóng. Tuyến đường vẫn sử dụng các điểm đến và lựa chọn định tuyến từ mã thông báo tuyến đường của bạn.
.noTokenProvided	Không áp dụng	Yêu cầu về tuyến đường không bao gồm mã thông báo tuyến đường.
.unknown	Không xác định	Trạng thái không xác định.

Nếu tuyến đường không nhất thiết phải tuân theo tuyến đường bạn đã lên kế hoạch và tuyến đường chính xác là quan trọng (ví dụ: vì bạn đã sử dụng tuyến đường đó để tính giá), hãy ghi lại trạng thái hoặc yêu cầu mã thông báo tuyến đường mới từ vị trí hiện tại của xe.

Lựa chọn định tuyến đã giải quyết

resolvedParameters là một đối tượng tuân thủ giao thức GMSNavigationRouteTokenResolvedParameters hoặc nil nếu không có các lựa chọn định tuyến. Nó có các thuộc tính sau:

• travelMode: Phương thức di chuyển mà tuyến đường sử dụng, chẳng hạn như .driving (GMSNavigationTravelModeDriving). SDK điều hướng cũng báo cáo .driving khi tuyến đường sử dụng một phương thức di chuyển không có giá trị phù hợp hoặc khi không có phương thức di chuyển.
• avoidTolls: Liệu tuyến đường có tránh trạm thu phí hay không.
• avoidHighways: Liệu tuyến đường có tránh đường cao tốc hay không.
• avoidFerries: Liệu tuyến đường có tránh phà hay không.
• avoidTunnels: Cho biết tuyến đường có được tính toán để tránh đường hầm khi có thể hay không.
• avoidVignettes: Các quốc gia mà tuyến đường được tính toán để tránh nhãn dán thu phí cầu đường khi có thể, dưới dạng mã vùng gồm hai chữ cái CLDR Unicode, chẳng hạn như CH cho Thuỵ Sĩ.
• rerouteStrategy: Chiến lược mà phần phụ trợ định tuyến sử dụng để tính toán các tuyến đường mới trong chuyến đi. Các chiến lược bao gồm .bestBasedOnTokenParameters (GMSNavigationRerouteStrategyBestBasedOnTokenParameters), sử dụng tham số định tuyến trong mã thông báo tuyến đường để tính toán tuyến đường mới.

Nếu trạng thái thực thi mã thông báo không phải là .tokenSuccessfullyApplied, thì SDK điều hướng chỉ báo cáo travelMode, avoidTolls, avoidHighways và avoidFerries. Các thuộc tính khác có giá trị mặc định, ngay cả khi bạn yêu cầu tránh đường hầm hoặc nhãn dán thu phí khi yêu cầu mã thông báo tuyến đường: avoidTunnels là false (NO), avoidVignettes trống và rerouteStrategy là .unknown (GMSNavigationRerouteStrategyUnknown).

Ví dụ

Ví dụ về mã sau đây minh hoạ cách lập kế hoạch cho một tuyến đường bằng mã thông báo tuyến đường, kiểm tra xem SDK điều hướng có áp dụng mã thông báo đó hay không và bắt đầu hướng dẫn.

Swift

let routeToken = "route token returned by Routes API"

mapView.navigator?.setDestinationsWithToken(routeToken) { [weak self] routeDescription, error in
  // Check whether the Navigation SDK found a route.
  guard routeDescription?.routeStatus == .OK else {
    print("Route error: \(error?.localizedDescription ?? "unknown")")
    return
  }

  // Check whether the Navigation SDK applied the route token.
  if let executionDetails = routeDescription?.routeTokenExecutionDetails {
    if executionDetails.tokenExecutionStatus != .tokenSuccessfullyApplied {
      print("The route might differ from your planned route.")
    }
  } else {
    print("Route token details aren't available.")
  }

  self?.mapView.navigator?.isGuidanceActive = true
}

Objective-C

NSString *routeToken = @"route token returned by Routes API";

[mapView.navigator setDestinationsWithToken:routeToken
                          completionHandler:^(id<GMSNavigationRouteDescription> _Nullable routeDescription,
                                              NSError *_Nullable error) {
  // Check whether the Navigation SDK found a route.
  if (routeDescription.routeStatus != GMSRouteStatusOK) {
    NSLog(@"Route error: %@", error.localizedDescription);
    return;
  }

  // Check whether the Navigation SDK applied the route token.
  id<GMSNavigationRouteTokenExecutionDetails> executionDetails =
      routeDescription.routeTokenExecutionDetails;
  if (executionDetails == nil) {
    NSLog(@"Route token details aren't available.");
  } else if (executionDetails.tokenExecutionStatus !=
             GMSNavigationRouteTokenExecutionStatusTokenSuccessfullyApplied) {
    NSLog(@"The route might differ from your planned route.");
  }

  mapView.navigator.guidanceActive = YES;
}];

Trường hợp có nhiều điểm dừng

Bạn có thể thiết lập tối đa 25 điểm tham chiếu.

SDK Điều hướng không tự động chuyển đến điểm đến tiếp theo. Khi xe đến một điểm tham chiếu, hãy gọi continueToNextDestinationWithCompletion: để bắt đầu chặng tiếp theo của chuyến đi. Điều này cũng áp dụng cho mã thông báo tuyến đường có điểm tham chiếu trung gian. Khi bạn chuyển đến điểm đến tiếp theo, SDK Điều hướng sẽ tiếp tục đi theo tuyến đường từ mã thông báo tuyến đường của bạn thay vì lập kế hoạch cho một tuyến đường mới.

Chú ý: Đôi khi, việc gọi phương thức continueToNextDestinationWithCompletion: có thể dẫn đến sự kiện đến không chính xác, trong đó điểm đến vừa hoàn tất có vẻ như được chọn lại.

Cách mã thông báo tuyến đường và SDK điều hướng tương tác

Sau đây là cách Navigation SDK xử lý tuyến đường bạn đã lên kế hoạch:

• Ghi đè mọi đích đến đã đặt trước đó.

• Sử dụng vị trí xuất phát của xe.

• Điều chỉnh theo tình trạng đường sá và giao thông. Xem phần Lý do tuyến đường đã lên kế hoạch có thể không được tuân thủ chính xác.

• Sử dụng các lựa chọn định tuyến được đặt trong mã thông báo tuyến đường thay vì các chế độ cài đặt sau trong ứng dụng, kể cả khi ứng dụng tính toán một tuyến đường mới trong chuyến đi:

  • avoidsHighways
  • avoidsTolls
  • avoidsFerries
  • licensePlateRestriction
  • Phương thức di chuyển được đặt trong ứng dụng của bạn

• Tuân theo các chế độ cài đặt này khi tính toán hoặc điều chỉnh tuyến đường:

  • Mục tiêu của tuyến đường từ mã thông báo tuyến đường, chẳng hạn như tuyến đường thân thiện với môi trường hoặc tuyến đường ngắn nhất. Nếu phải điều chỉnh tuyến đường, SDK Điều hướng sẽ sử dụng các mục tiêu tuyến đường mà bạn đã chỉ định khi yêu cầu mã thông báo tuyến đường.
  • Các lựa chọn liên quan đến điểm tham chiếu từ mã thông báo tuyến đường của bạn, chẳng hạn như lựa chọn ưu tiên về bên đường.

Lưu ý: Với setDestinationsWithToken:completionHandler:, bạn không truyền điểm tham chiếu, vì vậy, SDK Điều hướng sẽ sử dụng các điểm đến và lựa chọn điểm tham chiếu từ mã thông báo tuyến đường của bạn. Để đặt các lựa chọn cho điểm tham chiếu, chẳng hạn như lựa chọn ưu tiên về bên đường hoặc điểm dừng của xe, hãy sử dụng các trường sideOfRoad và vehicleStopover trên các điểm tham chiếu trong yêu cầu Routes API. Điểm xuất phát luôn là vị trí của thiết bị, vì vậy, các lựa chọn mà bạn đặt cho điểm xuất phát trong yêu cầu API Routes sẽ không áp dụng.