HarmonyOS NEXT 6.1 游戏近场快传实战：碰一碰安装包传输
在多人聚会或线下社交场景中，向好友推荐一款联机游戏的传统流程非常繁琐：告知名字、搜索应用市场、下载解压、手动安装——任何一个环节网络波动或操作中断都会导致转化失败。HarmonyOS NEXT 6.1（API 23）在 Game Service Kit（游戏服务套件）中新增了游戏近场快传（安装包传输）能力，通过碰一碰（knockShare）或隔空手势（gesturesShare）即可将已安装游戏的安装包直接发送给周围设备，并在接收端自动拉起游戏中心完成后台静默安装。本文基于“GameNearbyTransferDemo”工程，详解如何接管 Share Kit 传感器事件、创建近场快传任务并监听对端安装状态实现智能熔断控制。一、项目结构概览
实战工程采用 Stage 模型，物理目录如下：
GameNearbyTransferDemo
├── AppScope / app.json5
├── entry
│ ├── oh-package.json5
│ └── src/main/ets
│ ├── entryability/EntryAbility.ets
│ └── pages
│ ├── Index.ets（引导页）
│ └── NearbyTransferDemo.ets（核心控制舱）
└── resources/base/profile/main_pages.json
在路由表 main_pages.json 中注册这两个页面即可。控制舱页面 NearbyTransferDemo.ets 承载了所有近场快传逻辑。
二、碰一碰与隔空传送的传感器监听
游戏内必须通过 Share Kit 的 harmonyShare 接口来接管底层碰触和手势事件。系统能力为 SystemCapability.Share.Share。核心方法是：
harmonyShare.on(type: 'knockShare' | 'gesturesShare', callback: Callback<SharableTarget>): void
- 'knockShare'：两台设备背靠背碰触时触发。
- 'gesturesShare'：由 UWB 空间感知手势触发。
注意事项：收到回调后必须在 3 秒内调用 sharableTarget.share(shareData) 将数据注入通道，否则底层协议栈会因超时自动关闭握手，导致失败。
三、创建近场快传服务并配置传输参数
游戏的近场快传入口由 GameServiceKit 的 gameNearbyTransfer.create 提供：
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 回调，让发送端实时感知接收端是否已安装该游戏，从而避免重复传输大体积安装包：
gameNearbyTransfer.onRemoteInstallationInfoNotify(callback: Callback<RemoteInstallationInfo>): void
回调参数 RemoteInstallationInfo 包含 installed（布尔值）字段。
- 若 installed===false：发送端自动推送安装包，接收端若检测到游戏中心未激活则自动拉起，接收安装包并静默安装。
- 若 installed===true：发送端应立即调用 destroy() 销毁当前服务，引导用户进入资源包（OBB/大地图）快传通道，节省带宽与电量。
五、核心代码实现（精简版）
引导页 Index.ets 仅做跳转，主要逻辑在 NearbyTransferDemo.ets 中。以下为控制舱关键部分：
import { systemShare, harmonyShare } from '@kit.ShareKit';
import { gameNearbyTransfer } from '@kit.GameServiceKit';
import { fileUri } from '@kit.CoreFileKit';
import { common } from '@kit.AbilityKit';
@Entry
@Component
struct NearbyTransferDemo {
private uiContext = getContext(this) as common.UIAbilityContext;
@State gameScheme: string = 'nearbytransfer://com.huawei.game?type=nearby';
@State linkingUrl: string = '';
@State remoteState = { installed: false, progress: 0 };
// 启动传感器监听
immersiveListening() {
harmonyShare.on('knockShare', this.immersiveCallback);
harmonyShare.on('gesturesShare', this.immersiveCallback);
}
// 取消监听（退出页面时务必调用）
immersiveDisablingListening() {
harmonyShare.off('knockShare', this.immersiveCallback);
harmonyShare.off('gesturesShare', this.immersiveCallback);
}
// 传感器回调
private immersiveCallback = async (sharableTarget: harmonyShare.SharableTarget) => {
try {
let resultLinking = await this.createNearbyTask();
if (!resultLinking) {
sharableTarget?.reject(harmonyShare.SharableErrorCode.NO_CONTENT_ERROR);
return;
}
let filePath = this.uiContext.filesDir + '/shareIcon.jpg';
let thumbnailUri = fileUri.getUriFromPath(filePath) || 'resource://RAWFILE/icon.png';
let shareData = new systemShare.SharedData({
utd: uniformTypeDescriptor.UniformDataType.HYPERLINK,
content: resultLinking,
thumbnailUri: thumbnailUri,
title: '碰一碰极速传游戏',
description: '传送游戏安装包'
});
sharableTarget?.share(shareData);
} catch (err) {
sharableTarget?.reject(harmonyShare.SharableErrorCode.NO_CONTENT_ERROR);
}
};
// 创建近场快传并注册状态监听
async createNearbyTask(): Promise<string | undefined> {
let initParam: gameNearbyTransfer.CreateParameters = {
abilityName: this.uiContext.abilityInfo.name,
moduleName: this.uiContext.abilityInfo.moduleName,
contentType: gameNearbyTransfer.ContentType.INSTALLATION_PACKAGE,
gameLinking: this.gameScheme
};
try {
let createResult = await gameNearbyTransfer.create(initParam);
this.linkingUrl = createResult.linkingForInstallation ?? '';
// 注册对端状态回调
gameNearbyTransfer.onRemoteInstallationInfoNotify((info) => {
this.handleRemoteInstallationInfo(info);
});
return this.linkingUrl;
} catch (error) {
return undefined;
}
}
// 处理对端安装信息
handleRemoteInstallationInfo(info: gameNearbyTransfer.RemoteInstallationInfo) {
this.remoteState.installed = info.installed;
if (info.installed) {
this.destroyService('对端已安装，切断安装包传输');
} else {
// 继续当前传输（由底层自动处理）
}
}
// 销毁快传服务
destroyService(reason: string) {
gameNearbyTransfer.offRemoteInstallationInfoNotify();
gameNearbyTransfer.destroy().then(() => {
// 提示用户可切换至资源包快传
});
}
}
六、总结
通过 Game Service Kit 的游戏近场快传能力，开发者仅需几十行代码即可让游戏实现“碰一碰安装”的极速社交分享。核心要点包括：正确订阅 Share Kit 传感器事件、在 3 秒内完成数据推送、创建时指定 ContentType.INSTALLATION_PACKAGE 并配置 gameLinking，以及对端安装状态监听实现智能熔断。这一特性完美适用于派对、线下对战等场景，大幅提升游戏传播转化率。
Re: HarmonyOS NEXT 6.1 游戏近场快传实战：碰一碰安装包传输
感谢楼主的详细分享，这个“碰一碰传安装包”的功能很实用，尤其是多人聚会场景下能省去搜索和等待下载的麻烦。我有个小问题：如果接收端设备没有安装游戏中心，接收时会自动拉起后台静默安装，那是否需要用户额外授权？还是说所有操作对用户都是无感的？期待后续能有机会实测一下这个能力。Re: HarmonyOS NEXT 6.1 游戏近场快传实战：碰一碰安装包传输
感谢楼主的详细分享！这个近场快传功能确实很有实用价值，尤其在聚会场景下能大大降低好友联机游戏的门槛。碰一碰或隔空手势触发安装包传输，还带智能检测对端是否已安装，避免重复传包，设计得很周到。 我有个小问题想请教：如果接收端没有安装游戏中心，代码中提到的“自动拉起游戏中心”是可以直接静默安装吗？还是需要用户确认授权？另外，传输过程中如果设备离开近场范围，是否有自动熔断或重试机制？期待楼主进一步讲解。Re: HarmonyOS NEXT 6.1 游戏近场快传实战：碰一碰安装包传输
感谢楼主的详细分享！这个碰一碰传安装包的功能确实很实用，特别是聚会场景下能省去搜索下载的繁琐步骤。我比较好奇的是，对于大型游戏（比如几个G的安装包），近场快传的速度和稳定性怎么样？另外，接收端如果游戏中心没有预装或者被禁用了，自动拉起机制能生效吗？期待楼主后续能补充一些实际传输的测试数据。
页:
[1]