Convertor

概述

Convertor工具是为您提供的代码转换工具，支持Java和Kotlin工程。能够帮助您基于已有的调用第三方API的Android应用代码，快速转换为集成HMS Core的应用代码。工具提供了如下功能来帮助您完成转换：

• New Conversion：新建代码转换。
• Open Last Conversion：加载最近一次未完成的转换。
• Save All：备份当前工程以及转换信息。
• Restore Project：使用备份文件恢复工程。

代码转换流程如下：

1. Analyze：使用工具来分析应用工程使用第三方API的情况，帮助您做集成前的准备。
2. Select conversion policy：选择转换策略。工具为您提供了两类可选的转换策略：Add HMS API和To HMS API。
   • Add HMS API：在原来调用第三方API的代码基础上增加适配层代码模块（xmsadapter），该适配层代码能够根据调度策略来调用第三方API或HMS API，具体的调度策略将由您来决定。如果您希望该应用能够在没有第三方服务的华为手机上运行，那么您可以选择HMS API优先的调度策略。

     使用此转换策略的一大优势在于，您可以用一套业务代码来完成对第三方API或HMS API的调用以及同时上架第三方应用市场和华为应用市场。工具为您自动生成的xmsadapter模块实现第三方API与HMS API的调度，将业务代码与适配代码分离/解耦，您只需要关注业务，无需为第三方API和HMS API间的差异耗费过多精力。

     更详细的原理描述请参见Add HMS API策略的原理介绍。

   • To HMS API：将App代码中调用第三方API代码替换为调用相应的HMS API代码，转换后的代码直接调用HMS API。
3. Converting：提供转换界面帮助您方便完成转换操作，支持一键快速完成自动转换。
4. Build：转换后提供不同的打包策略，支持在不同的应用市场上架相应的应用包APK。

Convertor工具菜单入口如图所示：

开发环境要求

• JDK 1.8及以上
• Kotlin 1.3及以上

使用限制说明

转换工具仅支持基于代码的转换（选定的代码工程），不包含工程依赖的第三方包。

若您在工程中使用compile关键字引入依赖，请将其修改为implementation。

各Kit支持转换的情况如下表（仅列举出了支持HMS API转换的Kit）：

New Conversion

前提条件

• 在开始转换前，您需要完成AGC配置、集成HMS Core SDK、开通相关服务等开发准备工作。详细操作指导请参见文档中心里各Kit开发指南中的“开发准备”。
• 转换前，您需要先了解Android中Intent用法的注意事项：

  如果使用到intent.getXXX()或者intent.putXXX()方法时，需要手工书写Add HMS API策略代码，例如。

  使用GMS API的代码：

  DetectedActivity detectedActivity = ...;
  Intent intent = new Intent(BROADCAST_INTENT_ACTION);
  intent.putExtra(DETECTED_ACTIVITY_EXTRA_ID, detectedActivity);

  手工转换后的代码：

  DetectedActivity detectedActivity = ...;
  Intent intent = new Intent(BROADCAST_INTENT_ACTION);
  if (org.xms.g.utils.GlobalEnvSetting.isHms) {
      intent.putExtra(DETECTED_ACTIVITY_EXTRA_ID, (com.huawei.hms.location.ActivityIdentificationData)detectedActivity.getHInstance());
  } else {
      intent.putExtra(DETECTED_ACTIVITY_EXTRA_ID, (com.google.android.gms.location.DetectedActivity)detectedActivity.getGInstance());
  }

分析转换项目

下面的动画演示了一个项目的分析和转换过程。

1. 打开New Conversion，有以下四种方式：
   • 在菜单栏选择“HMS > Convertor > New Conversion”。
   • 在工具栏点击如下图标。

     

   • 快捷键“Ctrl+Alt+K”。
   • 代码区右键，选择“Convertor > New Conversion”。
2. 设置需要转换的Project Type、Analysis Path、Excluded Path和Backup Path信息，然后点击“Next”，等待分析完成。

   

   其中：

   • Project Type：需要转换的工程类型。
     • App：可独立编译，可运行的工程。
     • Library：只是独立的库，无法单独运行的工程。
   • Analysis Path：选择待分析工程的根目录。
   • Excluded Path：不需要扫描的文件目录，保持默认即可。一般为“.svn”目录、“.git”目录、“.gradle”目录、“.idea”目录、“build”目录和“gradle”目录。
   • Backup Path：备份转换前的项目文件，用于后续恢复工程。只能选择该工程外的目录。其中Excluded Path中的文件不会进行备份。
   • Comment out original code during conversion：注释模式，勾选生效后，代码区执行自动转换后，会对原始代码进行注释。
