跳到主要内容
版本：v7

UE

环境要求​

  • Android 5.0，API 21 或更高版本。
  • iOS 国内最低 11.0，海外最低 13.0。
  • 本文以 UE 4.26/4.27 工程为例；SDK 插件内包含部分 UE5 兼容分支，实际支持范围请以交付包说明为准。

接入前准备​

请联系平台同事获取最新的 UE 版 XDSDK 交付包，并将需要的插件目录拷贝到游戏工程的 Plugins/ 目录下。

参考工程中的插件通常包括：

Plugins/
├── AndroidX
├── AntiAddiction
├── TapCommon
├── TapDB
├── TapLogin
├── TapMoment
├── XDADs
├── XDGAccount
├── XDGAnnouncement
├── XDGCommon
├── XDGDouYinCPS
├── XDGMainland
├── XDGOverseas
├── XDGPayment
├── XDGPush
├── XDGReport
├── XDGSharing
└── XDGTapSDK

常见选择方式如下：

  • 必备基础能力：XDGCommon、XDGAccount、XDGPayment、XDGTapSDK、TapDB、AntiAddiction。
  • 地区能力：XDGMainland 与 XDGOverseas 二选一，或按包体分别集成。
  • 按需能力：XDGSharing、XDGPush、XDGAnnouncement、XDGReport、XDADs、XDGDouYinCPS、TapMoment。

项目依赖配置​

引擎模块依赖​

游戏自身模块的 Build.cs 里，至少需要加入 XDSDK 常用依赖。可参考交付 Demo 的写法：

PublicDependencyModuleNames.AddRange(new string[]
{
    "Core",
    "CoreUObject",
    "Engine",
});

PrivateDependencyModuleNames.AddRange(new string[]
{
    "Json",
    "JsonUtilities",
    "Slate",
    "SlateCore",
    "UMG",
    "WebBrowser",
    "XDGCommon",
    "XDGAccount",
    "XDGPayment",
    "XDGTapSDK",
    "TapDB",
    "AntiAddiction",

    // 按需添加
    "XDGMainland",
    "XDGOverseas",
    "XDGSharing",
    "XDGPush",
    "XDGAnnouncement",
    "XDGReport",
    "TapMoment",
    "XDADs",
});

加载 UPL 配置​

如果游戏需要在 Android/iOS 打包时注入额外配置文件、权限或 plist 字段，建议像参考工程一样在 Build.cs 中挂载自己的 UPL 文件：

if (Target.Platform == UnrealTargetPlatform.Android)
{
    PrivateDependencyModuleNames.AddRange(
        new string[]
        {
            "Launch",
            "AndroidPermission",
        }
    );

    AdditionalPropertiesForReceipt.Add(
        "AndroidPlugin",
        Path.Combine(ModuleDirectory, "YourProject_Android_UPL.xml")
    );
}

if (Target.Platform == UnrealTargetPlatform.IOS)
{
    AdditionalPropertiesForReceipt.Add(
        "IOSPlugin",
        Path.Combine(ModuleDirectory, "YourProject_iOS_UPL.xml")
    );
}

配置 XDGConfig​

UE 版 XDSDK 使用 XDGConfig 作为统一配置入口。推荐两种方式：

  1. 直接维护 Config/DefaultXDGConfig.ini。
  2. 在编辑器的 Project Settings > Plugins > XDGConfig 中填写，保存后写入同名 ini。

推荐配置文件路径​

Config/DefaultXDGConfig.ini

最小配置示例​

[/Script/XDGCommon.XDGConfig]
client_id=your_xd_client_id
region_type=Global
app_id=your_xd_app_id
game_name=Your Game

tapsdk__client_id=your_tap_client_id
tapsdk__client_token=your_tap_client_token
tapsdk__db_config__enable=True
tapsdk__db_config__channel=official

常见可选项​

  • 第三方登录：facebook__app_id、google__CLIENT_ID、google__CLIENT_ID_FOR_ANDROID、google__CLIENT_ID_FOR_PC、line__channel_id、twitter__consumer_key。
  • iOS 分享 / 登录回跳：wechat__universal_link、qq__universal_link、weibo__universal_link、xhs__universal_link、tiktok__universal_link、kuaishou__universal_link。
  • 推送：aliyun__push_key_ios、aliyun__push_secret_ios、aliyun__push_key_android、aliyun__push_secret_android。
  • PC：bSteamSDKLoginEnable、eos__enabled、eos__product_id、eos__client_id、eos__client_secret。
提示

移动端打包时，SDK 会在构建阶段根据 DefaultXDGConfig.ini 生成 XDConfig.json 并拷贝进包体，通常不需要再手工维护单独的 XDConfig.json。

Android 平台配置​

拷贝额外文件​

若使用 Firebase、国内推送或其他第三方能力，通常需要在 Android 打包阶段拷贝额外文件。推荐在自定义 UPL 中使用如下结构：

