开发注意事项

为了更好地保护最终用户的个人信息，规范 SDK 收集信息和获取设备标识的行为，鸿蒙地图 SDK 提供了统一配置对象 MapSDKConfig。开发者应在调用 Initializer.initialize() 前，先通过 Initializer.configure() 完成 MapSDKConfig 配置。
MapSDKConfig 当前包含以下能力：

• privacyAgreed：是否同意隐私政策

• oaidEnabled：是否允许 SDK 使用 OAID

其中，privacyAgreed 是地图初始化前的必选前置条件；如果未设置，Initializer.initialize() 会直接抛出异常。

鸿蒙地图 SDK 对外统一通过以下方式设置隐私状态和 OAID 开关：

import { Initializer, MapSDKConfigBuilder } from '@bdmap/base';

const config = new MapSDKConfigBuilder()
  .setPrivacyAgreed(true)
  .setOaidEnabled(true)
  .build();

await Initializer.configure(config);

接口说明如下：

/**
 * MapSDK 配置对象
 */
export interface MapSDKConfig {
  /**
   * 是否同意隐私政策
   * true: 同意
   * false: 不同意
   * null: 未设置
   */
  privacyAgreed: boolean | null;

  /**
   * 是否启用 OAID
   * true: 启用
   * false: 禁用
   */
  oaidEnabled: boolean;
}

/**
 * 配置构建器
 */
export class MapSDKConfigBuilder {
  public setPrivacyAgreed(agreed: boolean): MapSDKConfigBuilder;
  public setOaidEnabled(enabled: boolean): MapSDKConfigBuilder;
  public build(): MapSDKConfig;
}

/**
 * SDK 统一配置入口
 * 必须在调用 Initializer.initialize() 之前完成 privacyAgreed 配置
 *
 * @param config MapSDKConfig 配置对象
 */
public static async configure(config: MapSDKConfig): Promise<boolean>

注：

1. privacyAgreed 必须在调用 Initializer.initialize() 之前设置。

2. MapSDKConfigBuilder 默认值为：

• privacyAgreed = null

• oaidEnabled = true

3. 若 privacyAgreed 保持默认值 null，调用 Initializer.initialize() 时会抛出异常。

建议在 UIAbility 的 onWindowStageCreate() 中，先配置 MapSDKConfig，再执行 SDK 初始化，并对初始化阶段异常进行捕获：

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { Initializer, MapSDKConfigBuilder } from '@bdmap/base';

export default class EntryAbility extends UIAbility {
  async onWindowStageCreate(windowStage: window.WindowStage): Promise<void> {
    const config = new MapSDKConfigBuilder()
      .setPrivacyAgreed(true)
      .setOaidEnabled(true)
      .build();

    await Initializer.configure(config);

    try {
      await Initializer.getInstance().initialize('Your API_KEY', this.context);
    } catch (error) {
      console.error('Map SDK initialize failed:', JSON.stringify(error));
    }

    windowStage.loadContent('pages/Index');
  }
}

• 表示业务侧未完成隐私配置

• 调用 Initializer.initialize() 时会抛出异常：

Privacy mode is not set. Call configure() to set privacyAgreed before initialize().

表示业务侧明确设置为“不同意隐私政策”。
此时 SDK 会进入隐私受限模式，地图不支持发起检索、路线规划等数据请求

表示业务侧禁止 SDK 使用 OAID。
此时 SDK 的行为包括：清理内部OAID缓存，并停止使用OAID

鸿蒙地图 SDK 允许在初始化完成后再次调用 Initializer.configure() 更新 MapSDKConfig。
例如：

• 用户同意或撤回隐私政策后，重新调用 Initializer.configure()

• 用户切换 OAID 开关后，重新调用 Initializer.configure()

1. 在应用首次进入地图相关页面前，先完成隐私弹窗与业务侧授权确认。

2. 一旦用户作出选择，立即调用 Initializer.configure() 写入 MapSDKConfig。

3. 在 Initializer.initialize() 外层使用 try/catch 或 Promise 异常处理，避免因未配置 privacyAgreed 导致初始化异常未被捕获。