实战：React Native 集成 HMS Core

当我想写这样一篇文章的时候，取一个怎样的标题就把我难住了，其实今天只想讲明白一件事：“JavaScript 技术栈如何接入 HMS Core 从而实现‘超能力’的 App 开发？”，更直接一点就是“如何使用 React Native 集成 HMS Core？”。首先，为什么是 React Native？目前在大前端领域，跨端的框架选择并不多，除了多年依旧没发布 1.0 版本的 React Native，还有像 uniapp 、Taro、Rax 等同属于 JavaScript 技术向的框架，还有Xamarin、 Flutter 等其他技术向的跨端方案。而之所以选择 React Native ，主要还是因为 React Native 易于上手，就算不熟悉 JavaScript 也能快速入门。

前言

React Native^[1] 是使用 React 构建原生应用程序的框架，"Learn once, write anywhere: Build mobile apps with React",毫无疑问，这并不是一句空话，笔者所在的团队虽然没有原生开发人员但有幸使用 React Native 开发上线了多个跨端应用，至于体验怎样就先不提它，目前状况是“又不是不能用”，主要还是取决于“砌砖师傅”的手艺。Facebook 自 2015 年就开源了 React Native，至今一直在积极维护和使用，国内像腾讯QQ、京东、手机百度、小米有品等，或多或少都有使用 React Native。2022 年将是 React Native 开源新架构之年，同时 React Native 多平台愿景也在逐步实现，比如 Windows、MacOS、VR等端的开发探索，总之，React Native 即将到来的 1.0 版本值得期待！

“HMS Core^[2] 是华为终端云服务（HUAWEI Mobile Services）开放能力合集，位于开发者应用与操作系统之间，是为应用开发提供基础服务的平台。同时，依托华为云服务，HMS Core也为这些服务提供云端能力，用于各服务的开通、业务实现及运营。”，通俗地来讲，我们的应用集成 HMS Core 之后，就能获得人工智能、图形能力如AR、应用服务等能力。

如果您还没使用过React Native，没关系，毫不夸张地说，就算您不会 JavaScript，跟着官方文档或者社区的中文文档，不到半日便能开始开发 React Native 应用；如果您还没集成过 HMS Core，没关系，毫不夸张地说，就算您不懂编程，跟着官方文档动手实践，不出半日便能将强大的华为生态集成到您的应用中。“千里之行始于足下”，千万行的代码始于“Hello，World”，而代码的编写始于阅读官方文档。接下来，让我们遵循文档的脚步，开始在 React Native 中集成 HMS Core！

环境准备

React Native 中文网^[3]由武汉青罗网络科技有限公司维护，结合了该公司 React Native开发者在使用过程中的切身经验，一直以来坚持与官方文档保持同步更新，对国内 React Native 开发者来说是非常不错的学习资料。本文不再赘述不同开发平台、不同目标平台的 React Native 开发环境怎么搭建，仅以 Mac 开发平台下 Android 、 iOS 应用开发环境搭建为例。
先来一波劝退：

• 首先，暂时没找到一种不需要安装环境就能体验开发 React Native 的方式，而本地安装环境又非常占用磁盘空间，比如下图中仅安装 Xcode 及 Android Studio 就占用了近 20 G的容量，不过相比日渐臃肿的前端开发依赖也不足为奇。

  

• 其次，我们在使用 React Native 不同版本时所依赖的环境、版本也会有些差异，比如低于 0.67 版本的 React Native 构建 Android 应用时需要依赖 JDK 1.8 版本，也就是 Java 8，而本文使用的版本为 React Native ）。67，需依赖 JDK 11。因此，我们在使用 React Native 的过程中，可能存在多个环境，如我使用的 Mac 环境就安装了两个版本的 Java^[4]。总的来说，需要安装的依赖比较多，步骤也繁琐。

  平台/依赖	Windows	Mac	Linux
  Android	Node、JDK 和 Android Studio	Node、JDK 和 Android Studio	Node、JDK 和 Android Studio
  iOS	暂不支持	Node、Watchman、Xcode 和 CocoaPods	暂不支持

  

