Gtel Maps iOS SDK

What the SDK doesCác tính năng được SDK hỗ trợ

Recommended pathTrình tự tích hợp SDK

1. Add GtelMapSDK.xcframework to the app target and set it to Embed & Sign.Thêm GtelMapSDK.xcframework vào target ứng dụng và thiết lập Embed & Sign.
2. Configure the SDK before the first GtelMapView is created.Cấu hình SDK trước khi tạo GtelMapView đầu tiên.
3. Create GtelMapView, assign gtelMapDelegate, then send feature requests through apply(input:).Tạo GtelMapView, gắn gtelMapDelegate, rồi gửi yêu cầu bằng apply(input:).
4. Use GtelMapClient.shared for service calls that feed host-owned UI or background workflows.Dùng GtelMapClient.shared khi ứng dụng cần lấy dữ liệu cho giao diện riêng hoặc xử lý nền.

Binary package layoutCấu trúc binary package

GtelMapSDKVendor/
  GtelMapSDK.xcframework
  README.md
  manifest.json

Add GtelMapSDK.xcframeworkThêm GtelMapSDK.xcframework

1. Open the host app project or workspace in Xcode.Mở project hoặc workspace của ứng dụng trong Xcode.
2. Drag GtelMapSDKVendor/GtelMapSDK.xcframework into the project navigator.Kéo GtelMapSDKVendor/GtelMapSDK.xcframework vào project navigator.
3. In Xcode's add-file dialog, enable Copy items if needed and tick the host app target in Add to targets.Trong hộp thoại thêm file của Xcode, bật Copy items if needed và tích chọn app target ở mục Add to targets.
4. Open the app target General > Frameworks, Libraries, and Embedded Content and set GtelMapSDK.xcframework to Embed & Sign.Mở app target General > Frameworks, Libraries, and Embedded Content và đặt GtelMapSDK.xcframework là Embed & Sign.

Import SDKKhai báo module SDK

import UIKit
import GtelMapSDK

Runtime configuration valuesCác giá trị cấu hình runtime

Keep real values outside committed source. The public guide shows only where the host app supplies configuration.Không commit giá trị thật vào source. Guide chỉ chỉ ra nơi ứng dụng truyền cấu hình cho SDK.

Location permissionQuyền vị trí

Only declare the location usage description if the host app uses the user's location, focuses the camera on the current location, or uses navigation.Chỉ khai báo mô tả quyền vị trí nếu ứng dụng dùng vị trí người dùng, đưa camera tới vị trí hiện tại hoặc dùng dẫn đường.

<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs your location to display the map and provide directions.</string>

import UIKit
import GtelMapSDK

@main
final class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        GtelMapConfig.configure(GtelMapConfiguration(
            apiVersion: "1.1",
            weatherApiKey: "YOUR_WEATHER_API_KEY",
            ui: GtelMapUIConfiguration(
                titleColor: .black,
                titleSize: 13,
                subTitleColor: .gray,
                subTitleSize: 11,
                backgroundColor: .white
            ),
            size: GtelMapSizeConfiguration(
                closeButtonSize: 30,
                iconSize: 48,
                inset: 16
            )
        ))
        return true
    }
}

import SwiftUI
import GtelMapSDK

@main
struct YourApp: App {
    init() {
        GtelMapConfig.configure(GtelMapConfiguration(
            apiVersion: "1.1",
            weatherApiKey: "YOUR_WEATHER_API_KEY",
            ui: GtelMapUIConfiguration(
                titleColor: .black,
                titleSize: 13,
                subTitleColor: .gray,
                subTitleSize: 11,
                backgroundColor: .white
            ),
            size: GtelMapSizeConfiguration(
                closeButtonSize: 30,
                iconSize: 48,
                inset: 16
            )
        ))
    }

    var body: some Scene {
        WindowGroup {
            MapScreen()
        }
    }
}

GtelMapConfiguration referenceTham chiếu GtelMapConfiguration

GtelMapUIConfiguration referenceTham chiếu GtelMapUIConfiguration

GtelMapSizeConfiguration referenceTham chiếu GtelMapSizeConfiguration

Update configuration at runtimeCập nhật cấu hình khi đang chạy

Call apply(configuration:) on an existing GtelMapView instance to apply a new configuration without recreating the view.Gọi apply(configuration:) trên GtelMapView đang có để đổi cấu hình mà không cần tạo lại view.

mapView.apply(configuration: GtelMapConfiguration(baseURL: stagingURL))

Info.plist key & GtelMapConfig helpersKey Info.plist & hàm hỗ trợ GtelMapConfig

Only GTELMapAccessToken is read from Info.plist. All other values (apiVersion, weatherApiKey, baseURL, ui, size) are supplied via GtelMapConfig.configure in AppDelegate.Chỉ GTELMapAccessToken được đọc từ Info.plist. Các giá trị còn lại (apiVersion, weatherApiKey, baseURL, ui, size) được cung cấp qua GtelMapConfig.configure trong AppDelegate.

Use GtelMapConfig static helpers at app launch to guard against missing keys before creating the map view.Dùng các hàm static của GtelMapConfig khi mở app để phòng trường hợp thiếu key trước khi tạo bản đồ.

guard GtelMapConfig.hasAPIKey else {
    fatalError("GTELMapAccessToken missing in Info.plist")
}
GtelMapConfig.configure(GtelMapConfiguration(
    apiVersion: "1.1",
    weatherApiKey: "YOUR_WEATHER_API_KEY",
    ui: .default,
    size: .default
))

