帮你快速理解、总结文档立即下载
文档中心>游戏多媒体引擎

导入 SDK 到项目

最近更新时间：2026-06-01 19:23:01
我的收藏

本页目录：

本文介绍如何快速地将 GME SDK（HarmonyOS 版本）集成到您的 HarmonyOS 项目中。

开发环境要求

集成开发环境：6.0.0.858 或以上。
手机操作系统：HarmonyOS 5.0.5 或以上。
API Version：17 或以上。

通过 DevEco Studio 集成 HarmonyOS SDK

步骤1：下载 SDK

下载 SDK，解压后的 SDK 得到的目录结构如下：

GME_OHOS_sdk_3.x.x.xxx/
├── GME_OHOS_3.x.x.xxx.har    # 鸿蒙 HAR 包（推荐使用）
├── ets/                       # ArkTS 接口源码（参考用）
│   ├── gme/                   
│   ├── common/               
│   ├── liteav_base/           
│   └── liteav_ui/            
├── etslib/                    # GMESDK.ts 整合接口（参考用）
├── include/                   # C/C++ 头文件（NDK 场景使用）
│   ├── tmg_sdk.h
│   ├── av_room.h
│   ├── av_audio_ctrl.h
│   ├── av_audio_effect_ctrl.h
│   ├── av_ptt.h
│   ├── av_type.h
│   └── av_error.h
└── libs/                      # 不同 ABI 的 native so 库
    ├── arm64-v8a/             # libgmesdk.so / libtxffmpeg.so / libtxsoundtouch.so
    └── x86_64/

说明：
鸿蒙 SDK 已将所有 ArkTS 接口、Native SO 库一起封装到 GME_OHOS_3.x.x.xxx.har，集成时建议通过集成 har 包方式接入 GME SDK 库。只需导入 GME_OHOS_3.x.x.xxx.har 即可。

步骤2：新建 DevEco Studio 工程

打开 DevEco Studio，新建一个 Empty Ability 工程，本文以工程名 GMEApplication、模块名 entry 为例。


步骤3：拷贝 SDK

将 GME_OHOS_3.7.0.651.har 拷贝到工程的 entry/libs/ 目录下（若目录不存在请新建）：

GMEApplication/
└── entry/
    └── libs/
        └── GME_OHOS_3.x.x.xxx.har

步骤4：配置 SDK 依赖

打开 entry/oh-package.json5，在 dependencies 中以本地文件方式声明 gmesdk 依赖：
{
  "name": "entry",
  "version": "1.0.0",
  "description": "Please describe the basic information.",
  "main": "",
  "author": "",
  "license": "",
  "dependencies": {
    "gmesdk": "file:./libs/GME_OHOS_3.7.0.651.har"
  }
}
保存后，在 DevEco Studio 中执行 File > Sync and Refresh Project ，同步 SDK 成功后，entry/oh_modules/gmesdk/ 目录会自动生成。

步骤5：签名

自动签名（推荐：用于本地真机调试，如对外发布需要手动签名）
1. 顶部菜单 File > Project Structure
2. 左侧 Project > Signing Configs
3. 选中 default 配置 > 勾选 Automatically generate signing
4. 点击 Sign In，使用 实名认证过的华为开发者账号 登录
5. 等待 IDE 自动从 AGC（AppGallery Connect）申请 Debug 证书与 Profile，回填到 build-profile.json

步骤6：验证 SDK 导入是否正确

到这里，HarmonyOS 的 SDK 的配置已经完成，需要使用的 .ets 页面中导入 GMESDK，并调用 GetSDKVersion() 验证：

import { BusinessError } from '@kit.BasicServicesKit';
import { GetTMGInstance, TMGContext, TMGDelegate, ITMG_MAIN_EVENT_TYPE } from 'gmesdk';

@Entry
@Component
struct Index {
  @State sdkVersion: string = '';

  // GME 事件回调
  private tmgDelegate: TMGDelegate = {
    OnEvent: (type: ITMG_MAIN_EVENT_TYPE, data: string) => {
      console.info(`[GME] OnEvent type=${type}, data=${data}`);
    }
  };

  // 进入页面即拉取 SDK 版本号
  aboutToAppear(): void {
    try {
      const tmg: TMGContext = GetTMGInstance(getContext(this));
      tmg.SetTMGDelegate(this.tmgDelegate);
      this.sdkVersion = tmg.GetSDKVersion();
      console.info(`[GME] SDK Version: ${this.sdkVersion}`);
    } catch (err) {
      const e = err as BusinessError;
      this.sdkVersion = '获取失败';
      console.error(`[GME] GetSDKVersion failed: ${e.message}`);
    }
  }

  build() {
    Column({ space: 16 }) {
      Text('GMEApplication')
        .fontSize(22)
        .fontWeight(FontWeight.Bold)
        .margin({ top: 40 })

      Text(`SDK Version: ${this.sdkVersion}`)
        .fontSize(16)
        .fontColor('#1A73E8')
    }
    .width('100%')
    .height('100%')
    .alignItems(HorizontalAlign.Center)
  }
}
如果可以正常返回版本号字符串（如 `3.x.x.xxx`），说明 SDK 已经成功集成。


步骤7：配置必要权限

1. 麦克风权限申请
如果使用实时语音功能，需要在 entry/src/main/module.json5 的 module 节点下添加 requestPermissions 申请麦克风权限。
{
  "module": {
    // ... 其他配置 ...
    "requestPermissions": [
      {
        "name": "ohos.permission.MICROPHONE",
        "reason": "$string:permission_microphone_reason",
        "usedScene": {
          "abilities": ["EntryAbility"],
          "when": "always"
        }
      },
      { "name": "ohos.permission.INTERNET" },
      { "name": "ohos.permission.GET_NETWORK_INFO" },
      { "name": "ohos.permission.KEEP_BACKGROUND_RUNNING" }
    ]
  }
}
并在 entry/src/main/resources/base/element/string.json 中追加申请理由文案：
{
  "string": [
    { "name": "permission_microphone_reason", "value": "用于实时语音采集" }
  ]
}
2. 配置后台模式（backgroundModes）
在实时语音时应用切到后台或锁屏时仍需要持续采集与播放音频时需要在 EntryAbility 上声明 backgroundModes，并搭配 KEEP_BACKGROUND_RUNNING 权限。
在 entry/src/main/module.json5 的 abilities 数组里，给目标 Ability（这里是 EntryAbility）加上 backgroundModes：
{
  "module": {
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        // ... 其他字段保持不变 ...
        "backgroundModes": [
          "audioRecording",   // 后台音频采集
          "audioPlayback"     // 后台音频播放
        ]
      }
    ],
    "requestPermissions": [
      { "name": "ohos.permission.MICROPHONE",
        "reason": "$string:permission_microphone_reason",
        "usedScene": { "abilities": ["EntryAbility"], "when": "always" }
      },
      { "name": "ohos.permission.INTERNET" },
      { "name": "ohos.permission.GET_NETWORK_INFO" },
      { "name": "ohos.permission.KEEP_BACKGROUND_RUNNING" }
    ]
  }
}


中国站