鸿蒙开发-HMS Kit能力集(地图服务、华为支付服务)

地图服务

Map Kit（地图服务）是鸿蒙生态下的一个地图服务，为开发者提供强大而便捷的地图能力，助力全球开发者实现个性化地图呈现、地图搜索和路线规划等功能，轻松完成地图构建工作。

Map Kit提供了千万级别的 Poi（Point of Interest，兴趣点）。在地图表达中，一个 Poi 可代表一家商铺、一栋办公楼、一处景点等等。

Map Kit在Poi和路网信息展示方面，根据Poi属性信息及区域路网差异，在不同层级比例尺条件下，为用户展示更合适的Poi和路网信息。手势交互方面，提供了包括缩放、旋转、移动、倾斜等流畅的交互体验。

在这里插入图片描述

AGC控制台创建应用

步骤一：登录AppGallery Connect（简称AGC），点击“我的项目”，在项目中点击“添加项目”，输入项目名称后，点击“创建并继续”。
在这里插入图片描述

步骤二：项目创建完成后， “添加应用”.
注：应用包名需与DevEco Studio 创建HarmonyOS应用工程的Bundle name一致。
在这里插入图片描述

创建HarmonyOS工程

新工程包名需与AppGallery Connect创建应用时一直。
在这里插入图片描述
注：Bundle name需与AGC创建应用时应用包名一致

Client_id设置

新工程的entry模块的module.json5配置的module下，加入AGC应用的client_id分支设置

"metadata": [
 {
  "name": "client_id",
  "value": "111403049" 
   //配置为获取的Client ID
   }
]

添加公钥指纹

调试Map Kit（华为账号）必须

使用一台登录了华为账号的真机
对工程自动签名，产生调试证书
在AGC上对应的项目中，添加公钥指纹

在这里插入图片描述

开通地图服务

应用的“API管理”中搜索map，开启“地图服务”

在这里插入图片描述

地图呈现

MapComponent是地图组件，用于在您的页面中放置地图。

MapComponentController是地图组件的主要功能入口类，用来操作地图，与地图有关的所有方法从此处接入。

它所承载的工作包括：地图类型切换（如标准地图、空地图）、改变地图状态（中心点坐标和缩放级别）、添加点标记（Marker）、绘制几何图形(MapPolyline、MapPolygon、MapCircle)、各类事件监听等。

在这里插入图片描述

MapComponent接口说明

在这里插入图片描述

我的位置权限

启用“我的位置”之前，您需要确保您的应用可以获取用户定位。获取用户定位有两种方式：
方式一：申请ohos.permission.LOCATION和ohos.permission.APPROXIMATELY_LOCATION权限，需在module.json5配置文件中声明所需要的权限

"requestPermissions": [
      {
        "name": "ohos.permission.LOCATION",
        "reason": "$string:location_permission",
        "usedScene": {
          "abilities": [
            "MainAbility"
          ],
          "when": "inuse"
        }
      },
      {
        "name": "ohos.permission.LOCATION_IN_BACKGROUND",
        "reason": "$string:background_location_permission",
        "usedScene": {
          "abilities": [
            "MainAbility"
          ],
          "when": "inuse"
        }
      },
      {
        "name": "ohos.permission.APPROXIMATELY_LOCATION",
        "reason": "$string:fuzzy_location_permission",
        "usedScene": {
          "abilities": [
            "MainAbility"
          ],
          "when": "inuse"
        }
      }
    ]

请求权限代码