• 最后，由于众所周知的原因，我们在安装依赖的时候可能会遇到网络问题，如同 React Native 中文文档中所描述的“总之如果报错中出现有网址，那么 99% 就是无法正常连接网络”，此外无论是 Android 环境还是 iOS 环境，对于没有接触过的开发者来说，或多或少会有些心理负担，尤其是安装过程中多次碰壁之后。好在环境搭建好之后，就能持续使用，以后无论是开发 Android 还是 iOS，都能快速进行开发。

此刻，如果您还没有被劝退，建议您直接参考 ReactNative 中文文档搭建环境^[5]。

安装Node

Node.js® 是一个基于 Chrome V8 引擎 的 JavaScript 运行时环境。如今的前端生态已经非常依赖 Node.js,尤其是包管理器 -- npm。一般来说安装 Node 时我们可以选择从官网下载安装，在 Mac 上，我们也可以通过 `Homebrew`^[6] 来安装。

brew install node
brew install watchman

此外，为了应付本地同时安装不同 Node 版本的需要，我们可以安装 nvm^[7]来管理 Node 版本；为了满足不同 npm 镜像源的切换，我们可以安装 nrm^[8] 来管理镜像源。

如果直接下载 Node 遇到网络问题，可以尝试使用华为云镜像：https://repo.huaweicloud.com/nodejs/^[9],笔者之前的安装就是通过镜像下载然后一路next就装好了。

安装 JDK

Mac 环境下如果只想安装单个 JDK， 直接使用`Homebrew`^[10] 来安装：

brew install adoptopenjdk/openjdk/adoptopenjdk11

如果需要安装多个 JDK，就需要做一些特别的配置。笔者同样通过华为云镜像下载了多个 JDK --https://repo.huaweicloud.com/openjdk/^[11],安装之后修改~/.bash_profile进行多版本 JDK 的配置。比如：

export JAVA_11_HOME="/Library/Java/JavaVirtualMachines/jdk-11.0.2.jdk/Contents/Home"
export JAVA_8_HOME="/Library/Java/JavaVirtualMachines/jdk1.8.0_291.jdk/Contents/Home"
export JAVA_HOME=$JAVA_8_HOME
alias jdk8="export JAVA_HOME=$JAVA_8_HOME"
alias jdk11="export JAVA_HOME=$JAVA_11_HOME"

配置完成后执行 jdk11 就可以切换到 JDK 11.

安装 Android Studio 及 SDK

为什么要安装 Android Studio ？其实笔者也一直没想明白，作为前端开发代码编辑器首选 VS Code，感觉也没有使用 Android Studio 的需求，估计是为了方便安装 Android SDK 及安卓模拟器。访问https://developer.android.google.cn/studio/^[12]下载并安装Android Studio，下载时如果下载速度比较慢可以尝试使用迅雷或者通过可用的镜像下载，同样的一路next 进行安装。笔者当前安装的版本是 2022年2月17构建的 Android Studio Bumblebee | 2021.1.1 Patch 2。

如下图中的SDK Manager和Virtual Device Manager就是我们下载安装 Android Studio 后所需要用到的工具，一个是 Android SDK 管理，一个是安卓模拟器管理。通常来说，SDK Manager还可以在 Android Studio 的Preferences菜单中找到,具体路径是Appearance & Behavior → System Settings → Android SDK;而Virtual Device Manager在顶部的工具栏中可以找到 。

按照 React Native 文档推荐安装 Android 11 的编译环境，我们需要安装：

• Android SDK Platform 30
• Intel x86 Atom_64 System Image
• Android SDK Build-Tools 30.0.2

除了在 Android Studio 中操作，也可以通过执行命令行安装：

sdkmanager "platforms;android-30" "system-images;android-30;default;x86_64" "system-images;android-30;google_apis;x86"
sdkmanager "cmdline-tools;latest" "build-tools;30.0.2"

安装完毕之后，就是配置环境变量,同样的在~/.bash_profile进行添加：

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools

