入门指南

2.1 环境准备与获取 Key

工程基线为 JDK 17、Gradle 8.7、Android Gradle Plugin 8.5.2、compileSdk 34、minSdk 23；源码使用 Java 11，开启 desugaring。客户工程可使用经自行验证的其他兼容版本。

申请Sukha Android Key 时提供：应用 applicationId、实际 APK 签名证书 SHA1、授权数据集及地图/搜索/路线/导航能力。调试证书和正式证书分别登记。高德 Key 不可用于Sukha服务。

2.2 配置工程

将解压出的 maven 放到客户工程根目录的 vendor/sukha/maven。

// settings.gradle
dependencyResolutionManagement {
    repositories {
        maven { url = uri("$rootDir/vendor/sukha/maven") }
        google()
        mavenCentral()
    }
}

// app/build.gradle
android {
    compileSdk 34
    defaultConfig { minSdk 23 }
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_11
        targetCompatibility JavaVersion.VERSION_11
        coreLibraryDesugaringEnabled true
    }
}
dependencies {
    implementation 'cn.sukha.maps:maps-core:0.1.0-alpha.23'
    implementation 'cn.sukha.maps:maps-services:0.1.0-alpha.19'
    implementation 'cn.sukha.maps:maps-location:0.1.0-alpha.21'
    // 自定义导航时引入
    implementation 'cn.sukha.maps:maps-navigation-services:0.1.0-alpha.36'
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.0.3'
}

若采用完整地图界面，选择 maps-ui:0.1.0-alpha.79，由 POM 引入其依赖。不要混用不同批次模块。第三方 AndroidX、MapLibre 等依赖仍由 Google/Maven Central 获取。

2.3 配置 Manifest

<!-- manifest 节点下 -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!-- 使用定位才需要以下权限；还需宿主进行运行时申请 -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<!-- application 节点内，替换成自己的授权信息 -->
<meta-data android:name="cn.sukha.maps.API_KEY" android:value="YOUR_ANDROID_KEY" />
<meta-data android:name="cn.sukha.maps.SERVICE_URL" android:value="https://map.sukha.cn" />
<meta-data android:name="cn.sukha.maps.DATASET_ID" android:value="YOUR_DATASET_ID" />

示例经纬度位于演示数据范围；YOUR_DATASET_ID 由提供方分配，不能用示例坐标推断覆盖全国或全球。

2.4 显示第一张地图

下面是 Activity 的最小结构，在宿主完成所需的授权流程后进入此页。它不主动申请或启动定位。

package example;

import android.app.Activity;
import android.os.Bundle;
import cn.sukha.mapsdk.maps.MapView;
import cn.sukha.mapsdk.maps.CameraUpdateFactory;
import cn.sukha.mapsdk.maps.model.LatLng;
import cn.sukha.mapsdk.services.core.MapsInitializer;

public class QuickStartActivity extends Activity {
    private MapView mapView;
    @Override public void onCreate(Bundle state) {
        super.onCreate(state);
        MapsInitializer.initialize(this);
        mapView = new MapView(this);
        setContentView(mapView);
        mapView.onCreate(state);
        mapView.getMapAsync(map -> map.moveCamera(
            CameraUpdateFactory.newLatLngZoom(
                new LatLng(21.67623, 100.02228), 16)));
    }
    @Override protected void onStart() { super.onStart(); mapView.onStart(); }
    @Override protected void onResume() { super.onResume(); mapView.onResume(); }
    @Override protected void onPause() { mapView.onPause(); super.onPause(); }
    @Override protected void onStop() { mapView.onStop(); super.onStop(); }
    @Override protected void onSaveInstanceState(Bundle out) {
        super.onSaveInstanceState(out); mapView.onSaveInstanceState(out);
    }
    @Override public void onLowMemory() { super.onLowMemory(); mapView.onLowMemory(); }
    @Override protected void onDestroy() { mapView.onDestroy(); super.onDestroy(); }
}

宿主还需在 Manifest 声明此 Activity。getMapAsync 表示地图控制对象可用，不保证所有网络数据已加载。通过 MapView.setOnMapLoadListener 的 onMapLoadError(SdkException) 接收数据加载失败。

2.5 示例约定

后续示例为方法体片段，context 为 Activity/Context，map 是 getMapAsync 得到的 SukhaMap，report(value) 表示宿主更新界面或记录日志。示例并非全部顺序执行。常用 imports：

import cn.sukha.mapsdk.maps.*;
import cn.sukha.mapsdk.maps.model.*;
import cn.sukha.mapsdk.services.core.*;
import cn.sukha.mapsdk.services.poisearch.*;
import cn.sukha.mapsdk.services.inputtips.*;
import cn.sukha.mapsdk.services.geocoder.*;
import cn.sukha.mapsdk.services.route.*;
import cn.sukha.mapsdk.location.SukhaLocationClient;
import cn.sukha.mapsdk.location.SukhaLocationClientOption;