import { abilityAccessCtrl, bundleManager, common, PermissionRequestResult, Permissions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

在这里插入图片描述

华为支付服务

Payment Kit（华为支付服务）提提供了方便、安全和快捷的支付方式，将强大的支付、营销、运营等能力通过HarmonyOS系统级接口形式开放给广大开发者，集成便捷且快速。用户可在开发者的应用/元服务内通过支付完成实体商品或服务的购买并展示支付结果。
华为支付功能由花瓣支付（深圳）有限公司提供，打造更安全、更便捷的HarmonyOS系统支付体验，助力开发者的业务增长。
Payment Kit当前提供三种接入方式：商户、平台类商户、服务商，开发者需要根据实际业务模式选择适用的合作身份。

华为支付接入分类

华为支付接入分类

开发者可以选择直连商户模式，直接与华为支付对接，使用华为支付服务的经营主体。该模式下，我们提供支付产品及签约代扣产品，支持您的多种载体，包括HarmonyOS应用和元服务。

服务商

开发者可以选择服务商模式，作为华为支付商户与华为支付之间的连接者，为商户提供开户申请、支付接入、技术开发等综合解决方案机构，您需要在中国支付清算协会备案。该模式下，我们提供支付产品，支持您的多种载体，包括HarmonyOS应用和元服务。

平台类商户

华为支付服务场景

商城购物场景

用户在商户App选购完不同的商品后，可以直接在商户App应用内完成下单和支付。

会员包月场景

用户在商户App应用/元服务开通会员，在支付流程中，同时完成支付和签约，待签约生效后，商家可以按照协议中的时间直接发起免密代扣请求完成扣款续费，无需用户每个月都进行开通会员操作。

会员续费场景

用户在商户App应用/元服务中完成签约关系后，会员到期后商户系统可以直接发起免密代扣请求完成扣款续费，无需用户进入收银台并且输入支付密码。

华为支付服务功能

移动支付

商户可在移动端App中集成华为支付功能，轻松实现线上收款，支持银行卡、余额等支付工具。

元服务支付

商户可在元服务应用中集成华为支付功能，轻松实现线上收款，支持银行卡、余额等支付工具。

签约代扣

针对商户需要用户周期付款场景下推出的功能，与用户签订协议后，商户可按照约定的代扣规则发起扣款。

在这里插入图片描述

AGC控制台创建应用

步骤一：登录AppGallery Connect（简称AGC），点击“我的项目”，在项目中点击“添加项目”，输入项目名称后，点击“创建并继续”。

步骤二：项目创建完成后，点击项目设置页面“添加应用”按钮，在“添加应用”页面中设置参数后，点击“确认”。

注：应用包名需与DevEco Studio 创建HarmonyOS应用工程的Bundle name一致，均为com.nutpi.chapter0308，且应用分类选择“游戏”。
在这里插入图片描述

添加公钥指纹

调试Payment Kit（华为支付）必须

使用一台登录了华为账号的真机
对工程自动签名，产生调试证书
在AGC上对应的项目中，添加公钥指纹

在这里插入图片描述

开通Payment Kit

步骤一：登录AppGallery Connect平台，选择“我的项目”。
步骤二：在项目列表中找到项目，在项目下的应用列表中选择需要开通Payment Kit的应用。
在这里插入图片描述

步骤三：在左侧导航栏选择“盈利 > 华为支付服务（非虚拟类） > 立即开通”。

在这里插入图片描述
步骤四：（如果已有商户号请忽略本步骤）点击“申请支付商户号”，详细介绍参考华为支付商户入网。申请商户号后，还需要为商户号申请绑定AppID，详细参见商户号绑定AppID。

在这里插入图片描述

商户号绑定AppID

绑定AppID说明
商户后续支付交易依赖于AppGallery Connect中创建应用生成的AppID与商户号的关联关系，因此在华为支付商户入网成功后，需要在华为支付商户平台将商户号与AppID进行绑定才可发起交易。
暂不支持平台子商户及特约商户发起绑定AppID申请。
商户发起绑定AppID申请，同主体（商户号、AppID所关联的营业主体信息）时无需华为支付人工审核。异主体绑定需要商户联系产品侧沟通，申请绑定权限后才可发起绑定以及需要华为支付人工审核后，应用管理员登录AppGallery Connect网站才能对商户号绑定AppID进行授权。
AppID主体与特约商户一致或者与服务商一致，则认为同主体。

特定场景配置操作

接入非快捷支付（即非单次支付）能力，需商户提前联系产品侧开通对应产品（如签约代扣）。
如需要生成及下载对账单，需管理员先在“华为支付商户平台>功能设置”中开启“对账单接口获取开关”，开启后次日开始生成前一日的账单。
涉及服务商户代特约商户发起退款场景，需要服务商在华为支付商户平台上申请API退款授权完成特约商户退款授权操作。

在这里插入图片描述

证书准备

商户证书是指由商户申请的，包含商户的商户号、公司名称、公钥信息的证书。该证书文件要求为pem格式，支持RSA和SM2两种算法。商户可以自行生成公私秘钥证书，上传至华为支付商户平台。
商户将公钥证书提交到华为支付商户平台后才能获得证书ID，证书ID为请求HTTP请求头鉴权信息PayMercAuth对象中的authId。商户入网完成后，可以在：“商户中心”->“证书管理”->“上传商户证书”->“证书ID”处获取。

在这里插入图片描述
商户私钥
商户自行生成或申请商户证书时，会配套生成商户私钥。请妥善保管好商户私钥文件。
商户请求签名使用商户私钥，请妥善保管好商户私钥文件，不要把私钥文件暴露在公共场合，如上传到Github，写在客户端代码等。
商户私钥用于商户对API请求中的信息进行签名。

华为支付证书
华为支付证书是指由华为支付提供的，包含华为支付平台标识、公钥信息的证书。该证书算法为SM2。
商户请通过华为支付商户平台下载华为支付证书。
华为支付证书中的公钥用于商户对回调通知中的信息进行验签。

商户证书生成

公钥证书生成后须商户手动上传到平台，用于Payment Kit服务器对支付请求验证签名。
商户证书需要满足如下要求：
后缀要求：华为支付商户平台接收的公钥证书格式为“*.pem”。
格式要求：生成RSA公私钥时，密钥长度要求不小于3072，密钥格式为PKCS#8。
使用JavaScript的库线下生成
配置好node执行环境并使用文本编辑器新建文件，拷贝以下代码到文件中并保存命名为“generateKeyPair.js”。
打开命令行工具，执行node generateKeyPair.js命令。
从结果中拷贝生成的公私钥并保存。结果如右图所示：
在这里插入图片描述

商户证书上传与下载

上传商户证书
请登录华为支付商户平台，在“证书管理 >上传商户证书”模块进行商户证书公钥上传（生成方式及上传要求请参见商户证书生成）。
待上传公钥信息示例：
下载华为支付证书
通过“华为支付证书”模块进行华为支付证书下载，该证书用于校验华为支付给商户业务系统发送的信息，如支付结果信息等。

在这里插入图片描述

端侧应用配置

在HarmonyOS应用/元服务“entry/src/main/module.json5”文件中module的metadata节点下增加client_id和app_id属性配置。

在这里插入图片描述

云侧服务准备

华为支付服务提供了支付系统相关的一系列API接口。为减小API接口的接入工作量，华为支付服务提供了java版本对应的maven依赖用于云侧服务对接。
开发者可通过Maven集成来完成服务器开发环境的构建，以此来快速使用华为支付提供的API接口。
可下载示例代码支付-华为支付服务-服务端用以快速完成商户服务器接入。

单次支付业务流程

开发者通过接入Payment Kit单次支付，可以简便快捷的实现应用的支付能力。

商户客户端请求商户服务器创建商品订单。
商户服务器按照商户模型调用Payment Kit提供的直连商户预下单或平台类商户/服务商预下单接口获取预下单号（prepayId），然后组建orderStr返回给客户端。
商户客户端调用requestPayment接口调起Payment Kit客户端收银台。
用户在Payment Kit客户端收银台完成支付操作后，Payment Kit客户端会收到支付结果信息。
Payment Kit客户端展示支付结果页，用户关闭支付结果页
Payment Kit客户端会返回支付状态给商户客户端。
支付完成后，Payment Kit服务器会调用回调接口返回支付结果信息给商户服务器。
商户服务器收到支付结果回调响应后，使用SM2验签方式对支付结果进行验签。

在这里插入图片描述

单次支付开发步骤

步骤一：预下单（服务器开发）

开发者按照商户模型调用直连商户预下单或平台类商户/服务商预下单接口获取预支付ID（prepayId）。
为保证支付订单的安全性和可靠性需要对请求body和请求头PayMercAuth对象内的入参排序拼接进行签名。请参考排序拼接和签名示例代码。
构建orderStr。
商户服务器需要将客户端支付接口入参orderStr签名后返回给客户端。

在这里插入图片描述

步骤二：拉起华为支付收银台（端侧开发）