3. 设置转换策略，可以根据需要选择To HMS API或者Add HMS API，然后点击“Analyze”，执行转化分析。

   如果“Project Type”选择了“App”，会在xmsadapter文件下生成XMS代码。显示页面是：

   

   如果“Project Type”选择“Library”，显示页面是：

   

   展开

   关键字段	说明
   Update the following items before analysis	需要您在转换前注意以下几点： 需要使用JDK 1.8。 涉及使用AndroidX特性的，需要加上相关配置。 检查Android SDK的minSdkVersion和targetSdkVersion是否满足当前使用的HMS Core服务的要求。要求的版本请参见Gradle信息维护。 需要升级GMS服务的SDK，升级到兼容版本号，才能支持转换操作（无需升级则界面不展示）。各Kit要求的最低GMS API版本号请参见各Kit对GMS API的版本要求。
   Analysis Result	工程使用GMS API的情况统计，可以点击Details查看当前工程中使用GMS服务的API情况。
   Add HMS API	在您的应用中添加HMS Core。通过桥接的XMS API，即您的应用既可以调用GMS API，也可以调用HMS API。 在支持HMS API但是不支持GMS API的设备上，您的应用会调用HMS API。 在HMS API和GMS API都支持的设备上，应用可以通过您设置的策略来决定优先调用GMS API还是HMS API。
   To HMS API	将GMS API转换为HMS API，使您的App能在华为手机上运行。
   HMS API First	您的应用面向支持HMS API但是不支持GMS API的设备发布，可以配置您的路由策略优先调用HMS API。
   GMS API First	您的应用面向支持GMS API但是不支持HMS API的设备发布，可以配置您的路由策略优先调用GMS API。
   Dependent GMS APIs	当前项目使用到的GMS API和GMS method情况。
   Convertible GMS Methods	两种转换策略下，可自动转换和手动修改的GMS API方法数，以及自动转换率。
   Unconvertible GMS APIs	两种转换策略下，分别不支持转换的GMS API情况。请根据该结果选择适合您的转换策略。
   Unconvertible GMS Methods	HMS不支持的GMS方法总数。详情请点击Details。
   Select a conversion policy	选择支持的转换策略。其中Add HMS API可以设置HMS API优先还是GMS API优先。
   Generate code for creating app dependent only on GMS SDK	Add HMS API转换策略下，提供差异化的adapter代码生成能力，支持您构建只依赖GMS服务的APK包。勾选该复选框会显示提示信息，点击提示信息的链接可以查看文档中的详细描述。
   Generate code for creating app dependent only on HMS SDK	Add HMS API转换策略下，提供差异化的adapter代码生成能力，支持您构建只依赖HMS服务的APK包。勾选该复选框会显示提示信息，点击提示信息的链接可以查看文档中的详细描述。
   Path for storing the generated code (for Add HMS API only)	Add HMS API转换策略下，XMS代码存放在工程根目录下xmsadapter module。
   Export analysis result	工程使用GMS API的情况统计，可以点击“Export analysis result”导出当前工程中使用GMS服务的API情况。

4. Add HMS API场景下，您需要在工程中初始化路由。

   结合转换过程中选择的HMS API或者GMS API路由优先策略，您需要在工程中调用GlobalEnvSetting.init方法，决定App程序运行在HMS环境或者GMS环境。路由设置方法请参见Add HMS API场景下路由初始化策略介绍。

   init方法用于检测当前手机环境是否可以运行HMS服务或者GMS服务。

5. 转换分析结果如下所示。关键字段的说明请参见下表。

   

   展开

   关键字段	说明
   Show Converted	勾选：展示所有已转换和未转换的记录。 不勾选：展示尚未做过处理的记录。 说明 只能展示本次扫描结果的处理记录。如果您已经处理过后再次扫描项目，则上次扫描后的处理记录无法查看。
   Convert	对选中的记录执行转换操作。
   Revert	对选中的已经执行自动转换的记录进行回退。当前不支持“Ctrl+Z”的回退方式。
   Total	扫描出需要处理的总条目数。
   Converted	已经执行自动转换或者手动修改的记录总数。
   Conversion Type	扫描结果可以进行转换的类型，分为三类： Auto：使用工具的convert功能可自动转换，无需确认。 Dummy：HMS不支持该方法，adapter只封装了GMS的方法，需您确认是否保留或删除，确认好后，使用工具的convert功能可自动转换。 Manual：工具不支持自动转换，需要您手工转换。
   Content	扫描结果需要进行转换的原始内容。
   Description	转换修改说明。

6. 查看每个转换条目的详细分析结果，有如下两种方式：
   • 点击待转换条目，可以跳转到项目中对应的代码处。
   • 双击待自动转换条目，可以展示自动转换前后代码的差异对比。

处理分析结果

下面的动画演示了如何处理分析结果的过程。

从分析结果来看，部分GMS的API接口是可以通过IDE自动进行转换的，但是部分API接口不支持自动转换，需要手工进行转换。

Auto、Dummy类型支持如下三种方式进行转换修改。

• 方式一（推荐）：勾选需要进行自动转换的条目，然后点击“Convert”，自动完成转换工作。Auto和Dummy支持全选和单选。如果您想一键全选Auto或一键全选Dummy，请在“Conversion Type”中筛选类别后再点击一键全选按钮。

  