func focusPlace(_ coordinate: CLLocationCoordinate2D) {
    guard mapView.isValidCoordinate(coordinate) else {
        mapView.setCameraBoundsInVietNam()
        return
    }
    mapView.setCameraZoomToAt(coordinate: coordinate, edgePadding: .zero)
}

func fitCustomBounds(sw: CLLocationCoordinate2D, ne: CLLocationCoordinate2D) {
    mapView.setCameraDefaultMap(sw: sw, ne: ne)
}

func gtelMapView(_ mapView: GtelMapView, didChangeRegion bounds: MapVisibleBounds) {
    currentMapCenter = bounds.center
}

GtelMapCameraChangeReasonGtelMapCameraChangeReason

The regionWillChangeWith and regionDidChangeWith delegate callbacks receive a GtelMapCameraChangeReason OptionSet. Use it to distinguish user gestures from programmatic camera moves.Các callback regionWillChangeWith và regionDidChangeWith nhận GtelMapCameraChangeReason. Dùng giá trị này để biết camera đổi do người dùng thao tác hay do code gọi.

func gtelMapView(_ mapView: GtelMapView, regionDidChangeWith reason: GtelMapCameraChangeReason, animated: Bool) {
    if reason.contains(.gesturePan) || reason.contains(.gesturePinch) {
        dismissSearchPanel()
    }
}

func loadStyles() {
    // Option A: read the local catalog synchronously
    styleItems = GtelMapClient.shared.mapStyles

    // Option B: receive it via the delegate through GtelMapViewInput
    mapView.apply(input: .mapStyles)
}

func applyStyle(_ style: GtelMapStyleModel) {
    mapView.apply(input: .mapStyle(style))
}

func applyExternalStyle(_ source: GtelMapStyleSource) {
    mapView.apply(input: .mapStyleSource(source))
}

Built-in styles (GtelMapStyle)Style dựng sẵn (GtelMapStyle)

Switch a built-in style with mapView.apply(style:). Existing markers and routes re-attach once the new style has loaded.Đổi style dựng sẵn bằng mapView.apply(style:). Marker và tuyến đường hiện có sẽ tự gắn lại sau khi style mới tải xong.

// Create the map already set to a built-in style
let mapView = GtelMapView(style: .STREETS)

// Or switch style at any time
mapView.apply(style: .STREETS)

// Resolve a style from a raw id (nil for an unknown id)
if let style = GtelMapStyle.fromId("dark") {
    mapView.apply(style: style)
}

Custom style contentCustom style content

Use custom style content when the host app already has GeoJSON-like content, images, layer ids, or filters to control on the current style.Dùng custom style content khi ứng dụng đã có dữ liệu dạng GeoJSON, hình ảnh, layer id hoặc bộ lọc cần hiển thị trên style hiện tại.

Custom style typesCác type của custom style

GtelMapCustomLayerStyle controls visual appearance. Key fields: color, strokeColor, opacity, width (line), radius (circle), iconScale (symbol), showsTitle, allowsOverlap.GtelMapCustomLayerStyle điều khiển cách layer hiển thị. Các trường thường dùng gồm color, strokeColor, opacity, width, radius, iconScale, showsTitle và allowsOverlap.

Read-back helpersHàm đọc trạng thái

Use these to inspect the current custom style state without tracking it separately in the host app.Dùng các hàm này để kiểm tra custom style hiện tại mà ứng dụng không cần tự lưu thêm.

Custom feature tapTap vào custom feature

When the user taps a feature in a host-owned custom layer, the SDK fires didTapCustomFeature. The layerId parameter identifies which layer was tapped.Khi người dùng chạm vào feature trong custom layer của ứng dụng, SDK gọi didTapCustomFeature. Tham số layerId cho biết layer nào được chạm.

func gtelMapView(_ mapView: GtelMapView, didTapCustomFeature feature: GtelMapCustomFeature, layerId: String?) {
    guard let id = feature.id else { return }
    showDetail(for: id, layer: layerId)
}

Custom style errorsLỗi custom style

The delegate has two didFailCustomStyleContent overloads: one with ResponseMessage (network/general) and one with typed GtelMapCustomStyleContentError (validation). Common validation errors:Delegate có hai hàm didFailCustomStyleContent: một hàm trả ResponseMessage cho lỗi chung, một hàm trả GtelMapCustomStyleContentError cho lỗi dữ liệu đầu vào. Các lỗi thường gặp:

func showFocusedMarker(_ annotation: AnnotationModel) {
    mapView.apply(input: .marker(annotation, iconScale: 1.0, zoomLevel: 16))
}

func showMarkers(_ annotations: [AnnotationModel]) {
    mapView.apply(input: .annotations(annotations, layerId: "places", visibleLayerIds: ["places"], iconScale: 1.0))
}

func clearMarkers() {
    mapView.removeAllAnnotations()
    mapView.deselectAllCallout()
}

func gtelMapView(_ mapView: GtelMapView, didTouchAnnotation annotation: AnnotationModel) {
    selectedAnnotation = annotation
}

func gtelMapView(_ mapView: GtelMapView, markerImageFor annotation: AnnotationModel) -> UIImage? {
    markerIcon(for: annotation)
}

Custom annotation viewView annotation tùy chỉnh

Return a UIView from annotationViewFor to render a fully custom annotation instead of an icon image. The view is pinned to the annotation coordinate.Trả UIView từ annotationViewFor để hiển thị marker tùy chỉnh thay vì chỉ dùng icon. View sẽ được đặt tại tọa độ của marker.

