HarmonyOS NEXT 6.1 游戏近场快传实战：碰一碰安装包传输

鸿蒙专家

在多人聚会或线下社交场景中，向好友推荐一款联机游戏的传统流程非常繁琐：告知名字、搜索应用市场、下载解压、手动安装——任何一个环节网络波动或操作中断都会导致转化失败。HarmonyOS NEXT 6.1（API 23）在 Game Service Kit（游戏服务套件）中新增了游戏近场快传（安装包传输）能力，通过碰一碰（knockShare）或隔空手势（gesturesShare）即可将已安装游戏的安装包直接发送给周围设备，并在接收端自动拉起游戏中心完成后台静默安装。本文基于“GameNearbyTransferDemo”工程，详解如何接管 Share Kit 传感器事件、创建近场快传任务并监听对端安装状态实现智能熔断控制。

一、项目结构概览

实战工程采用 Stage 模型，物理目录如下：

2. GameNearbyTransferDemo
3. ├── AppScope / app.json5
4. ├── entry
5. │ ├── oh-package.json5
6. │ └── src/main/ets
7. │ ├── entryability/EntryAbility.ets
8. │ └── pages
9. │ ├── Index.ets（引导页）
10. │ └── NearbyTransferDemo.ets（核心控制舱）
11. └── resources/base/profile/main_pages.json

复制代码

在路由表 main_pages.json 中注册这两个页面即可。控制舱页面 NearbyTransferDemo.ets 承载了所有近场快传逻辑。

二、碰一碰与隔空传送的传感器监听

游戏内必须通过 Share Kit 的 harmonyShare 接口来接管底层碰触和手势事件。系统能力为 SystemCapability.Share.Share。核心方法是：

2. harmonyShare.on(type: 'knockShare' | 'gesturesShare', callback: Callback<SharableTarget>): void

复制代码

- 'knockShare'：两台设备背靠背碰触时触发。
- 'gesturesShare'：由 UWB 空间感知手势触发。

注意事项：收到回调后必须在 3 秒内调用 sharableTarget.share(shareData) 将数据注入通道，否则底层协议栈会因超时自动关闭握手，导致失败。

三、创建近场快传服务并配置传输参数

游戏的近场快传入口由 GameServiceKit 的 gameNearbyTransfer.create 提供：

2. gameNearbyTransfer.create(createParameters: CreateParameters): Promise<CreateResult>

复制代码

系统能力要求 SystemCapability.GameService.GameNearby，且只能在 Stage 模型的 UIAbilityContext 中调用。关键参数 CreateParameters 包括：
- abilityName：当前 UIAbility 名称。
- moduleName：当前模块名称。
- contentType：必须设置为 ContentType.INSTALLATION_PACKAGE（值为 0）。
- gameLinking：游戏的 Scheme/Deeplink，例如 "nearbytransfer://com.huawei.game?type=nearby"，用于接收端拉起游戏。

成功创建后，createResult 中的 linkingForInstallation 即为分享用的超级链接。

四、对端安装状态监听与智能分流

创建快传后需立即绑定 onRemoteInstallationInfoNotify 回调，让发送端实时感知接收端是否已安装该游戏，从而避免重复传输大体积安装包：

2. gameNearbyTransfer.onRemoteInstallationInfoNotify(callback: Callback<RemoteInstallationInfo>): void

复制代码

回调参数 RemoteInstallationInfo 包含 installed（布尔值）字段。
- 若 installed===false：发送端自动推送安装包，接收端若检测到游戏中心未激活则自动拉起，接收安装包并静默安装。
- 若 installed===true：发送端应立即调用 destroy() 销毁当前服务，引导用户进入资源包（OBB/大地图）快传通道，节省带宽与电量。

五、核心代码实现（精简版）

引导页 Index.ets 仅做跳转，主要逻辑在 NearbyTransferDemo.ets 中。以下为控制舱关键部分：

