Version: v4

UE5 SDK 开发指南

本文介绍如何在游戏中接入 TapTap 内嵌动态功能，使用内嵌动态功能需依赖 TapTap 登录。

当前 UE5 插件仅实现 Android 和 iOS；Tap PC 下不会打开动态页面或执行发布等操作。

集成前准备

参考开发者中心配置创建应用、配置包名与签名证书
参考 UE5 集成指南完成 TapSDK 基础接入
内嵌动态依赖于 TapTap 登录模块，开发者接入前应先完成 TapTap 登录的接入

等待初始化和登录成功后再调用动态接口。

权限说明

Android 权限说明

该模块在 Android 平台需要如下权限：

权限	使用目的	权限申请时机
网络权限	用于访问网络数据	用户首次使用该功能时会申请权限
获取网络状态	用于检测当前网络连接是否有效	用户首次使用该功能时会申请权限
读写存储权限	用于发布或下载动态页面内图片、视频	下载或使用本地图片发布动态时申请

该模块将在 Android 应用中添加如下权限：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"
  tools:ignore="ScopedStorage" />
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES"/>
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

iOS 权限说明

该模块在 iOS 平台需要如下权限：

权限	使用目的	权限申请时机
相册权限	获取相册中图片或保存网络图片到相册中	用户首次使用该功能时会申请权限
相机权限	用于拍照或录视频	用户首次使用该功能时会申请权限
麦克风权限	用于录视频时获取声音	用户首次使用该功能时会申请权限

通过项目的 iOS Additional Plist Data 或项目自己的 iOS 构建配置，将以下条目加入最终应用的 Info.plist，并替换授权文案：

<key>NSPhotoLibraryUsageDescription</key>
<string>用于选择和保存动态中的图片或视频</string>
<key>NSCameraUsageDescription</key>
<string>用于拍摄动态中的照片或视频</string>
<key>NSMicrophoneUsageDescription</key>
<string>用于录制动态视频的声音</string>

SDK 获取

参考 UE5 集成指南完成 TapCore 基础接入。再从下载页下载相同版本的 TapLogin、TapMoment，放入项目的 Plugins 目录并启用。

添加模块依赖

在游戏模块的 <GameModule>.Build.cs 中添加：

PublicDependencyModuleNames.AddRange(new string[]
{
    "TapCore",
    "TapLogin",
    "TapMoment",
});

修改 Build.cs 后重新生成项目文件并编译。

设置回调

设置回调以获取动态的状态变化。

实现 ITapMomentCallback，重写 OnMomentResult_Implementation，并在打开动态页面前调用 SetCallback 注册。

#include "TapMoment.h"

UCLASS()
class UGameMomentHandler : public UObject, public ITapMomentCallback
{
    GENERATED_BODY()
public:
    virtual void OnMomentResult_Implementation(int32 Code, const FString& Message) override
    {
        // 根据 Code 处理动态事件，回调值见下表。
        UE_LOG(LogTemp, Log, TEXT("Moment event [%d]: %s"), Code, *Message);
    }
};

// 初始化和登录成功后，在游戏对象的成员函数中创建并注册
MomentHandler = NewObject<UGameMomentHandler>(this);
TScriptInterface<ITapMomentCallback> Callback;
Callback.SetObject(MomentHandler.Get());
Callback.SetInterface(Cast<ITapMomentCallback>(MomentHandler.Get()));
UTapMoment::SetCallback(Callback);

// 不再需要事件时，传入空接口清除
// UTapMoment::SetCallback(TScriptInterface<ITapMomentCallback>{});

用 UPROPERTY 成员 MomentHandler 持有处理对象，直到停止监听。

回调方法中 Code 表示事件类型，现支持的回调类型如下：

回调	回调值	说明
`PublishSuccess`	10000	动态发布成功
`PublishFail`	10100	动态发布失败
`PublishCancel`	10200	关闭动态发布页面
`GetNoticeSuccess`	20000	获取新消息成功
`GetNoticeFail`	20100	获取新消息失败
`MomentAppear`	30000	动态页面打开
`MomentDisappear`	30100	动态页面关闭
`CloseCancel`	50000	取消关闭所有动态界面（弹框点击取消按钮）
`CloseConfirm`	50100	确认关闭所有动态界面（弹框点击确认按钮）
`LoginSuccess`	60000	动态页面内登录成功
数值 `70000`	70000	场景化入口回调

获取新消息

定时调用获取消息通知的接口，有新信息时可以在 TapTap 动态入口显示小红点，提醒玩家查看新动态。

UTapMoment::FetchNotification();

获取消息通知的结果会在本文刚开始设置的回调中返回，Code 为 ETapMomentCallbackCode::GetNoticeSuccess（20000）表示获取成功，ETapMomentCallbackCode::GetNoticeFail（20100）表示获取失败。获取成功时，Message 为新消息数量，0 表示没有新消息。