func gtelMapView(_ mapView: GtelMapView, annotationViewFor annotation: AnnotationModel) -> UIView? {
    guard annotation.type == "highlight" else { return nil }
    let badge = PulsingBadgeView()
    badge.tintColor = .systemRed
    return badge
}

Callout lifecycleVòng đời hiển thị của khung bóng thoại thông tin (Callout View) (Callout Lifecycle)

Callout positioning helpersHàm căn chỉnh callout

When the host app places a custom overlay anchored to the callout (e.g. a bottom sheet pinned above it), use these helpers to keep it aligned after layout changes.Khi ứng dụng đặt một overlay gắn với callout, ví dụ bottom sheet nằm phía trên callout, dùng các hàm này để giữ đúng vị trí sau khi layout thay đổi.

func requestRoute(from origin: LocationDataRequest, to destination: LocationDataRequest, costing: TransportType) {
    mapView.apply(input: .navigationRoute(locations: [origin, destination], costing: costing))
}

func renderRoute(_ response: RouteResponseModel) {
    mapView.apply(input: .route(response))
}

func clearRoute() {
    mapView.apply(input: .clearRoute)
}

func gtelMapView(_ mapView: GtelMapView, didLoadNavigationRoute route: RouteResponseModel, selectedTrip: TripModel?) {
    routeSummary = selectedTrip
}

Alternative and candidate routesTuyến đường thay thế và các tuyến đề xuất (Alternative & Candidate Routes)

For A/B alternatives, request the candidate route data through the host flow, then render the public response set with .matrixCandidateRoutes. Use delegate route-selection callbacks to keep host UI in sync.Với nhiều tuyến thay thế, ứng dụng lấy dữ liệu tuyến trước, rồi hiển thị bằng .matrixCandidateRoutes. Dùng callback chọn tuyến để cập nhật giao diện.

func renderCandidateRoutes(_ routes: [RouteResponseModel?], colors: [UIColor], sources: [MatrixRouteSourceMarker], targets: [MatrixRouteTargetMarker]) {
    mapView.apply(input: .matrixCandidateRoutes(
        responses: routes,
        colors: colors,
        sourceMarkers: sources,
        targetMarkers: targets,
        optimalIndex: 0,
        optimalTargetIndex: 0
    ))
}

func gtelMapView(_ mapView: GtelMapView, didSelectNavigationRoute route: RouteResponseModel, selectedTrip: TripModel?) {
    selectedRoute = route
}

Direct route API helpersHàm lấy dữ liệu tuyến đường

Use these when the host app needs route data without rendering it on the map (e.g. to display a distance summary before the user confirms).Dùng khi ứng dụng cần dữ liệu tuyến đường nhưng chưa cần hiển thị lên bản đồ, ví dụ để xem trước khoảng cách trước khi người dùng xác nhận.

let req = EstimateTimeDataRequest(
    origin: LocationDataRequest(lat: 10.776, lng: 106.701, address: "Point A"),
    destination: LocationDataRequest(lat: 10.800, lng: 106.720, address: "Point B"),
    costing: .auto
)
GtelMapClient.shared.getRoutes(request: req) { response, message in
    guard message.onCheckSuccess(), let trip = response?.trip else { return }
    showSummary(distance: trip.summary?.length, time: trip.summary?.time)
}

GtelMapClient.shared.getDoorToDoorRoute(request: req) { response, message in
    guard message.onCheckSuccess() else { return }
    renderDoorToDoorResult(response)
}

func showBoundary(_ coordinates: [CLLocationCoordinate2D]) {
    guard coordinates.count >= 3 else { return }
    mapView.apply(input: .polygon(coordinates: coordinates))
}

func clearBoundary() {
    mapView.apply(input: .clearPolygon)
}

extension MapViewController: GtelMapViewDelegate {
    func gtelMapViewDidFinishLoadingStyle(_ mapView: GtelMapView) {
        // re-apply custom content after each style reload
        if let content = pendingCustomContent {
            mapView.apply(input: .customStyleContent(content: content))
        }
    }

    func gtelMapViewRegionIsChanging(_ mapView: GtelMapView) {
        // lightweight: update a loading indicator only
        mapView.scheduleOverlayPositionUpdate()
    }

    func gtelMapView(_ mapView: GtelMapView, didTapCoordinate coordinate: CLLocationCoordinate2D) {
        tappedCoordinate = coordinate
    }

    func gtelMapView(_ mapView: GtelMapView, didPinCoordinate coordinate: CLLocationCoordinate2D) {
        mapView.apply(input: .reversePoint(coordinate: coordinate, showMarker: true, zoom: 18, size: 1))
    }

    func gtelMapView(_ mapView: GtelMapView, regionWillChangeWith reason: GtelMapCameraChangeReason, animated: Bool) {
        if reason.contains(.gesturePan) { dismissSearchPanel() }
    }

    func gtelMapView(_ mapView: GtelMapView, regionDidChangeWith reason: GtelMapCameraChangeReason, animated: Bool) {}

    func gtelMapViewDidBeginGesturePan(_ mapView: GtelMapView) {}

    func gtelMapViewDidEndGesturePan(_ mapView: GtelMapView) {}
}

func handleLocation(_ coordinate: CLLocationCoordinate2D?) {
    guard let coordinate, mapView.isValidCoordinate(coordinate) else {
        mapView.setCameraBoundsInVietNam()
        return
    }

    mapView.setCameraToUserLocation(coordinate: coordinate, zoomLevel: mapView.currentZoomLevel)
    mapView.showUserCurrentLocation()
}