2. import { systemShare, harmonyShare } from '@kit.ShareKit';
3. import { gameNearbyTransfer } from '@kit.GameServiceKit';
4. import { fileUri } from '@kit.CoreFileKit';
5. import { common } from '@kit.AbilityKit';
7. @Entry
8. @Component
9. struct NearbyTransferDemo {
10.     private uiContext = getContext(this) as common.UIAbilityContext;
11.     @State gameScheme: string = 'nearbytransfer://com.huawei.game?type=nearby';
12.     @State linkingUrl: string = '';
13.     @State remoteState = { installed: false, progress: 0 };
15.     // 启动传感器监听
16.     immersiveListening() {
17.         harmonyShare.on('knockShare', this.immersiveCallback);
18.         harmonyShare.on('gesturesShare', this.immersiveCallback);
19.     }
21.     // 取消监听（退出页面时务必调用）
22.     immersiveDisablingListening() {
23.         harmonyShare.off('knockShare', this.immersiveCallback);
24.         harmonyShare.off('gesturesShare', this.immersiveCallback);
25.     }
27.     // 传感器回调
28.     private immersiveCallback = async (sharableTarget: harmonyShare.SharableTarget) => {
29.         try {
30.             let resultLinking = await this.createNearbyTask();
31.             if (!resultLinking) {
32.                 sharableTarget?.reject(harmonyShare.SharableErrorCode.NO_CONTENT_ERROR);
33.                 return;
34.             }
35.             let filePath = this.uiContext.filesDir + '/shareIcon.jpg';
36.             let thumbnailUri = fileUri.getUriFromPath(filePath) || 'resource://RAWFILE/icon.png';
37.             let shareData = new systemShare.SharedData({
38.                 utd: uniformTypeDescriptor.UniformDataType.HYPERLINK,
39.                 content: resultLinking,
40.                 thumbnailUri: thumbnailUri,
41.                 title: '碰一碰极速传游戏',
42.                 description: '传送游戏安装包'
43.             });
44.             sharableTarget?.share(shareData);
45.         } catch (err) {
46.             sharableTarget?.reject(harmonyShare.SharableErrorCode.NO_CONTENT_ERROR);
47.         }
48.     };
50.     // 创建近场快传并注册状态监听
51.     async createNearbyTask(): Promise<string | undefined> {
52.         let initParam: gameNearbyTransfer.CreateParameters = {
53.             abilityName: this.uiContext.abilityInfo.name,
54.             moduleName: this.uiContext.abilityInfo.moduleName,
55.             contentType: gameNearbyTransfer.ContentType.INSTALLATION_PACKAGE,
56.             gameLinking: this.gameScheme
57.         };
58.         try {
59.             let createResult = await gameNearbyTransfer.create(initParam);
60.             this.linkingUrl = createResult.linkingForInstallation ?? '';
61.             // 注册对端状态回调
62.             gameNearbyTransfer.onRemoteInstallationInfoNotify((info) => {
63.                 this.handleRemoteInstallationInfo(info);
64.             });
65.             return this.linkingUrl;
66.         } catch (error) {
67.             return undefined;
68.         }
69.     }
71.     // 处理对端安装信息
72.     handleRemoteInstallationInfo(info: gameNearbyTransfer.RemoteInstallationInfo) {
73.         this.remoteState.installed = info.installed;
74.         if (info.installed) {
75.             this.destroyService('对端已安装，切断安装包传输');
76.         } else {
77.             // 继续当前传输（由底层自动处理）
78.         }
79.     }
81.     // 销毁快传服务
82.     destroyService(reason: string) {
83.         gameNearbyTransfer.offRemoteInstallationInfoNotify();
84.         gameNearbyTransfer.destroy().then(() => {
85.             // 提示用户可切换至资源包快传
86.         });
87.     }
88. }

复制代码

六、总结

通过 Game Service Kit 的游戏近场快传能力，开发者仅需几十行代码即可让游戏实现“碰一碰安装”的极速社交分享。核心要点包括：正确订阅 Share Kit 传感器事件、在 3 秒内完成数据推送、创建时指定 ContentType.INSTALLATION_PACKAGE 并配置 gameLinking，以及对端安装状态监听实现智能熔断。这一特性完美适用于派对、线下对战等场景，大幅提升游戏传播转化率。

热心网友7

感谢楼主的详细分享，这个“碰一碰传安装包”的功能很实用，尤其是多人聚会场景下能省去搜索和等待下载的麻烦。我有个小问题：如果接收端设备没有安装游戏中心，接收时会自动拉起后台静默安装，那是否需要用户额外授权？还是说所有操作对用户都是无感的？期待后续能有机会实测一下这个能力。

热心网友7

感谢楼主的详细分享！这个近场快传功能确实很有实用价值，尤其在聚会场景下能大大降低好友联机游戏的门槛。碰一碰或隔空手势触发安装包传输，还带智能检测对端是否已安装，避免重复传包，设计得很周到。 我有个小问题想请教：如果接收端没有安装游戏中心，代码中提到的“自动拉起游戏中心”是可以直接静默安装吗？还是需要用户确认授权？另外，传输过程中如果设备离开近场范围，是否有自动熔断或重试机制？期待楼主进一步讲解。

热心网友7

感谢楼主的详细分享！这个碰一碰传安装包的功能确实很实用，特别是聚会场景下能省去搜索下载的繁琐步骤。我比较好奇的是，对于大型游戏（比如几个G的安装包），近场快传的速度和稳定性怎么样？另外，接收端如果游戏中心没有预装或者被禁用了，自动拉起机制能生效吗？期待楼主后续能补充一些实际传输的测试数据。