Nguồn cấp dữ liệu đường đi từng chặng cung cấp thông tin chỉ dành cho chỉ đường cho các thiết bị không được thiết kế để hướng dẫn chỉ đường dựa trên bản đồ. Thành phần này cung cấp các thao tác sắp tới bằng các phần tử mà bạn cung cấp:

• biểu tượng (trái, phải, rẽ vòng ngược)
• số thứ tự rẽ trong vòng xoay
• tên đường
• khoảng cách và thời gian ước tính đến bước điều hướng tiếp theo hoặc đích đến cuối cùng

Bạn có thể sử dụng nguồn cấp dữ liệu từng chặng để tạo trải nghiệm khi giao diện người dùng SDK chỉ đường đầy đủ không phù hợp, chẳng hạn như đối với Android Auto hoặc màn hình nhỏ không có ngăn xếp Android đầy đủ. Ví dụ: bạn có thể sử dụng tính năng này cho người lái xe hai bánh, trong đó bạn có thể chiếu hướng dẫn chỉ đường để giúp họ đến đích nhanh hơn và tự tin hơn với ít sự phân tâm nhất.

Để sử dụng SDK, bạn sẽ tạo một dịch vụ và đăng ký dịch vụ đó với SDK điều hướng cho Android để dịch vụ có thể nhận thông tin điều hướng mới theo thời gian thực (khoảng một lần mỗi giây trong khi điều hướng).

Tài liệu này hướng dẫn bạn cách tạo và đăng ký dịch vụ điều hướng nhận thông tin điều hướng từ SDK và cung cấp trạng thái điều hướng cho thiết bị nhận.

Tổng quan

Phần này mô tả cách thêm thư viện TurnByTurn vào dự án của bạn và tóm tắt quy trình cấp cao để xây dựng chức năng theo từng chặng.

Thêm thư viện TurnByTurn vào dự án của bạn bằng Maven (nên dùng)

Để sử dụng phiên bản độc lập của thư viện TurnByTurn, hãy làm theo các bước sau:

1. Thiết lập môi trường để truy cập vào kho lưu trữ Maven của máy chủ lưu trữ:

   Maven

   Thêm đoạn mã sau vào tệp pom.xml của bạn:

       <project>
         ...
         <repositories>
           <repository>
             <id>google-maven-repository</id>
             <url>https://maven.google.com</url>
           </repository>
         </repositories>
         ...
       </project>
       
       

   Gradle

   Thêm đoạn mã sau vào tệp build.gradle của bạn:

   repositories {
       ...
       google()
   }
       

2. Thêm phần phụ thuộc sau vào cấu hình Maven hoặc Gradle:

   Maven

   <dependencies>
     ...
     <dependency>
       <groupId>com.google.android.maps</groupId>
       <artifactId>google_turnbyturn</artifactId>
       <version>1.0.0</version>
     </dependency>
   </dependencies>
       
       

   Gradle

   dependencies {
     ...
     implementation 'com.google.android.maps:google_turnbyturn:1.0.0'
   }
       

Thêm thư viện TurnByTurn vào dự án bằng tệp JAR đã tải xuống (phương án thay thế)

Thư việnTurnByTurn được cung cấp dưới dạng tệp JAR trong thư mục SDK này. Nếu bạn không có quyền truy cập, hãy liên hệ với người đại diện của bạn.

1. Tải và giải nén google_turnbyturn_*.jar.
2. Sao chép tệp JAR đã tải xuống vào thư mục app/libs của dự án.

3. Thêm nội dung sau vào build.gradle để đưa tệp JAR vào bản dựng.

   dependencies {
       ...
       api fileTree(include: ['*.jar'], dir: 'libs')
   }
   

Sử dụng Thư viện TurnByTurn

Sau đây là các bước cấp cao để bật chức năng chỉ đường từng chặng. Các phần tiếp theo sẽ cung cấp thông tin chi tiết về từng bước.

1. Tạo một dịch vụ để nhận thông tin cập nhật về đường đi.

2. Đăng ký dịch vụ.

3. Tìm hiểu về trạng thái điều hướng.

4. Xem ví dụ về màn hình điều hướng hiển thị các thành phần thiết yếu.

Tạo một dịch vụ để nhận thông tin cập nhật về chỉ đường

SDK Điều hướng liên kết với dịch vụ TurnByTurn và gửi thông tin cập nhật về điều hướng thông qua Android Messenger. Bạn có thể tạo một dịch vụ điều hướng mới cho các bản cập nhật này hoặc sử dụng một dịch vụ hiện có.

Lợi ích của việc sử dụng dịch vụ để nhận thông tin cập nhật về điều hướng là dịch vụ có thể hoạt động trong một quy trình nền riêng biệt.