POI delegate flowLuồng delegate của POI

POI callout action helpersHelpers xử lý action của POI callout

When the host app renders a custom button inside the callout (e.g. "Navigate" or "Call"), call these helpers so the SDK coordinates the internal state properly.Khi ứng dụng hiển thị nút riêng trong callout, ví dụ "Dẫn đường" hoặc "Gọi", hãy gọi các hàm này để SDK cập nhật trạng thái đúng.

// User tapped the primary action button in the POI callout
func userDidTapCalloutPrimary() {
    mapView.handlePOICalloutTap()
}

// User tapped the direction button in the POI callout
func userDidTapCalloutDirection() {
    mapView.handlePOICalloutDirection()
}

PlaceDetailModelPlaceDetailModel

PlaceDetailModel returned in didLoadPOIDetail is the same model used by the .placeDetail input flow. Key fields:PlaceDetailModel nhận được trong didLoadPOIDetail là cùng model với input .placeDetail. Các trường chính:

func autocomplete(_ text: String, focus: CLLocationCoordinate2D) {
    mapView.apply(input: .autocomplete(text: text, focusLat: focus.latitude, focusLng: focus.longitude, size: 8))
}

func search(_ text: String, focus: CLLocationCoordinate2D) {
    mapView.apply(input: .forwardGeocoding(text: text, focusLat: focus.latitude, focusLng: focus.longitude, size: 10))
}

func reverse(_ coordinate: CLLocationCoordinate2D) {
    mapView.apply(input: .reversePoint(coordinate: coordinate, showMarker: true, zoom: 18, size: 1))
}

func nearby(category: CatetoryPlaceType, center: CLLocationCoordinate2D) {
    mapView.apply(input: .nearbySearch(category: category, location: center, radius: 1000, size: 20))
}

func openPlaceDetail(_ placeId: String) {
    mapView.apply(input: .placeDetail(placeId))
}

Direct reverse geocoding helperHàm lấy địa chỉ trực tiếp

Use GtelMapClient.shared.reversePoint when the host app needs the address directly (e.g. for a form field) without rendering a marker or going through the map delegate.Dùng GtelMapClient.shared.reversePoint khi ứng dụng cần địa chỉ trực tiếp, ví dụ điền vào form, mà không cần hiển thị marker hoặc đi qua delegate của bản đồ.

GtelMapClient.shared.reversePoint(
    pointLat: coordinate.latitude,
    pointLon: coordinate.longitude,
    zoom: 18,
    size: 1,
    region: nil,
    localadmin: nil
) { geocoding, message in
    guard message.onCheckSuccess(), let address = geocoding?.subtitle else { return }
    destinationField.text = address
}

Host app flowLuồng xử lý phía ứng dụng

1. Keep the latest map center from didChangeRegion and use it as the search focus.Lưu tâm bản đồ mới nhất từ didChangeRegion để ưu tiên kết quả quanh khu vực đang xem.
2. Debounce user text before sending .autocomplete or .forwardGeocoding.Chờ người dùng dừng nhập rồi mới gửi .autocomplete hoặc .forwardGeocoding.
3. Render the result list in host UI, then select a result with .searchResult or load details with .placeDetail.Hiển thị danh sách kết quả trong giao diện của ứng dụng, rồi chọn kết quả bằng .searchResult hoặc lấy chi tiết bằng .placeDetail.
4. Use .clearSearch when the query is empty or the search screen closes.Dùng .clearSearch khi ô tìm kiếm rỗng hoặc màn hình tìm kiếm đóng.

func loadAvailableModes(_ locations: [LocationDataRequest]) {
    mapView.apply(input: .navigationAvailableModes(locations))
}

func loadRoute(_ locations: [LocationDataRequest], costing: TransportType) {
    mapView.apply(input: .navigationRoute(locations: locations, costing: costing, language: "vi", rendersRoute: true))
}

func showMultiStopRoute(_ route: RouteResponseModel, stops: [MultiStopPointItem]) {
    mapView.apply(input: .multiStopRoute(response: route, stops: stops))
}

func gtelMapView(_ mapView: GtelMapView, didLoadNavigationModes items: [TransportItemModel], selected: TransportType?, locations: [LocationDataRequest]) {
    transportModes = items
}

func gtelMapView(_ mapView: GtelMapView, didFailNavigation message: ResponseMessage) {
    showError(message)
}

Navigation flowLuồng dẫn đường

Additional navigation callbacksCallback navigation bổ sung

InitializerKhởi tạo

let navVC = GtelRouteNavigationViewController(
    stops: [originCoordinate, destinationCoordinate],
    profile: .car,          // GtelRouteNavigationProfile
    language: "vi",         // instruction language
    mode: .live             // .live (real GPS) or .demo (simulated)
)
present(navVC, animated: true)

Navigation runtime boundaryPhạm vi thực thi module dẫn đường (Navigation Runtime Scope)

Host apps should treat GtelRouteNavigationViewController as the navigation boundary. Provide stops, profile, language, and mode when initializing the controller; the SDK loads the route and manages the turn-by-turn runtime internally.Ứng dụng chỉ cần làm việc với GtelRouteNavigationViewController khi dùng dẫn đường. Truyền stops, profile, language và mode khi khởi tạo; SDK tự tải tuyến và quản lý dẫn đường từng ngã rẽ (Turn-by-turn).

