SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsbaidu-map-ios-sdk

baidu-map-ios-sdk

Coding & development

View repository

Updated 10-15 18:45

About this skill

Baidu Maps iOS SDK

Goals and Boundaries

  • Goal: Correctly integrate Baidu Maps/location/walking and cycling navigation in an iOS project, and provide an implementation solution that complies with privacy and coordinate system specifications.
  • Responsible for: Integration, configuration, API selection, and examples for BaiduMapKit, BMKLocationKit, and BaiduWalkNaviKit; consistent with the reference documents within the skill.
  • Not responsible for: Driving navigation details (Baidu Maps driving navigation documentation), server-side logic, non-Baidu SDKs, UI visual design (only follow ui-standards.md specifications).

When to Use

Enable this skill when any one of the following is met:

  • Keywords: Baidu Maps, BMKMapView, BMKLocationKit, walking and cycling navigation, BaiduWalkNaviKit, annotations, route planning, CocoaPods integration, BD09, location authorization
  • Requirement types: map display, single/continuous/background location, real-time walking or cycling navigation, POI/annotations/overlays, route drawing, reverse geocoding, trajectory animation, point clustering, privacy popups

Load on demand: First select the document in reference.md according to the requirement, then reference the corresponding references content; if the requirement is ambiguous, clarify with the user before providing a solution.

Integration and Coding Order

  • When Baidu Maps SDK is not integrated: First configure and execute CocoaPods (write/complete the Podfile → execute pod install → use the generated .xcworkspace to open),after the SDK headers can be imported correctlythen write the code that calls maps/location/search, etc. This both avoids using #if __has_include(...) for conditional compilation and allows writing code based on the actual SDK headers, reducing interface inconsistencies or compilation errors.
  • When the SDK is already integrated locally: Directly import headers as needed and write code,based on the SDK version, headers, and interfaces in the current project; class names, methods, and parameters must be consistent with the local headers, and do not write APIs that do not exist. If a compilation error indicates a symbol does not exist, prompt the developer to verify or update the Pod version and then retry.

Agent Execution Requirements

  1. Proactively prompt for AK and Bundle
    When writing or integrating code that uses the maps/location SDK,proactively prompt the developer：

    • to apply in the Baidu LBS console for an iOS app AK, and the app's Bundle Identifier must be consistent with the project's PRODUCT_BUNDLE_IDENTIFIER ;
    • reserve/replace the AK location in the code or configuration (such as AppDelegate the key in, or explain that it needs to be configured in the console), and note "replace YOUR_AK with the actual AK".
    • If the project has not yet configured a Bundle ID, remind the developer to set it and make it consistent with the package name entered when applying in the console.

  2. Automatically execute compilation fixes after writing code, and stop once compilation succeeds
    After completing code modifications related to Baidu Maps/location,mustExecute according to the following process,Do not end while compilation has not passed：

    • Automatically execute compilation: use xcodebuild -workspace xxx.xcworkspace -scheme xxx -destination 'generic/platform=iOS' build(or an equivalent command; use workspace for CocoaPods projects, and project for pure projects).
    • If compilation reports errors: based on the error information,fix immediately(class names, method signatures, header files, ARC, protocol declarations, etc.), and after fixing,execute compilation again。
    • Loop: repeat "compile → if there are errors, fix → compile again" untilcompilation passes with no errors。
    • Stop after compilation is error-free: only after the build succeeds (BUILD SUCCEEDED) should this round of code modification and fixing end; do not continue making additional modifications unrelated to compilation.

  3. Configure Launch Screen to avoid a non-fullscreen App
    When integrating maps or involving fullscreen display,mustensure the project has configured Launch Screen, to avoid black bars or non-fullscreen display after running. For details, see project-config.md"Window Initialization/Launch Screen":

    • Within the project there is LaunchScreen.storyboard(or an equivalent Launch resource), and it is added to the target's Resources;
    • In Info.plist configure UILaunchStoryboardName as LaunchScreen；
    • If missing, proactively create it or supplement the explanation, and remind the developer to add this configuration.