tip

为了方便玩家查看好友动态、游戏公告等，我们建议将 TapTap 动态入口放在显眼的位置，每分钟调用 1 次获取消息通知的接口。

获取消息通知时，如果没有新消息（Message 为 0），那么游戏需要清除界面上的小红点。同样，打开 TapTap 动态页面后，游戏也需要清除界面上的小红点。

显示动态页面

在游戏中显示 TapTap 动态页面，玩家可以查看及发布动态。

#include "TapMoment.h"

UTapMoment::Open();

note

打开动态页面时，请先屏蔽游戏自身的声音，以免干扰动态内的视频声音。

如需要动态能支持横竖屏随设备自动旋转，需要游戏自身能支持横竖屏。

如前所述，打开动态页面后别忘了清除动态页面入口处的小红点。

按以下步骤配置动态页面的背景图：

在开发者中心进入 游戏服务 > 内嵌动态 > 主题配置。
选择深色或浅色导航主题、设置顶栏色值，并上传背景图片。图片需为 JPG 或 PNG 格式；横版尺寸为 2436 × 1125 px，竖版尺寸为 1125 × 2436 px。
点击 申请修改，提交审核。

背景图需要人工审核后才能生效，请预留充足的时间。

动态页面背景图配置入口和申请修改按钮

场景化入口

开发者可以结合游戏场景绘制入口，玩家打开入口跳转到指定的页面。使用前需要在开发者中心后台完成场景化入口配置。

UTapMoment::OpenScene(TEXT("scene_id"));

场景化入口回调格式说明

原生层产生 70000 事件时，UE5 通过 OnMomentResult 透传 Message。消息为 JSON 字符串，应按以下结构解析：

SDK 回调结构

字段名	值类型	required	说明
sceneId	字符串	是	场景化入口 ID
eventType	字符串	是	枚举的事件类型，如 VIEW，FORWARD，VOTE 等
eventPayload	字符串	是	根据类型自定义的 JSON 字符串
timestamp	整数	是	unix 时间戳，ms

事件类型

eventType	eventPayload (未序列化)	说明
`READY`	`{}`	场景化页面已打开
REPOST	`{}`	转发，仅帖子本身
VOTE	`{ isCancel: boolean }`	点赞（含是否取消），仅帖子本身
FOLLOW	`{ isCancel: boolean }`	关注（含是否取消），仅帖子本身
COMMENT	`{}`	评论，仅帖子本身

关闭动态页面

玩家可以在动态页面主动退出，但在特定场景下，游戏可能需要主动关闭动态页面。

比如，玩家排位等待结束，准备进入对局时提示玩家关闭动态页面，玩家确认后关闭，此时调用如下接口：

UTapMoment::CloseWithTitle(TEXT("提示"), TEXT("匹配成功，进入游戏"));

接口中第一个参数为确认弹窗中的标题，第二个参数为确认弹窗中的内容。

用户的选择会通过回调返回：

ETapMomentCallbackCode::CloseCancel（50000），表示玩家点了「取消」，选择不关闭动态页面。
ETapMomentCallbackCode::CloseConfirm（50100），表示玩家点了「确认」，选择关闭动态页面。

如果需要直接关闭动态窗口，不弹出二次确认框，调用如下接口：

UTapMoment::Close();

一键发布

info

这是可选功能，请根据项目需求决定是否在游戏中加入这一功能。

我们推荐游戏让玩家直接在动态页面发布新动态。不过，SDK 也提供了发布图文动态的 API，以支持「一键发动态」等需求。图文动态包括单张或多张图片及相应的文字内容。

// ImageFilePath 是游戏生成或选择的、可供原生 SDK 读取的本地图片路径。
FTapMomentPostData PostData;
PostData.Content = TEXT("分享游戏精彩瞬间");
PostData.ImagePaths.Add(ImageFilePath);

UTapMoment::Publish(PostData);

info

玩家在动态页面可以发布图文动态和视频动态。「一键发布」只支持发布图文动态。

国际化

UTapMoment 没有独立的语言设置 API。核心语言偏好可通过 UE5 集成指南中的 PreferredLanguage 配置；动态页面的实际语言由原生 SDK 和页面决定。当前 iOS 动态页向 H5 提供的是系统首选语言，不能保证仅修改核心语言偏好就切换所有动态文案。

集成前准备​

权限说明​

Android 权限说明​

iOS 权限说明​

SDK 获取​

添加模块依赖​

设置回调​

获取新消息​

显示动态页面​

场景化入口​

场景化入口回调格式说明​

关闭动态页面​

一键发布​

国际化​