Dịch vụ trong ví dụ sau nhận thông tin điều hướng và sử dụng TurnByTurnManager để chuyển đổi dữ liệu thành đối tượng NavInfo chứa thông tin chi tiết về điều hướng.

/**
 *   Receives turn-by-turn navigation information forwarded from NavSDK.
 */
public class NavInfoReceivingService extends Service {
  /** The messenger used by the service to receive nav step updates. */
  private Messenger incomingMessenger;
  private TurnByTurnManager turnByTurnManager;

  private final class IncomingNavStepHandler extends Handler {
    public IncomingNavStepHandler(Looper looper) {
      super(looper);
    }

    @Override
    public void handleMessage(Message msg) {
      // Identify the message through the msg.what field.
      if (TurnByTurnManager.MSG_NAV_INFO == msg.what) {
        // Extract the NavInfo object using the TurnByTurnManager.
        NavInfo navInfo = turnByTurnManager
          .readNavInfoFromBundle(msg.getData()));
      // Do something with the NavInfo
    }
  }
}

@Nullable
@Override
public IBinder onBind(Intent intent) {
  return incomingMessenger.getBinder();
}

@Override
public void onCreate() {
  turnByTurnManager = TurnByTurnManager.createInstance();
  HandlerThread thread =
    new HandlerThread("NavInfoReceivingService",
      Process.THREAD_PRIORITY_DEFAULT);
  thread.start();
  incomingMessenger = new Messenger(
    new IncomingNavStepHandler(thread.getLooper()));
}

Mã thông báo

Bạn có thể xác định thông báo NavInfo thông qua trường Message.what của lớp Message, được đặt thành giá trị TurnByTurnManager.MSG_NAV_INFO.

Đăng ký dịch vụ để nhận thông tin cập nhật về chỉ đường

Các đoạn mã sau đây sẽ đăng ký dịch vụ chỉ đường.

boolean isNavInfoReceivingServiceRegistered =
          navigator.registerServiceForNavUpdates(
              getPackageName(), NavInfoReceivingService.class.getName(), numNextStepsToPreview);

Bắt đầu và dừng dịch vụ

Dịch vụ điều hướng sẽ hoạt động miễn là SDK Điều hướng liên kết với dịch vụ đó. Bạn có thể gọi startService() và stopService() theo cách thủ công để kiểm soát vòng đời của dịch vụ chỉ đường, nhưng khi bạn đăng ký dịch vụ của mình bằng SDK Chỉ đường, dịch vụ sẽ tự động bắt đầu và chỉ dừng khi bạn huỷ đăng ký dịch vụ đó. Tuỳ thuộc vào cách thiết lập ứng dụng, bạn nên cân nhắc việc bắt đầu một dịch vụ trên nền trước, như mô tả trong phần Tổng quan về dịch vụ trong tài liệu Android.

Huỷ đăng ký dịch vụ

Để ngừng nhận thông tin cập nhật về chỉ đường, hãy huỷ đăng ký dịch vụ này khỏi SDK Chỉ đường.

navigator.unregisterServiceForNavUpdates();

Tìm hiểu về trạng thái điều hướng

Sử dụng NavInfo.getNavState() để biết trạng thái điều hướng hiện tại, trạng thái này là một trong những trạng thái sau:

• Đang hoạt động – Trạng thái ENROUTE có nghĩa là tính năng điều hướng có hướng dẫn hiện đang hoạt động và người dùng đang đi theo tuyến đường được cung cấp. Có thông tin về bước điều động sắp tới.

• Đổi tuyến đường – REROUTING có nghĩa là quá trình điều hướng đang diễn ra, nhưng trình điều hướng đang tìm một tuyến đường mới. Bước thao tác sắp tới không có sẵn vì chưa có tuyến đường mới. Trong ứng dụng mẫu, thông báo "Đang định tuyến lại..." sẽ xuất hiện trên màn hình thông tin chỉ đường. Sau khi tìm thấy một tuyến đường, thông báo NavInfo sẽ được gửi với trạng thái ENROUTE.

• Đã dừng – STOPPED có nghĩa là quá trình điều hướng đã kết thúc. Ví dụ: thao tác điều hướng sẽ dừng khi người dùng thoát khỏi thao tác điều hướng trong ứng dụng. Trong ứng dụng mẫu, trạng thái STOPPED sẽ xoá màn hình thông tin điều hướng để ngăn việc hiển thị hướng dẫn từng bước còn lại.

Điền sẵn màn hình của nguồn cấp dữ liệu

Sau khi thiết lập dịch vụ theo từng chặng, bạn đã hoàn thành phần này về các thành phần hình ảnh và văn bản mà bạn có thể dùng để điền các thẻ hướng dẫn cho nguồn cấp dữ liệu từng chặng.

Trường thông tin về thẻ điều hướng

