Di chuyển cho mô-đun SDK của người tiêu dùng iOS

Consumer SDK dành cho iOS cho phép bạn tạo ứng dụng Chia sẻ chuyến đi bằng cách sử dụng cấu trúc mô-đun. Bạn có thể sử dụng các phần của API mà bạn muốn sử dụng cho ứng dụng cụ thể và tích hợp các phần đó với API của riêng bạn. API SDK người dùng cho các tính năng khác nhau được đóng gói thành các mô-đun riêng biệt.

Nếu ứng dụng Chia sẻ chuyến đi của bạn sử dụng các phiên bản SDK người dùng cũ hơn, bạn sẽ cần nâng cấp ứng dụng để dùng cấu trúc mô-đun này. Hướng dẫn di chuyển này mô tả cách nâng cấp ứng dụng của bạn.

Tổng quan

Cấu trúc mô-đun SDK người dùng giới thiệu một đối tượng MapViewSession chứa trạng thái giao diện người dùng. Trong các phiên bản trước của SDK người dùng, các ứng dụng lưu chuyển giữa các trạng thái. Với cấu trúc mô-đun này, bạn sẽ tạo một đối tượng MapViewSession và có thể hiển thị phiên trên bản đồ. Nếu không có phiên nào hiển thị, thì bản đồ sẽ hiển thị cùng một nội dung như khi chỉ sử dụng SDK Maps cho iOS.

Đối tượng MapViewSession đại diện cho một thực thể sử dụng trong vòng đời của một mô-đun. Phiên hoạt động là điểm truy cập vào các API mô-đun. Ví dụ: một phiên Chia sẻ hành trình tuân theo một chuyến đi. Bạn sẽ tương tác với đối tượng JourneySharingSession để theo dõi chuyến đi.

`TripModel` đối tượng

Trong các phiên bản trước của SDK người tiêu dùng, thực thể TripService cho phép bạn chỉ theo dõi một chuyến đi trực tiếp tại mỗi thời điểm. Bằng cách sử dụng đối tượng TripModel, bạn có thể theo dõi nhiều chuyến đi trực tiếp trong một thực thể TripService. Bạn có thể tạo một thực thể của TripModel từ TripService và mỗi thực thể của TripModel được liên kết với một chuyến đi cụ thể.

Thực thể TripModel gọi các sự kiện cập nhật nếu người đăng ký đã đăng ký đang trong chuyến đi khi được cập nhật.

Bạn cũng có thể dùng đối tượng TripModel để tạo một bản sao của đối tượng JourneySharingSession.

`MapViewSession` tiểu bang

Mỗi lần, bạn chỉ có thể thêm mỗi thực thể MapViewSession vào một mapView và có thể ở một trong hai trạng thái sau:

Trạng thái GMTCMapViewSessionStateInactive cho biết rằng MapViewSession này chưa được thêm vào bất kỳ mapView nào hoặc đã bị xoá khỏi mapView. Khi thực thể MapViewSession đã bị xoá khỏi mapView, phương thức didRemoveFromMapView sẽ được gọi.

Việc gọi phương thức hideMapViewSession hoặc hideAllMapViewSessions sẽ xoá mapViewSession khỏi mapView:
```
[_mapView hideMapViewSession:mapViewSessionA];
```
hoặc
```
[_mapView hideAllMapViewSessions];
```
Trạng thái GMTCMapViewSessionStateActive cho biết MapViewSession này đã được thêm vào mapView. Khi một thực thể của MapViewSession đã được thêm vào mapView, phương thức didAddToMapView sẽ được gọi. Việc gọi phương thức showMapViewSession sẽ thêm mapViewSession vào mapView đích:
```
[_mapView showMapViewSession:mapViewSessionA];
```

Sử dụng các thành phần giao diện người dùng và chỉ dữ liệu

Bạn có thể tạo ứng dụng đi chung xe bằng các thành phần chỉ có dữ liệu hoặc các API thành phần giao diện người dùng do Giải pháp gọi xe và giao hàng theo yêu cầu cung cấp.

Sử dụng các thành phần chỉ dữ liệu

Cách tạo ứng dụng đi chung xe bằng thành phần chỉ dữ liệu:

Khởi động một đối tượng GMTCServices bằng cách chỉ định mã nhà cung cấp và nhà cung cấp mã thông báo truy cập.
Lấy thuộc tính tripService từ thực thể dùng chung của đối tượng GMTCServices.
Tạo hoặc truy xuất bản sao của đối tượng GMTCTripModel cho một chuyến đi cụ thể bằng phương thức tripModelForTripName của đối tượng tripService.
Đăng ký các lệnh gọi lại cho thực thể GMTCTripModel để bắt đầu giám sát chuyến đi.