<resourceCopies>
    <copyDir src="$S(PluginDir)/Android/app/" dst="$S(BuildDir)/gradle/app/"/>
    <copyDir src="$S(PluginDir)/Android/assets/" dst="$S(BuildDir)/assets/"/>
</resourceCopies>

常见文件包括：

  • google-services.json
  • agconnect-services.json
  • supplierconfig.json

Manifest 相关配置​

如需自己补充 Android 11 包可见性、分享 FileProvider、附加权限等，建议在自定义 UPL 的 <androidManifestUpdates> 中统一处理。

如果启用了海外网页支付，XDGPayment 插件会在打包时自动向 AndroidManifest.xml 注入 SchemeCCTActivity，并基于 client_id 自动生成 xd{小写 client_id} 的回跳 Scheme，因此不要移除该插件的默认 UPL。

常见权限与查询项​

参考工程中常见的 Android 侧补充内容包括：

  • android.permission.ACCESS_NETWORK_STATE
  • android.permission.POST_NOTIFICATIONS
  • android.permission.READ_EXTERNAL_STORAGE
  • android.permission.READ_MEDIA_IMAGE
  • android.permission.READ_MEDIA_VIDEO
  • com.taptap、com.taptap.global、com.tencent.mm、com.sina.weibo 等包可见性查询

iOS 平台配置​

拷贝额外文件​

若使用 Firebase 或其他 iOS 第三方能力，可在自定义 UPL 中拷贝额外文件到构建目录：

<init>
    <copyDir src="$S(PluginDir)/iOS/app/" dst="$S(BuildDir)/"/>
</init>

常见文件包括：

  • GoogleService-Info.plist

Info.plist 配置​

XDSDK 涉及的 iOS 配置通常通过 UPL 注入到 info.plist：

  • 隐私权限文案：NSCameraUsageDescription、NSMicrophoneUsageDescription、NSPhotoLibraryUsageDescription、NSUserTrackingUsageDescription
  • 回跳 Scheme：TapTap、微信、QQ、微博、Facebook、Google、Line、TikTok、小红书、快手等
  • 白名单：LSApplicationQueriesSchemes

可使用如下模板：

<iosPListUpdates>
    <addElements tag="dict" once="true">
        <!-- 权限说明 -->
        <key>NSCameraUsageDescription</key>
        <string>请允许应用使用相机</string>

        <!-- 第三方回跳 Scheme -->
        <key>CFBundleURLTypes</key>
        <array>
            <!-- 按项目实际参数填写 -->
        </array>

        <!-- 第三方白名单 -->
        <key>LSApplicationQueriesSchemes</key>
        <array>
            <string>tapsdk</string>
            <string>tapiosdk</string>
            <string>taptap</string>
            <string>weixin</string>
            <string>mqq</string>
            <string>sinaweibo</string>
        </array>
    </addElements>
</iosPListUpdates>

Capabilities / DefaultEngine.ini​

如果启用了苹果登录、推送、Game Center、Associated Domains 或 Keychain Sharing，请在 DefaultEngine.ini 中增加对应配置：

[/Script/IOSRuntimeSettings.IOSRuntimeSettings]
bEnableSignInWithAppleSupport=True
bEnableRemoteNotificationsSupport=True
bEnableGameCenterSupport=True
iOSAssociatedDomains=applinks:your.domain
iOSKeychainAccessGroups=$(AppIdentifierPrefix)com.google.GIDSignIn,$(AppIdentifierPrefix)com.your.game

PC 平台配置​

Steam 登录 / 支付​

如需启用 Steam 账号登录或 Steam 支付：

  • 启用 OnlineSubsystemSteam 插件。
  • 在 DefaultXDGConfig.ini 中设置 bSteamSDKLoginEnable=True。

Epic 内购​

如需启用 Epic 内购，需要在 DefaultXDGConfig.ini 中补充 EOS 相关参数：

eos__enabled=True
eos__product_id="your_product_id"
eos__client_id="your_client_id"
eos__client_secret="your_client_secret"

常见问题​

需要手动放置 XDConfig.json 吗？​

通常不需要。UE 版 SDK 会在移动端构建阶段由 DefaultXDGConfig.ini 生成 XDConfig.json 并自动拷贝到目标包体。

Firebase 配置文件放在哪里？​

  • Android：通过 UPL 拷贝 google-services.json 到 $S(BuildDir)/gradle/app/。
  • iOS：通过 UPL 拷贝 GoogleService-Info.plist 到 $S(BuildDir)/。

海外网页支付回跳 Scheme 如何配置？​

XDGPayment 插件会根据 client_id 自动生成 xd{小写 client_id} 的 Scheme 并注入 SchemeCCTActivity。若游戏自定义了 Manifest，请确保不要覆盖或移除这部分配置。