func loadStaticPreview(center: CLLocationCoordinate2D) {
    let request = StaticMapRequest(
        center: center,
        zoom: 14,
        size: StaticMapSize(width: 640, height: 360)
    )

    GtelMapClient.shared.getStaticMap(request: request) { image, message in
        guard message.onCheckSuccess(), let image else { return }
        previewImageView.image = image
    }
}

func checkFence(pointId: String, coordinate: CLLocationCoordinate2D, geometry: PolygonGeometryModel) {
    mapView.apply(input: .geofencingPolygon(pointId: pointId, coordinate: coordinate, geometry: geometry))
}

Service referenceTham khảo service public

// The style catalog is served locally by the SDK — no network call needed
let mapStyles = GtelMapClient.shared.mapStyles

let picker = GtelMapStylePickerViewController(items: mapStyles, selectedStyle: currentStyle)
picker.onSelect = { [weak self, weak picker] style in
    picker?.dismiss(animated: true)
    self?.mapView.apply(input: .mapStyle(style))
}
present(picker, animated: true)

let categoryView = GtelNearbyCategoryView()
categoryView.onSelect = { [weak self] category in
    self?.mapView.apply(input: .nearbySearch(category: category, location: center))
}

SetupCấu hình

import GtelMapSDK

GtelMapConfig.configure(GtelMapConfiguration(
    apiVersion: "1.1",
    weatherApiKey: "YOUR_WEATHER_API_KEY"
))

GtelMapClient.shared.reversePoint(
    pointLat: 21.0278,
    pointLon: 105.8342
) { place, message in
    guard message.onCheckSuccess(), let place else { return }

    showAddress(place)
}

Choose the right entry pointChọn đúng entry point

Available service methodsCác service method hiện có

Examples for every methodVí dụ cho từng hàm

The snippets below use the callback overloads so UIKit host screens can receive results without creating Task blocks. The callback returns the response model plus ResponseMessage.Các ví dụ bên dưới dùng callback để màn UIKit nhận kết quả mà không cần tạo Task. Callback trả model kết quả kèm ResponseMessage.

let center = CLLocationCoordinate2D(latitude: 21.0278, longitude: 105.8342)
let destination = CLLocationCoordinate2D(latitude: 21.0368, longitude: 105.8342)

GtelMapClient.shared.reversePoint(
    pointLat: center.latitude,
    pointLon: center.longitude
) { reverse, reverseMessage in
    guard reverseMessage.onCheckSuccess(), let reverse else { return }
    updateAddress(reverse)
}

GtelMapClient.shared.autocomplete(
    text: "Ho Guom",
    focusLat: center.latitude,
    focusLng: center.longitude,
    size: 10
) { suggestions, autocompleteMessage in
    guard autocompleteMessage.onCheckSuccess() else { return }
    updateSuggestions(suggestions?.features ?? [])
}

GtelMapClient.shared.forwardGeocoding(
    text: "Ho Guom",
    focusLat: center.latitude,
    focusLng: center.longitude,
    size: 10
) { searchResult, searchMessage in
    guard searchMessage.onCheckSuccess() else { return }
    updateSearchResult(searchResult)
}

if let placeId = selectedPlaceId {
    GtelMapClient.shared.getLocationDetail(id: placeId) { detail, detailMessage in
        guard detailMessage.onCheckSuccess(), let detail else { return }
        showPlaceDetail(detail)
    }
}

GtelMapClient.shared.nearbySearch(
    location: center,
    types: "restaurant",
    radius: 1000,
    size: 20
) { nearby, nearbyMessage in
    guard nearbyMessage.onCheckSuccess(), let nearby else { return }
    updateNearbyPlaces(nearby)
}

let origin = CLLocationCoordinate2D(latitude: 21.0278, longitude: 105.8342)
let destination = CLLocationCoordinate2D(latitude: 21.0368, longitude: 105.8342)

let matrixRequest = MatrixRouteRequest(
    sources: [origin],
    targets: [destination],
    mode: .driving
)
GtelMapClient.shared.getMatrixRoute(request: matrixRequest) { matrix, matrixMessage in
    guard matrixMessage.onCheckSuccess(), let matrix else { return }
    updateMatrixSummary(matrix)
}

let routeRequest = EstimateTimeDataRequest(
    criteria: CriteriaDataRequest(locations: [
        LocationDataRequest(coordinate: origin),
        LocationDataRequest(coordinate: destination)
    ]),
    costing: "auto"
)
GtelMapClient.shared.getRoutes(request: routeRequest) { route, routeMessage in
    guard routeMessage.onCheckSuccess(), let route else { return }
    updateRouteSummary(route)
}

let doorToDoorRequest = EstimateTimeDataRequest(
    criteria: CriteriaDataRequest(locations: [
        LocationDataRequest(coordinate: origin),
        LocationDataRequest(coordinate: destination)
    ]),
    costing: "auto",
    doorToDoor: true
)
GtelMapClient.shared.getDoorToDoorRoute(
    request: doorToDoorRequest
) { doorToDoorRoute, doorToDoorMessage in
    guard doorToDoorMessage.onCheckSuccess(), let doorToDoorRoute else { return }
    updateDoorToDoorSummary(doorToDoorRoute)
}

let center = CLLocationCoordinate2D(latitude: 21.0278, longitude: 105.8342)

GtelMapClient.shared.getProvincePolygon(code: "01") { province, provinceMessage in
    guard provinceMessage.onCheckSuccess(), let province else { return }
    updateProvinceBoundary(province)
}