Khi người dùng nhập tính năng chỉ đường, một thẻ điều hướng sẽ xuất hiện ở trên cùng, chứa dữ liệu điều hướng được điền từ SDK Điều hướng. Hình ảnh liên quan cho thấy ví dụ về các thành phần điều hướng thiết yếu này.

Bảng này cho thấy các trường chứa thông tin điều hướng và vị trí bạn có thể tìm thấy các trường đó.

Các trường cho từng bước điều hướng	Các trường cho thông tin tổng thể của chuyến đi
Tìm thấy trong StepInfo	Tìm thấy trong NavInfo
Tên đường đầy đủ	Thời gian còn lại
Biểu tượng thao tác	Khoảng cách đến đích đến
Khoảng cách đến bước tiếp theo
Trường hướng dẫn làn đường

Hướng dẫn làn đường

SDK điều hướng biểu thị các làn đường trong thẻ rẽ điều hướng dưới dạng các đối tượng dữ liệu Lane và LaneDirection. Đối tượng Lane đại diện cho một làn đường cụ thể trong quá trình điều hướng và có một danh sách các đối tượng LaneDirection mô tả tất cả các lượt rẽ có thể thực hiện từ làn đường này.

Hướng được đề xuất mà người dùng nên đi trong một làn đường được đánh dấu bằng trường isRecommended.

Ví dụ về tính năng hướng dẫn làn đường

Đoạn mã sau đây minh hoạ cách trình bày dữ liệu của các làn đường hiển thị ở trên.

// Lane 1
LaneDirections = [{/*laneShape=*/ STRAIGHT, /*isRecommended=*/ false},
                  {/*laneShape=*/ SLIGHT_LEFT, /*isRecommended=*/ true}]

// Lane 2
LaneDirections = [{/*laneShape=*/ STRAIGHT, /*isRecommended=*/ false}]

Tạo biểu tượng cho các thao tác

Enum Maneuver xác định từng thao tác có thể xảy ra trong khi điều hướng và bạn có thể lấy thao tác cho một bước nhất định từ phương thức StepInfo.getManeuver().

Bạn phải tạo biểu tượng thao tác và ghép nối các biểu tượng đó với thao tác liên quan. Đối với một số thao tác, bạn có thể thiết lập mối liên kết 1-1 với một biểu tượng, chẳng hạn như DESTINATION_LEFT và DESTINATION_RIGHT. Tuy nhiên, vì một số thao tác tương tự nhau, nên bạn có thể muốn liên kết nhiều thao tác với một biểu tượng. Ví dụ: TURN_LEFT và ON_RAMP_LEFT đều có thể liên kết với biểu tượng rẽ trái.

Một số thao tác lái xe có thêm nhãn clockwise hoặc counterclockwise mà SDK xác định dựa trên bên lái xe của một quốc gia. Ví dụ: ở những quốc gia mà người lái xe đi ở bên trái đường, người lái xe sẽ rẽ vòng tròn hoặc rẽ ngược chiều kim đồng hồ, trong khi ở những quốc gia mà người lái xe đi ở bên phải đường, người lái xe sẽ rẽ theo chiều kim đồng hồ. SDK Điều hướng phát hiện liệu một thao tác lái xe có xảy ra ở làn đường bên trái hay bên phải và xuất ra thao tác lái xe thích hợp. Do đó, biểu tượng thao tác có thể khác nhau đối với thao tác theo chiều kim đồng hồ so với thao tác ngược chiều kim đồng hồ.

Sử dụng biểu tượng được tạo

Để hỗ trợ các trường hợp sử dụng Android Auto, SDK Điều hướng hỗ trợ tạo biểu tượng hướng dẫn thao tác và làn đường. Các biểu tượng này phù hợp với hướng dẫn định kích thước hình ảnh của thư viện Ứng dụng Android Auto cho Ô tô đề xuất nhắm mục tiêu hộp giới hạn 500 x 74 dp. Hãy xem setsLaneImage và CarIcon trong tài liệu tham khảo Android để biết thông tin chi tiết.

Ví dụ về việc tạo biểu tượng

NavigationUpdatesOptions options =
  NavigationUpdatesOptions.builder()
             .setNumNextStepsToPreview(numNextStepsToPreview)
             .setGeneratedStepImagesType(GeneratedStepImagesType.BITMAP)
             .setDisplayMetrics(getResources().getDisplayMetrics())
             .build();
boolean isRegistered =
          navigator.registerServiceForNavUpdates(
              getPackageName(),
              NavInfoReceivingService.class.getName(),
              options);

Sau khi bạn bật tính năng tạo biểu tượng, đối tượng TurnbyTurn StepInfo sẽ điền các biểu tượng vào các trường maneuverBitmap và lanesBitmap.

Bước tiếp theo

• Đối với ứng dụng Android Auto:
  • Vẽ bản đồ và bật tính năng điều hướng.