安装 XCode 及 CocoaPods

如果我们还想体验 React Native 开发 iOS，则还需要安装 XCode 及 iOS 所需的编译环境。如果 Mac 没有足够的存储空间，建议直接放弃，毕竟苹果的存储不便宜啊。

安装 Xcode 最简单的方法是通过 App Store^[13] 安装,安装 XCode 会同时安装 iOS 模拟器和所有必要的工具来构建我们的 iOS 应用程序。此外如果想使用 iOS 模拟器，还需自行选择安装，又是一笔不少的存储支出！

接着还需安装包管理器 CocoaPods：

sudo gem install cocoapods
# 或者使用 brew 安装
brew install cocoapods

至此， Android 和 iOS 的开发环境搭建完毕，我们不仅可以使用 React Native 来开发应用，也可以直接使用原生进行开发，如果此时还想体验 Taro 或者 Flutter，当前的环境也是能够满足的。接下来，我们将在AppGallery Connect 中创建我们要开发的应用。

AGC 介绍及 APP 创建

AGC 全称 AppGallery Connect，它是华为开发者联盟推出的一项服务，为开发者提供移动应用全生命周期服务，覆盖全终端全场景，降低开发成本，提升运营效率，助力商业成功。总的来说，AGC的使命就是助力开发者商业成功。AGC能快速孵化创意、提高开发效率、全球化分发、精细化运营、大数据分析……对于笔者而言，使用AGC主要还是因为在集成 HMS Core 之前，需要在AGC中创建项目、创建应用、打开相关服务。这一切操作的前提是注册华为账号、认证开发者！

账号准备完毕，登录 AppGallery Connect^[14] 创建我们将要开发的应用。这里笔者创建了一个名为HMS React Native的 Android 应用。

通过执行命令npx react-native init HMSReactNative初始化了一个 React Native 应用。期间，笔者也遇到依赖安装网络不畅的问题，基本上是靠多执行几次安装命令反复尝试解决的，如果一直存在网络报错的问题，则需要用到一些靠谱的代理软件来处理。

通过运行指令npm run android、npm run ios我们分别能在 Android 模拟器和iOS模拟器上运行 React Native 的 Hello World,值得注意的是首次运行因为加载依赖速度稍微慢些。这也就是 React Native 一直倡导的“一次学习，随处编写”。

接着我们打开AGC-我的项目^[15]完善一下应用的信息，比如包名。React Native 初始化的应用包名一般为com.项目名称小写，例如com.hmsrectnative

如果需要在 iOS 中集成，那么我们还需在 AGC 中创建 iOS 应用：

HMSCore SDK 集成

HMS 提供了全面的生态基础开放能力，比如图形相关的 AR引擎、VR引擎，比如人工智能相关的机器学习服务等等，所以的这些能力相关的文档和接入指南我们都可以通过访问HMS Core 官网^[16]获取。本次集成我们以华为分析服务（Analytics Kit）为例，尝试使用 React Native 集成进行开发。

AGC 开通服务

我们使用Analytics Kit服务的时候，需要在AppGallery Connect上开通Analytics Kit服务，如下图中进入到AGC-我的项目-华为分析找到项目概览进入相关页面填写信息进行开启。这里，笔者注意到AGC-我的项目-API 管理下有众多的服务如推送服务、手语服务、云存储、云托管、3D建模等等，除此之外，还提供服务端的Server SDK 配置，目前支持 Java 、NodeJS 服务端的集成。

开启Analytics Kit服务之后，HMS Core 官网贴地给出了集成文档的入口，按照文档的步骤我们基本能够完成在 Android 和 iOS 的集成Analytics Kit。其实在React Native开发过程中，如果集成的依赖有原生模块提供的方法时，集成方法就如同原生依赖的集成，不过往往在使用第三方依赖时，我们通常还要考虑是否能够兼容不同系统。像 hms-react-native-plugin^[17] ,目前只有react-native-hms-analytics实现了同时支持 Android 和 iOS，而且部分 API 也只有 Android才能使用。如果想在 iOS 中使用其他服务，还需开发者自行实现原生模块的开发。