GtelMapClient.shared.getWardPolygon(code: "00001") { ward, wardMessage in
    guard wardMessage.onCheckSuccess(), let ward else { return }
    updateWardBoundary(ward)
}

let polygon = PolygonGeometryModel(
    type: "Polygon",
    coordinates: [[[
        [105.80, 21.00],
        [105.88, 21.00],
        [105.88, 21.06],
        [105.80, 21.06],
        [105.80, 21.00]
    ]]]
)
GtelMapClient.shared.checkPointInsidePolygon(
    pointId: "hanoi-center",
    coordinate: center,
    geometry: polygon
) { isInside, geofenceMessage in
    guard geofenceMessage.onCheckSuccess(), let isInside else { return }
    updateGeofenceStatus(isInside)
}

let center = CLLocationCoordinate2D(latitude: 21.0278, longitude: 105.8342)
let destination = CLLocationCoordinate2D(latitude: 21.0368, longitude: 105.8342)

GtelMapClient.shared.getWeather(
    lat: center.latitude,
    lon: center.longitude
) { weather, weatherMessage in
    guard weatherMessage.onCheckSuccess(), let weather else { return }
    showWeather(weather)
}

let snapRequest = SnapToRoadsRequest(
    coordinates: [center, destination],
    interpolate: true
)
GtelMapClient.shared.snapToRoads(request: snapRequest) { snappedRoad, snapMessage in
    guard snapMessage.onCheckSuccess(), let snappedRoad else { return }
    updateSnappedRoad(snappedRoad)
}

let isochroneRequest = IsochroneRequest(
    coordinate: center,
    metric: .time,
    contours: [5, 10, 15],
    mode: .driving,
    colors: ["2E86DE", "10AC84", "FF9F43"]
)
GtelMapClient.shared.isochrone(request: isochroneRequest) { isochrone, isochroneMessage in
    guard isochroneMessage.onCheckSuccess(), let isochrone else { return }
    updateIsochrone(isochrone)
}

let staticMapRequest = StaticMapRequest(
    center: center,
    zoom: 14,
    size: StaticMapSize(width: 640, height: 360),
    markers: [StaticMapMarker(coordinate: center)],
    path: StaticMapPath(coordinates: [center, destination])
)
GtelMapClient.shared.getStaticMap(request: staticMapRequest) { previewImage, imageMessage in
    guard imageMessage.onCheckSuccess(), let previewImage else { return }
    showPreview(previewImage)
}

GtelMapClient.shared.getStaticMapData(request: staticMapRequest) { previewData, dataMessage in
    guard dataMessage.onCheckSuccess(), let previewData else { return }
    cachePreviewData(previewData)
}

// Built-in style catalog is local — read it synchronously, no callback needed
let styles = GtelMapClient.shared.mapStyles
updateStyleSwitcher(styles)

Callback result styleNhận kết quả bằng callback

For host apps, prefer the callback overloads. They do not require Task at the call site and return both the model and ResponseMessage; the service facade does not throw.Với ứng dụng UIKit, nên dùng dạng callback. Cách này không cần tạo Task tại nơi gọi và trả về cả model lẫn ResponseMessage; service facade không ném lỗi (throw).

GtelMapClient.shared.autocomplete(
    text: "Ha Noi",
    focusLat: 21.0278,
    focusLng: 105.8342,
    size: 10
) { model, message in
    guard message.onCheckSuccess() else {
        showError(message)
        return
    }

    results = model?.features ?? []
}

Fetch first, render laterLấy dữ liệu trước, hiển thị sau

A host screen can calculate data with GtelMapClient, then pass the result into GtelMapView.apply(input:) only when the user opens a map.Một màn hình có thể lấy dữ liệu bằng GtelMapClient trước. Khi người dùng mở bản đồ, truyền kết quả vào GtelMapView.apply(input:).

GtelMapClient.shared.getRoutes(request: request) { route, message in
    guard message.onCheckSuccess(), let route else { return }

    // Later, on the map screen:
    mapView.apply(input: .route(route))
}

GtelPlaceSearchViewControllerGtelPlaceSearchViewController

GtelPlaceSearchViewController is the UIKit v1 search UI. It debounces text input, loads suggestions through GtelMapClient.shared.autocomplete, and reports selection through GtelPlaceSearchDelegate.GtelPlaceSearchViewController là màn hình tìm kiếm UIKit v1. Controller tự chờ người dùng dừng nhập, lấy gợi ý qua GtelMapClient.shared.autocomplete và trả lựa chọn qua GtelPlaceSearchDelegate.

extension MapViewController: GtelPlaceSearchDelegate {
    func showSearch() {
        let searchVC = GtelPlaceSearchViewController()
        searchVC.delegate = self
        searchVC.focusCoordinate = currentMapCenter
        searchVC.searchSize = 10
        present(searchVC, animated: true)
    }

    func placeSearch(_ controller: GtelPlaceSearchViewController, didSelect item: SearchResultItemDataSource) {
        controller.dismiss(animated: true)
        mapView.apply(input: .searchResult(item))
    }

    func placeSearchDidCancel(_ controller: GtelPlaceSearchViewController) {
        controller.dismiss(animated: true)
    }
}

Current limitsGiới hạn hiện tại

func gtelMapView(_ mapView: GtelMapView, didLoadSearchResults items: [SearchResultItemDataSource]) {
    results = items
}