Rules that must be followed

  1. Privacy and configuration

    • Before first use, a popup must be shown for the user to read and agree to the privacy policy, and then the corresponding API may be called.
    • Map：[BMKMapManager setAgreePrivacy:YES]（class method, do not use sharedInstance; when not agreed, search may return nil).
    • Location: through BMKLocationAuth 's setAgreePrivacy after the user agrees, then initialize BMKLocationManager, etc.; for details, see location.md。
    • Info.plist must configure CFBundleDisplayName; when using location, configure NSLocationWhenInUseUsageDescription, etc. For details, see project-config.md。
    • AK and Bundle: When writing integration code, proactively prompt the developer to provide/configure the AK, and the Bundle Identifier must match the one applied for in the Baidu console (see "Agent execution requirements" above).
    • Launch Screen: LaunchScreen.storyboard and Info.plist's UILaunchStoryboardName must be configured to avoid the App being non-fullscreen or having black bars after running; see project-config.md。

  2. Coordinate system

    • The map SDK uses globally BD09; the location SDK defaults to GCJ02. When mixed with maps, it must be unified to BD09: set the location coordinateType to BMKLocationCoordinateTypeBMK09LL, or use utils.md 's BMKCoordTrans conversion.

  3. Annotations and geometry (must be followed)

    • Point annotations must preferentially use Marker, and must not use Annotation/PinAnnotation: point annotationsmust preferentiallyuse BMKIconMarker/BMKTextMarker(addOverlay system),forbiddenUse BMKPointAnnotation, BMKAnnotationView, BMKPinAnnotationView (the addAnnotation system) except in the following cases: point clustering (BMKClusterManager must use BMKPointAnnotation), fixed screen point selection (isLockedToScreen), and other scenarios that can only be implemented with addAnnotation. For start/end points, cars, ordinary pins, etc., always use Marker. See overlays.md、annotations.md。
    • For distance, field of view, bearing, etc., use utils.md such as BMKGeometry; do not write them by hand.
    • Routes and start/end points must prioritize textures: when drawingroutes, prioritize BMKPolylineView.textureImage(image width and height must be a power of 2) or, for traffic scenarios, use BMKMultiTexturePolylineView + assets traffic textures;start/end points' BMKIconMarker.icon must prioritize assets of icon_start、icon_end; only when no texture is available should strokeColor/solid color or custom drawing be used. See overlays.md"Routes and Start/End Points: Texture Priority".
    • Route car texture: the car icon on the routemust prioritizethe texture images provided by this skill assets（assets/images/(such as icon_car, car_triangle, track_car); only when no texture is available should solid colors or custom-drawn images be used.

  4. Walking/cycling: distinguish two approaches according to requirements

    • Route planning (route calculation + line drawing): BMKRouteSearch (BaiduMapKit), walkingSearch/ridingSearch, then draw the polyline yourself after obtaining the route. See route.md。
    • Walking/cycling real-time navigation: BaiduWalkNaviKit, Manager + guidance, TTS, off-route correction, multiple instances/no UI. See navi.md。
    • The two aredifferent services: if you only need to draw lines, use route; if you need real-time navigation, use navi. Before giving a solution, first choose the correct documentation according to the developer's requirements.

  5. Versions and APIs are subject to the local environment(consistent with "Integration and Coding Order" above)

    • Already integrated SDK:subject to the SDK version and header files in the project, class names, methods, parameters consistent with the header files; do not write #if __has_include, write code directly after importing the header files.
    • If a certain class, method, or property in the user's projectdoes not exist(compilation error or no such symbol in the header file),prompt the user to update the corresponding Pod to the latest versionand then retry; do not force writing nonexistent APIs according to the documentation.

  6. Logo must not be obscured and route viewport adaptation (must be considered)

    • Logo must not be obscured: the Baidu Maps Logo must not be removed and must not be obscured by UI. When there is a floating bar/bottom bar,mustuse setMapPadding to reserve boundaries (e.g., reserve the search panel at the top, reserve barH+4 at the bottom), so that the Logo falls within the visible content area. See ui-standards.md"Map Logo, Compass, and mapPadding".
    • Route viewport adaptation must be done: when a route is drawn,mustcall fitVisibleMapRect:edgePadding:withAnimated: for viewport adaptation; edgePadding according to ui-standards.md"Route viewport adaptation" reserved (top search panel +50+marker, bottom bar +20+marker, left and right 50+marker, etc.), to avoid the route or start/end points being clipped or obscured by the UI. mapPadding and the edgePadding of fitVisibleMapRect are used separately; do not mix them.

Output specification (evaluable)

When providing a solution, it must satisfy:

  • Actionable: includes specific class names, methods, call order, and necessary configuration (such as Info.plist, privacy call timing, Launch Screen).
  • Verifiable: privacy and coordinate system handling are explicit; if it involves location authorization failure, the solution may point to the "Authorization Failure Troubleshooting" of location.md .
  • Composable: select documents and common combinations according to reference.md ; for walking/cycling selection see Rule 4.
  • AK/Bundle prompt: when map/location initialization is involved, explicitly prompt the developer to configure AK and Bundle Identifier.
  • After writing, compile until it passes: after completing the code writing, automatically execute xcodebuild compilation; if there are errors, fix them according to the errors and recompile, looping until compilation succeeds, then stop.
  • Full screen and Launch Screen: when map full screen or window size is involved, confirm or explain that LaunchScreen.storyboard and UILaunchStoryboardName have been configured, to avoid non-full-screen or black bars after running.
  • Logo not obscured: when a map is involved and there is a floating bar/bottom bar, the solutionmustinclude setMapPadding, and explain that the bottom reservation should be as small as possible (such as barH+4), to ensure the Logo is not obscured.
  • Route viewport adaptation: when route drawing is involved, the solutionmustinclude the edgePadding setting of fitVisibleMapRect, reserving top, bottom, left, and right according to ui-standards, to ensure the route and start/end points are within the visible area and not obscured by the UI.
  • Use Marker for point annotations: when map point annotations are involved (start/end points, car, pins, etc.),mustuse BMKIconMarker/BMKTextMarker (addOverlay), and must not use BMKPointAnnotation/BMKPinAnnotationView, except for exceptional scenarios such as point clustering or fixed-screen point selection.
  • Route and start/end point texture priority: when route polylines or start/end point Markers are involved,mustprioritize textures (route: BMKPolylineView.textureImage or BMKMultiTexturePolylineView; start/end points: BMKIconMarker.icon uses the icon_start/icon_end of assets ), and only write strokeColor or custom drawing when no texture is available; see overlays.md"Routes and start/end points: texture priority".

Solution structure: requirements → corresponding documents → configuration and dependencies (including AK/Bundle, Launch Screen) → key APIs → example snippets → notes (including Logo/route viewport, Marker priority).

Reference index