添加AGC配置文件及集成

Android 端和 iOS 端添加AGC文件略有不同，Android 需配置应用签名信息，而 iOS 需要使用 Xcode 进行添加。

• Android

  ①在 React Native 的项目初始化过程中，自动生成了debug.keystore,我们通过执行命令生成 SHA256(PS:为了安全起见，请自行生成密钥)：

  keytool -list -v -keystore android/app/debug.keystore
  

  ②将生成的 SHA256 配置到 AGC：

  ③下载agconnect-services.json并放置到 React Native 项目下android/src下

  

  ④配置SDK地址，如新增Maven仓地址，修改android/build.gradle：

  buildscript {
    // ......
    repositories {
        google()
        mavenCentral()
        // 配置HMS Core SDK的Maven仓地址。
        maven {url 'https://developer.huawei.com/repo/'}
    }
    dependencies {
        classpath("com.android.tools.build:gradle:4.2.2")
        // 增加agcp插件配置，推荐您使用最新版本的agcp插件。
        classpath 'com.huawei.agconnect:agcp:1.6.0.300'
    }
  }
  
  allprojects {
      repositories {
          // ......
          // 配置HMS Core SDK的Maven仓地址。
          maven {url 'https://developer.huawei.com/repo/'}
      }
  }
  
  

  ⑤集成react-native-hms-analytics^[18],HMS Core 官方为 React Native 开发者提供了专用的 npm 包，我们通过 npm 包的安装指令安装：

  npm i @hmscore/react-native-hms-analytics
  

  修改android/app/build.gradle:

  apply plugin: "com.huawei.agconnect"
  // ...
  implementation project(':react-native-hms-analytics')
  

  修改android/settings.gradle:

  include ':react-native-hms-analytics'
  project(':react-native-hms-analytics').projectDir = new File(rootProject.projectDir, '../node_modules/@hmscore/react-native-hms-analytics/android')
  

• iOS

  ①下载agconnect-services.plist并放置到 React Native 项目下iOS 应用模块的根目录

  

  ② react-native-hms-analytics^[19] npm 包安装：

  npm i @hmscore/react-native-hms-analytics
  

  ③ 安装 Pod 依赖：

  cd ios && pod install
  

  ④ 初始化配置，修改ios/HMSReactNative/AppDelegate.m,在AppDelegate中添加:

  [HiAnalytics config]; // Initialization
  

多端开发

上文的步骤中我们已经分别在 Android 和 iOS 中集成了 HMS Core 中的分析服务 Analytics Kit，接下来就是见真章的时候了。使用 React Native，我们能够实现一套代码多端运行，快速开发 Android 和 iOS 两端的应用。直接上蹩脚的代码：

/**
 * Sample React Native App
 * https://github.com/facebook/react-native
 *
 * @format
 * @flow strict-local
 */

import React, {useState} from 'react';
import {
  Text,
  ScrollView,
  Platform,
  useColorScheme,
  SafeAreaView,
  StatusBar,
  Button,
  ToastAndroid,
  Alert,
  StyleSheet,
} from 'react-native';

import {Colors} from 'react-native/Libraries/NewAppScreen';
// 引入 HMS Analytics Kit
import HMSAnalytics from '@hmscore/react-native-hms-analytics';