func gtelMapView(_ mapView: GtelMapView, didFailSearch message: ResponseMessage) {
    showError(message)
}

func gtelMapViewDidFinishLoading(_ mapView: GtelMapView) {
    isMapReady = true
}

Error callback groupsNhóm callback lỗi

GtelMapViewInput

GtelMapView helpers

GtelMapViewDelegateGtelMapViewDelegate

Integration stepsCác bước tích hợp

1. Configure the SDK once during app launch.Cấu hình SDK một lần khi app khởi động.
2. Create GtelMapView in the screen.Tạo GtelMapView trong màn hình.
3. Assign gtelMapDelegate before sending any input.Gắn gtelMapDelegate trước khi gửi input.
4. Wait for map loading callback before moving to the default viewport.Chờ callback báo bản đồ đã tải xong rồi mới đưa camera về vùng mặc định.

final class FirstMapViewController: UIViewController, GtelMapViewDelegate {
    private let mapView = GtelMapView()

    override func viewDidLoad() {
        super.viewDidLoad()
        mapView.gtelMapDelegate = self
        view.addSubview(mapView)
        mapView.frame = view.bounds
        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
    }

    func gtelMapViewDidFinishLoading(_ mapView: GtelMapView) {
        mapView.setCameraBoundsInVietNam()
    }
}

Next stepsBước tiếp theo

func prepareStylePicker() {
    mapView.apply(input: .mapStyles)
}

func gtelMapView(_ mapView: GtelMapView, didLoadMapStyles items: [GtelMapStyleModel]) {
    styleItems = items
}

func userDidSelectStyle(_ style: GtelMapStyleModel) {
    mapView.apply(input: .mapStyle(style))
}

// 1. Register icon and add content block once
func setupVehicleLayer(vehicles: [Vehicle]) {
    mapView.apply(input: .customStyleImage(name: "host_ic_vehicle", image: UIImage(named: "ic_vehicle")!))

    let features = vehicles.map { v in
        GtelMapCustomFeature(
            id: v.id,
            geometry: .point(v.coordinate),
            title: v.name,
            properties: ["status": v.status]
        )
    }
    let source = GtelMapCustomSource(id: "host_vehicles_source", features: features)
    let layer = GtelMapCustomLayer(
        id: "host_vehicles_layer",
        sourceId: "host_vehicles_source",
        kind: .symbol,
        style: GtelMapCustomLayerStyle(iconScale: 1.2, showsTitle: true)
    )
    let content = GtelMapCustomStyleContent(
        id: "host_vehicles",
        sources: [source],
        layers: [layer]
    )
    mapView.apply(input: .customStyleContent(content: content))
}

// 2. Update a single vehicle position without re-adding everything
func updateVehicle(_ vehicle: Vehicle) {
    let updated = GtelMapCustomFeature(
        id: vehicle.id,
        geometry: .point(vehicle.coordinate),
        title: vehicle.name,
        properties: ["status": vehicle.status]
    )
    mapView.apply(input: .updateCustomStyleFeature(
        contentId: "host_vehicles",
        sourceId: "host_vehicles_source",
        feature: updated
    ))
}

// 3. Handle taps
func gtelMapView(_ mapView: GtelMapView, didTapCustomFeature feature: GtelMapCustomFeature, layerId: String?) {
    guard let vehicleId = feature.id else { return }
    showVehicleDetail(id: vehicleId)
}

// 4. Clean up when leaving the screen
func cleanup() {
    mapView.apply(input: .removeCustomStyleContentById(contentId: "host_vehicles"))
}

func renderPlaces(_ places: [AnnotationModel]) {
    mapView.apply(input: .annotations(places, layerId: "nearby_places", visibleLayerIds: ["nearby_places"], iconScale: 1.0))
    mapView.onSetVisiableBounds(annotations: places)
}

func gtelMapView(_ mapView: GtelMapView, didShowCallout annotation: AnnotationModel, isLoadingSubtitle: Bool) {
    showPlacePreview(annotation)
}

func searchTextDidChange(_ text: String, focus: CLLocationCoordinate2D) {
    searchDebouncer.run { [weak self] in
        guard !text.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
            self?.mapView.apply(input: .clearSearch)
            return
        }
        self?.mapView.apply(input: .autocomplete(text: text, focusLat: focus.latitude, focusLng: focus.longitude, size: 8))
    }
}

func gtelMapView(_ mapView: GtelMapView, didLoadAutocompleteResults items: [SearchResultItemDataSource]) {
    suggestions = items
}

Selecting a suggestionChọn một gợi ý

func userDidSelectSuggestion(_ item: SearchResultItemDataSource) {
    mapView.apply(input: .searchResult(item))
    if !item.placeId.isEmpty {
        mapView.apply(input: .placeDetail(item.placeId))
    }
}

func gtelMapView(_ mapView: GtelMapView, didPinCoordinate coordinate: CLLocationCoordinate2D) {
    mapView.apply(input: .reversePoint(coordinate: coordinate, showMarker: true, zoom: 18, size: 1))
}

func gtelMapView(_ mapView: GtelMapView, didLoadReversePoint place: GeocodingResponseModel?, coordinate: CLLocationCoordinate2D) {
    pinnedPlace = place
}

// No input needed — SDK handles POI tap automatically.
// The host app just implements delegate callbacks.

extension MapViewController: GtelMapViewDelegate {
    // Step 1: callout appears with title from map data
    func gtelMapView(_ mapView: GtelMapView, didShowCallout annotation: AnnotationModel, isLoadingSubtitle: Bool) {
        showCalloutView(title: annotation.title ?? "", isLoading: isLoadingSubtitle)
    }

