鸿蒙Next星河版应用开发——如何调用地图功能（从正确手动签名说起）

一、地图功能与一般功能的区别

鸿蒙系统可以使用华为自带的地图功能，要使用这些功能，必须填写手动签名才可以,这是与一般的功能相区别的。注意 Windows 模拟器暂不支持地图功能，只有使用具有Next系统的真机以及mac模拟器，才能查看地图。

（一）一般功能——可自动签名的功能

一般的，由用户自己设定的功能，简单的功能，在使用DevEco编译器进行测试的过程中，是经常需要签名的。

（二）地图功能简介——需手动签名的功能

地图功能属于需要调用API的一种特殊服务，需要使用远程的地图API接口，如华为地图、高德地图等，为用户提供便利的地图操作体验。

地图功能属于已经被封装好的功能，有许多Kit包可以调用，其中典型的包如Location Kit位置服务包。

另外，除了系统已经封装好的API及相应方法，还需要在华为的AGC(AppGallery Connect)应用程序链接库中，调用自己建立的HarmonyOS应用。

二、手动签名的要件

下图中Key alias、Key password 相当于账号密码（Store password与Key password可保持一致），而Store file、Profile file、Certpath file都是要存储在特定文件路径下的秘钥。在最后要进行签名的过程中，下面红色框中的位置，都是要预先设置、存储好的密码与秘钥。

总结一下生成签名证书需要的要件：

（1）.p12 秘钥

（2）Key Store password、Key alias、Key password 账号、密码

（3）csr 文件

（4）.p7b 秘钥

（5）.cer 秘钥

AGC开启地图服务

配置应用包和证书

配置项目的 module.json5 中的应用指纹(Client ID)

三、手动签名具体方法

（一）手动签名共配置四个证书文件：

在 DevEco Studio 工具侧生成密钥（.p12）和证书请求文件（.csr）。
在 AppGallery Connect 侧申请应用证书（.cer）、Profile（.p7b）文件。生成签名证书指纹

（二） DevEco Studio 工具侧

要生成私钥和证书请求文件：点击构建菜单——生成私钥和证书请求文件

（1）生成.p12秘钥文件

没有时直接新建，有的时候可选已有文件

（2）设置Key store password、Alias、Password

Key store password、Alias在测试中可设为一致方便记忆，但一定要创建文档记录账号密码，以防未来遗忘。

（3）生成.csr文件

设置好Key store password、Alias、Password后,点击“Next”，开始创建.csr文件

注意，这里的CSR file的文件名字可自己拟定，点击选择所在文件夹后输入文件名自行确定。（如下文中我使用的是Csr.csr的文件名）

（三）AppGallery Connect 侧

AGC入口：AppGallery Connect

（1）申请调试证书 .cer

注意点：

请确保您的开发者帐号已实名认证。

每个帐号最多申请 2 个调试证书，1个发布证书。

证书格式为 .cer，包含公钥、证书指纹等信息。

发布证书由AGC颁发的、为HarmonyOS应用配置签名信息的数字证书，可保障软件代码完整性和发布者身份真实性。

申请过程：

① 登录AppGallery Connect，选择“用户与访问”。

② 在左侧导航栏点击“证书管理”，进入“证书管理”页面，点击“新增证书”。

③ 在弹出的“新增证书”窗口填写要申请的证书信息，点击“提交”。

参数	说明
证书名称	不超过100个字符，随意。
证书类型	选择“调试证书”。
选取证书请求文件（CSR）	选择本地 .csr 文件。

④证书申请成功后，“证书管理”页面展示证书名称等信息。点击“下载”，将生成的证书保存至本地，供后续签名使用。

（2）创建HarmonyOS应用

华为官方文档参考：创建HarmonyOS应用

创建HarmonyOS应用是获取.p7b文件的必要前置步骤，核心步骤如下

（1）创建项目

（2）创建应用

（3）在项目下添加应用

以上操作完成好后，在“项目设置”的“常规”栏目下就可以看见项目和应用的资料，注意要选取“应用”中的内容进行后续操作。

后续操作：根据应用信息修改两个位置的代码

注意： 应用包名需要确保唯一性，最后记得更新项目 AppScope/app.json5 的 bundleName 的配置。

下图中，红色框出的部分是我们在项目中需要引入代码的内容，红线的部分需要我们主动生成，这里仅做一个大体了解即可，后面会给出详细说明。

修改对应文件的内容

修改一： 应用包名需要确保唯一性，需要更新项目 AppScope/app.json5 的 bundleName 的配置。

修改二：在 entry/src/main/module.json5 下添加metadata字段，其中value部分为AGC应用中显示的Client ID。

添加模板如下：

"module": {
  // 地图服务所需的配置如下：CV 后改 value 即可
  "metadata": [
    {
      "name": "client_id",
      // 注意：从自己的 AGC 应用中复制，每个用户的都不一样
      "value": "xxxxxx"  
    }
  ],
  // metadata 跟 requestPermissions 同级
  "requestPermissions": [],
  "name": "xxxx",
  "type": "entry",
  "description": "xxxx",
  "mainElement": "xxxx",
  "deviceTypes": [],
  "pages": "xxxx",
  "abilities": [],
}

坑点说明：metadata的输入易出错，建议复制黏贴上面代码

在metadata中，client_id的格式必须严格以小写字母中间加下划线的方式表示，value则是重AGC应用中复制过来的Client ID，如果把name直接复制Client ID输入则会出错，地图无法显示。

（3）申请调试Profile .p7b

前提条件

● 已创建您的AGC项目，并已在项目下创建HarmonyOS应用/元服务。 ● 已申请调试证书，并注册至少一个调试设备。

操作步骤

登录AppGallery Connect，选择“我的项目”。注意：未实名开发者可在当前页面的顶部菜单下拉列表中选择“我的项目”。
找到您的项目，点击您创建的HarmonyOS应用/元服务。
选择“HarmonyOS应用 > HAP Provision Profile管理”，进入“管理HAP Provision Profile”页面，点击右上角“添加”。
在弹出的“HarmonyAppProvision信息”窗口添加调试Profile，完成后点击“提交”。

在添加了HarmonyOS应用后，点击下载按钮，即可得到.p7b密钥文件

（四）汇总签名要件

在完成好以上操作后，我们拥有了下面的要件，就可以进行签名登录了

登录要件：

（1）.p12 秘钥

（2）Key Store password、Key alias、Key password 账号、密码

（3）.csr 文件

（4）.p7b 秘钥

（5）.cer 秘钥

具体操作如下:

在File > Project Structure > Project > Signing Configs > default界面中，取消“Automatically generate signature”勾选项，然后配置工程的签名信息。

Store File：选择密钥库文件，文件后缀为 .p12。

Store Password：输入密钥库密码。

Key Alias：输入密钥的别名信息。忘记请重新操作。

Key Password：输入密钥的密码。

Sign Alg：签名算法，固定为 SHA256withECDSA。

Profile File：选择申请的发布Profile文件，文件后缀为 .p7b。

Certpath File：选择申请的发布数字证书文件，文件后缀为 .cer。