Ví dụ sau đây cho thấy cách sử dụng các thành phần chỉ dữ liệu:

[GMTCServices setAccessTokenProvider:[[AccessTokenProvider alloc] init]
                          providerID:yourProviderID];
GMTCTripService *tripService = [GMTCServices sharedServices].tripService;

// Create a tripModel instance for listening to updates to the trip specified by this trip name.
GMTCTripModel *tripModel = [tripService tripModelForTripName:tripName];

// Register for the trip update events.
[tripModel registerSubscriber:self];

// To stop listening for the trip update.
[tripModel unregisterSubscriber:self];

Sử dụng các API thành phần trên giao diện người dùng

Làm theo quy trình này để tạo một ứng dụng cho người tiêu dùng bằng các API phần tử giao diện người dùng của Giải pháp gọi xe và giao hàng theo yêu cầu:

Khởi động một đối tượng GMTCServices bằng cách chỉ định mã nhà cung cấp và nhà cung cấp mã thông báo truy cập.
Khởi động một đối tượng GMTCMapView để kết xuất bản đồ cơ sở.
Lấy thuộc tính tripService từ thực thể dùng chung của đối tượng GMTCServices.
Tạo hoặc truy xuất bản sao của đối tượng GMTCTripModel cho một chuyến đi cụ thể bằng phương thức tripModelForTripName của đối tượng tripService.
Tạo một đối tượng GMTCJourneySharingSession bằng thực thể GMTCTripModel.
Hiển thị đối tượng GMTCJourneySharingSession trên mapView.
Đăng ký các lệnh gọi lại cho thực thể GMTCTripModel để bắt đầu giám sát chuyến đi.

Ví dụ sau đây cho thấy cách sử dụng các API giao diện người dùng:

[GMTCServices setAccessTokenProvider:[[AccessTokenProvider alloc] init]
                          providerID:yourProviderID];
GMTCTripService *tripService = [GMTCServices sharedServices].tripService;

// Create a tripModel instance for listening to updates to the trip specified by this trip name.
GMTCTripModel *tripModel = [tripService tripModelForTripName:tripName];
GMTCJourneySharingSession *journeySharingSession =
  [[GMTCJourneySharingSession alloc] initWithTripModel:tripModel];

// Add the journeySharingSession instance on the mapView for UI updating.
[self.mapView showMapViewSession:journeySharingSession];

// Register for the trip update events.
[tripModel registerSubscriber:self];

// To remove the JourneySharingSession from the mapView:
[self.mapView hideMapViewSession:journeySharingSession];

// To stop listening for the trip update.
[tripModel unregisterSubscriber:self];

Thay đổi mã cấu trúc mô-đun

Nếu ứng dụng Chia sẻ chuyến đi của bạn sử dụng các phiên bản SDK người dùng trước đây, thì cấu trúc mô-đun mới cập nhật sẽ yêu cầu bạn thay đổi một số mã. Phần này mô tả một số thay đổi đó.

Giám sát chuyến đi

Cấu trúc mô-đun mới cập nhật yêu cầu thay đổi mã cho cả người dùng lớp dữ liệu và người dùng giao diện người dùng.

Trong các phiên bản cũ, người dùng theo lớp dữ liệu có thể xử lý việc giám sát chuyến đi bằng mã sau:

GRCTripRequest *tripRequest =
    [[GRCTripRequest alloc] initWithRequestHeader:[GRSRequestHeader defaultHeader]
                                         tripName:tripName
                          autoRefreshTimeInterval:1];
GRCTripService *tripService = [GRCServices sharedServices].tripService;
[tripService registerServiceSubscriber:self];
[tripService setActiveTripWithRequest:tripRequest];

Khi sử dụng cấu trúc mô-đun, người dùng lớp dữ liệu sẽ dùng mã sau:

GMTCTripService *tripService = [GMTCServices sharedServices].tripService;
GMTCTripModel *tripModel = [tripService tripModelForTripName:tripName];
tripModel.options.autoRefreshTimeInterval = 1;
[tripModel registerSubscriber:self];

Trong các phiên bản cũ, người dùng giao diện người dùng có thể xử lý việc giám sát chuyến đi bằng mã sau:

// Show the Journey Sharing user interface.
[self.mapView startTripMonitoring];

// Hide the Journey Sharing user interface.
[self.mapView resetCustomerState];

Khi sử dụng cấu trúc mô-đun, người dùng giao diện người dùng sẽ sử dụng mã sau:

// Show the Journey Sharing user interface.
GMTCJourneySharingSession *journeySharingSession =
  [[GMTCJourneySharingSession alloc] initWithTripModel:tripModel];
[self.mapView showMapViewSession:journeySharingSession];

// Hide the Journey Sharing user interface.
[self.mapView hideMapViewSession:journeySharingSession];