    // Step 2: subtitle (address) resolves asynchronously
    func gtelMapView(_ mapView: GtelMapView, didUpdateCalloutSubtitle subtitle: String) {
        calloutView.subtitleLabel.text = subtitle
    }

    // Step 3: category resolves (update icon in callout)
    func gtelMapView(_ mapView: GtelMapView, didUpdateCalloutCategory type: String) {
        calloutView.categoryIcon.image = categoryIcon(for: type)
    }

    // Step 4: full detail available — populate bottom sheet
    func gtelMapView(_ mapView: GtelMapView, didLoadPOIDetail detail: PlaceDetailModel) {
        bottomSheet.populate(
            name: detail.name,
            address: detail.adrFormatAddress ?? detail.formattedAddress,
            phone: detail.internationalPhoneNumber,
            types: detail.types
        )
        bottomSheet.show()
    }

    // Step 5: user taps "Navigate" button in host UI
    @IBAction func navigateButtonTapped() {
        mapView.handlePOICalloutDirection()
    }

    // Step 6: callout dismissed
    func gtelMapViewDidRemoveCallout(_ mapView: GtelMapView) {
        bottomSheet.hide()
    }
}

func route(from origin: LocationDataRequest, to destination: LocationDataRequest) {
    mapView.apply(input: .navigationRoute(locations: [origin, destination], costing: .auto))
}

func gtelMapView(_ mapView: GtelMapView, didLoadNavigationRoute route: RouteResponseModel, selectedTrip: TripModel?) {
    routeInfo = selectedTrip
}

func clearRouteFlow() {
    mapView.apply(input: .clearRoute)
}

Common variantsBiến thể thường dùng

func prepareNavigation(_ locations: [LocationDataRequest]) {
    mapView.apply(input: .navigationAvailableModes(locations))
}

func gtelMapView(_ mapView: GtelMapView, didLoadNavigationModes items: [TransportItemModel], selected: TransportType?, locations: [LocationDataRequest]) {
    let costing = selected ?? .auto
    mapView.apply(input: .navigationRoute(locations: locations, costing: costing))
}

func startNavigation(from origin: CLLocationCoordinate2D, to destination: CLLocationCoordinate2D) {
    let navVC = GtelRouteNavigationViewController(
        stops: [origin, destination],
        profile: .car,
        language: "vi",
        mode: .live
    )
    navVC.modalPresentationStyle = .fullScreen
    present(navVC, animated: true)
}

// Demo mode — useful for testing in Simulator
func startDemoNavigation(from origin: CLLocationCoordinate2D, to destination: CLLocationCoordinate2D) {
    let navVC = GtelRouteNavigationViewController(
        stops: [origin, destination],
        profile: .car,
        language: "vi",
        mode: .demo
    )
    navVC.modalPresentationStyle = .fullScreen
    present(navVC, animated: true)
}

// Multi-stop
func startMultiStopNavigation(stops: [CLLocationCoordinate2D]) {
    let navVC = GtelRouteNavigationViewController(
        stops: stops,
        profile: .car,
        language: "vi",
        mode: .live
    )
    present(navVC, animated: true)
}

func loadDoorToDoorPreview(origin: LocationDataRequest, destination: LocationDataRequest) {
    let request = EstimateTimeDataRequest(
        origin: origin,
        destination: destination,
        costing: .auto
    )
    GtelMapClient.shared.getDoorToDoorRoute(request: request) { [weak self] response, message in
        guard let self, message.onCheckSuccess(), let trip = response?.trip else {
            self?.showError(message.getDes())
            return
        }
        self.showDoorToDoorSummary(
            totalDistance: trip.summary?.length,
            totalTime: trip.summary?.time,
            legs: trip.legs
        )
        if let response { self.mapView.apply(input: .route(response)) }
    }
}

func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) {
    guard let coordinate = locations.last?.coordinate, mapView.isValidCoordinate(coordinate) else {
        mapView.setCameraBoundsInVietNam()
        return
    }
    mapView.setCameraToUserLocation(coordinate: coordinate, zoomLevel: 16)
}

func checkGeofence(vehicleId: String, vehicleCoordinate: CLLocationCoordinate2D, zone: PolygonGeometryModel) {
    mapView.apply(input: .geofencingPolygon(
        pointId: vehicleId,
        coordinate: vehicleCoordinate,
        geometry: zone
    ))
}

func gtelMapView(_ mapView: GtelMapView, didLoadGeofencingResult pointId: String, isInside: Bool) {
    if isInside {
        showAlert("\(pointId) is inside the zone")
    } else {
        showAlert("\(pointId) has left the zone")
    }
}

func gtelMapView(_ mapView: GtelMapView, didFailGeofencing message: ResponseMessage) {
    showError(message.getDes())
}

func showIsochroneZones(from coordinate: CLLocationCoordinate2D) {
    let request = IsochroneRequest(
        lat: coordinate.latitude,
        lng: coordinate.longitude,
        contours: [5, 10, 15],      // minutes
        costing: .auto
    )
    GtelMapClient.shared.isochrone(request: request) { [weak self] response, message in
        guard let self, message.onCheckSuccess(), let response else { return }
        self.mapView.apply(input: .isochrone(
            response: response,
            originCoordinate: coordinate,
            callouts: nil
        ))
    }
}

func clearZones() {
    mapView.apply(input: .clearIsochrone)
}