const App: () => Node = () => {
  const isDarkMode = useColorScheme() === 'dark';
  const [aaid, setAaid] = useState('');
  const [userProfile, setUserProfile] = useState({});
  const backgroundStyle = {
    backgroundColor: isDarkMode ? Colors.darker : Colors.lighter,
  };
  // Android 初始化
  if (Platform.OS === 'android') {
    HMSAnalytics.getInstance()
      .then(res => {
        console.log({isInstanceAvailable: true});
      })
      .catch(err => console.log('getInstance', err));
  }

  const getAAID = async () => {
    // 获取 AAID
    HMSAnalytics.getAAID()
      .then(res => {
        console.log('getAAID', res);
        Platform.OS === 'ios' ? setAaid(res) : setAaid(res.aaid);
      })
      .catch(err => console.log('getAAID', err));
    // 开启分析服务
    HMSAnalytics.setAnalyticsEnabled(true)
      .then(res => console.log('setAnalyticsEnabled', res))
      .catch(err => console.log('setAnalyticsEnabled:error', err));
  };

  const gerUserProfile = async () => {
    // 获取用户信息
    HMSAnalytics.getUserProfiles(true)
      .then(res => {
        console.log('getUserProf', res);
        setUserProfile(res);
      })
      .catch(err => console.log('getUserProf:error', err));
  };

  const sendEvent = async () => {
    const eventId = '$CheckIn';
    const bundle = {
      $Days: 1,
      UserProfile: JSON.stringify(userProfile),
    };
    // 发送事件
    HMSAnalytics.onEvent(eventId, bundle)
      .then(res => {
        console.log('onEvent', res);
        Platform.OS === 'ios'
          ? Alert.alert('Success!')
          : ToastAndroid.show('Success!', ToastAndroid.SHORT);
      })
      .catch(err => console.log('onEvent:error', err));
  };

  return (
    
      'light-content' : 'dark-content'} />
      {aaid}
              onPress={() => {
          getAAID();
        }}
        title="Get AAID"
      />
      
        {userProfile
          ? Object.keys(userProfile)
              .sort()
              .map(function (key) {
                return (
                  
                    {key}:{userProfile[key]}
                  
                );
              })
          : null}
      

              onPress={() => {
          gerUserProfile();
        }}
        title="Get User Profile"
      />
              onPress={() => {
          sendEvent();
        }}
        title="Send Event"
      />
    
  );
};

const styles = StyleSheet.create({
  contentBox: {
    padding: 20,
    backgroundColor: '#eee',
  },
  h_300: {
    height: 300,
  },
});

export default App;

以上代码效果如下：

总的来说做了三件事：获取 AAID 、获取 UserProfiles、发送埋点事件。这里着重说说分析服务中的埋点分析。首先我们先设置埋点，Analytics Kit 中提供了游戏、教育、电商、运动健康、房产、汽车、通用、金融理财、出行旅游等众多行业模板，借助于模板，我们能快速设置埋点事件；比如打卡事件：

接着，编写调用代码，此处没有进行封装，实际业务中我们一般会对埋点方法进行封装：

HMSAnalytics.onEvent(eventId, bundle)

eventId就是事件ID,如通用模板中打卡事件的id是$CheckIn,bundle就是事件入参，如打卡事件默认的入参为$Days,还可以添加自定义参数，如上图中UserProfile。

接入完毕，我们还可以对埋点进行验证，不过前提是需要开启调试模式，此处以 iOS 为例，先在 XCode 中加入调试参数-HADebugEnabled上文中代码里边就实现了简单的事件上报，点击Send Event就会触发埋点事件，我们在埋点验证可以查看调用结果。

至此，我们使用 React Native 技术栈借助 HMS Core 实现了一些 JavaScript 本身不具备的能力。

回顾及总结

集成之路并非一帆风顺，笔者在整个实操过程中还是遇到了翻车，这里简单记录一下：

• 集成报错

  Plugin with id 'maven' not found.

• iOS 集成之后获取不到 AAID

集成步骤有遗漏初始化配置，导致没有正常连接 AGC 服务。

总得来说，我们集成 HMS Core 还是非常顺利的，理想状态下，我们可以一套代码实现 HMS Core 能力的落地，不过目前如果使用 React Native 开发的话， HMS Core 在 iOS 中使用还需开发者自行编写原生模块的代码，这对于新手来说还是有一定门槛，期待各路开发“用爱发电”不断完善和丰富 HMS Core，这样无论是 Android、iOS，还是 Web、鸿蒙，无论是快应用，还是云开发，通过 HMS Core，我们通通能把握！

本文首发于华为开发者联盟^[20]，公众号：胡琦 同步更新。

参考资料