• 方式二：点击待转换的条目，定位到具体修改点，点击“Apply HMS Convertor Auto-Convert”，确认修改。转换完成后对应的转换项置灰且被勾选。

  

• 方式三：双击待转换的项目，进入HMS Convertor diff页面。左侧（Original File）表示转换前项目，右侧（Fix File）表示转换后项目。点击，将Fix File的内容同步到Original File中，关闭页面完成转换。

  

  说明

  Fix File不能编辑修改。

  转换完成回到转换分析结果页面，对应的转换项置灰且被勾选。如果要回退转换，勾选需要回退转换的条目，然后点击“Revert”即可。

  

Manual类型转换方法：点击待修改条目定位到具体修改点，然后根据扫描结果中的Description描述进行手动修改。修改完成后，手动将修改条目的复选框由修改为状态。

全部转换项转换完成且转换项状态为或后，会提示您是否进行完整性检查，点击“Jump”即可跳转到完整性检查页面。

手工指导窗口说明（目前只支持Map Kit和Location Kit）：

• 如何跳转到手工指导窗口

  手工指导窗口为使用HMS Toolkit的过程中需要进行手工转换的开发者提供帮助，点击Conversion tab页面中Location/Map Kit的手工修改条目，点击下图中“Go to Manual Instruction”即可跳转到手工指导窗口。

  

• 功能详解

  手工指导窗口如图所示：

  

  • 1处和2处分别是GMS和XMS代码描述。
  • 3处和4处分别是GMS和XMS代码示例，实现的是相同的功能。左边高亮的代码是当前指定的API，右边的是对应的XMS的API，该部分支持拷贝。
  • 点击5处“Help”可跳转到官网指导文件查看帮助文档。
  • 点击6处可生成包含手工指导接口的Demo工程，帮助您更好地理解和适配手工指导接口。点击“Create Demo Project”显示如下窗口，选择需要生成的Kit组合（目前只支持Map和Location），点击“Next”选择一个空的目录即可生成Demo工程。

    

    成功后在右下角有如下所示弹框，点击“Open Project”即可用Android Studio打开该工程。

    

Add HMS API场景下，您需要根据业务上下文实现Add HMS API的代码逻辑转换。提供了以下API供您使用，具体的使用方法可以参见各个Kit的手工转换指导书（可通过手工修改条目中的Description链接获取）。

编译项目

确认所有的记录都处理完成后，进行编译，编译通过则转换完成。

Open Last Conversion

在菜单栏选择“HMS > Convertor > Open Last Conversion”，可以打开上次转换结果，即直接进入到上次转换的扫描分析结果界面。

Save All

备份当前工程以及转换信息。

对于大型项目，当您执行了部分转换，希望对转换中的工程代码以及转换列表进行存量备份时，点击“Save All”可以实现当前转换中的工程代码以及转换列表备份。后续可以通过“Restore Project”进行恢复，然后从备份时的进度继续完成转换。

备份路径固定为您在上一次执行扫描时设置的“Backup Path”目录。备份的zip文件名称为“工程名+时间戳+注释模式+转换策略+转换进度”。

Restore Project

在菜单栏选择“HMS > Convertor > Restore Project”，打开备份工程的恢复设置界面，可以将指定备份目录下的文件恢复到目标目录。

恢复文件后，需要手动在work tree选中当前工程目录，然后右键选择“Reload from Disk”进行刷新。当前备份分为两种：

• 名称为“工程名+时间戳”的备份，这是对于转换前工程进行的备份，选择这样的备份进行恢复，会还原到转换前的工程，并清空转换列表信息。
• 名称为“工程名+时间戳+注释模式+转换策略+转换进度”的备份，这是工具菜单中的“Save All”功能生成的备份文件，选择该备份文件进行恢复，不仅恢复工程代码，同时还加载转换列表信息，恢复后，可以继续进行转换操作。

Compare XMS Code

您对XMS代码进行了修改或者添加了新的Kit。再次使用转换工具，为了让您能更好的感知新、旧XMS代码前后的差异。工具会根据新的gradle依赖生成新的XMS代码。有以下两种场景。

场景一

您重新使用工具生成XMS代码。重新生成一份代码到xmsadapter文件夹中，旧的XMS代码会被备份，并且提供新旧XMS代码比较功能。

1. 通过“New Conversion”重新生成XMS代码，并指定XMS生成代码的路径。

   

2. 看到下面提示，表示重新生成XMS代码成功。点击“OK”。

   

3. Adapter Updates界面展示新、旧XMS代码的差异，点击“Open backup folder”打开旧的XMS代码备份路径，点击“Open new folder”打开新生成的XMS代码的路径，表格展示变化的文件列表。
4. 双击文件，查看文件对比。
5. 您根据前后两份XMS代码进行手工合并到xmsadapter中。

   

场景二

您在原来的工程上通过Repository引入新的Kit，生成新的XMS代码。

1. 选择要添加的Kit。

2. 和场景一的操作一样，您需要进行手工合并XMS代码。