介绍

SDK分为两部分，"插件部分"和"工程部分"

"插件部分"主要用于游戏引擎侧的快速接入，接口为游戏代码直接调用。当前支持Unity，CocosCreator，Laya三种引擎，具体版本下表有列出。插件在下文有下载链接。

"工程部分"是我们适配了各个市场规则后，方便游戏研发快速出包的平台工程，目前支持 Android，iOS两种。需要将游戏引擎编译出来的资源和代码，按照文档填充到工程中，在通过工程打包即可出包。工程由运营同学提供，一般是一个网页链接(落地页)。

下载 SDK 插件包

WARNING

温馨提示：特殊宏__FILE__的建议

• Cocos Creator引擎，代码里面不要用__FILE__这个宏
• 请搜索引擎代码，将__FILE__整体换成 __FILE_NAME__

插件初始化

SDK 是一个 unitypackage 文件，直接将其导入Unity内，import所有内容。

等待编译完之后，Unity的菜单栏会新增一个ZMYSDK的菜单。选择 打开包管理器 导入App版本SDK插件。

在使用接口前，需要先初始化 SDK。

在主 Sence 界面右键->ZMYSDK->启动入口，新建一个启动入口对象，然后在 Inspector 中选择 Set Up 模式为 APP 启动即可。

🎉 这一步走完后，SDK 前期的准备工作完成，下面就可以进行 SDK 接口和功能的对接

Unity 项目可以先使用编辑器接口模拟，在 Unity Editor 中验证广告、支付、登录、存档等业务回调，再进行真机联调。

WARNING

所有 internal 修饰的接口都会进行封装，业务方不要直接调用

所有的接口都可以通过以下方式进行调用：

ZMYSDKManager.I.Sdk.xxxx接口名称

如需在 SDK 管理器初始化完成后执行游戏逻辑，应在 Awake 中订阅 SDKInitOver_Event，并在对象销毁时取消订阅：

using System;
using UnityEngine;
using ZMYSDK;

public class SDKInitListener : MonoBehaviour
{
    private void Awake()
    {
        ZMYSDKManager.SDKInitOver_Event += OnSDKInitOver;
    }

    private void OnDestroy()
    {
        ZMYSDKManager.SDKInitOver_Event -= OnSDKInitOver;
    }

    private void OnSDKInitOver(object sender, EventArgs eventArgs)
    {
        Debug.Log("SDK 初始化完成");
        // 此处执行依赖 SDK 初始化结果的游戏逻辑
    }
}

SDKInitOver_Event 在渠道接口创建完成并调用 OnEnterGame(gameName) 后触发。该事件只通知一次，不会向后注册的监听者补发， 因此不要等到普通 Start 或更晚阶段再订阅。

SDK 整体目录结构如下:

appsdk_dl.js

appsdk_dl.d.ts

使用说明：

1. 将lib-sdk目录下的appsdk_dl.js导入工程，并且勾选为插件，提示文件也在lib-sdk下的appsdk.d.ts。
2. 在进入游戏后调用GameHelper.init()，使用任何GameHelper方法前都必须保证调用完GameHelper.init()，并且是在GameHelper.init()的 callback 回调完后。
3. 目前GameHelper包含：公共功能模块、广告模块、统计模块、内购模块、登陆模块。使用任何功能优先在AppModule、AdsModule、GameStatistics、PayModule、LoginModule这些模块查找，如果没有最后再去AppApi查找。
4. 研发对接完后构建相应的平台资源，然后将资源导入相应的 Android、iOS 工程即可

初始化完成回调示例：

GameHelper.init(() => {
    console.log("SDK 初始化完成");
    // 此处开始调用依赖 SDK 初始化完成的接口
});

WARNING

💡 如果是 CocosCreator 3.7.2 和 3.7.3、3.8.3 版本，请修改 JniCocosEntry.cpp 和 GameActivity.cpp 后再导出游戏资源，修改前最好备份一份源文件

具体路径
C:\ProgramData\cocos\editors\Creator\3.7.2\resources\resources\3d\engine\native\cocos\platform\android\jni\JniCocosEntry.cpp
JniCocosEntry.cpp 修改内容

line.41

JNIEXPORT void JNICALL Java_com_cocos_lib_CocosActivity_onCreateNative(JNIEnv *env, jobject obj, jobject activity) {
    cc::JniHelper::init(env, activity);
}

C:\ProgramData\cocos\editors\Creator\3.7.2\resources\resources\3d\engine\native\external\sources\android-gamesdk\GameActivity\game-activity\include\game-activity\GameActivity.cpp
GameActivity.cpp 修改内容

line.1394

extern "C" JNIEXPORT jlong JNICALL Java_com_google_androidgamesdk_GameActivity_loadNativeCode(
    JNIEnv *env, jobject obj, jobject javaGameActivity, jstring path, jstring funcName,
    jstring internalDataDir, jstring obbDir, jstring externalDataDir,
    jobject jAssetMgr, jbyteArray savedState) {
    GameActivity_register(env);
    jlong nativeCode = loadNativeCode_native(
        env, javaGameActivity, path, funcName, internalDataDir, obbDir,
        externalDataDir, jAssetMgr, savedState);
    return nativeCode;
}

line.1159

{"loadNativeCode", "(Landroid/app/Activity;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Landroid/content/res/AssetManager;[B)J", (void *)loadNativeCode_native},

SDK 整体目录结构如下

appsdk_dl.js

appsdk_dl.d.ts

Laya 导入说明：

WARNING

💡 将 appsdk_dl.js 导入到工程的 bin 目录，将提示文件 appsdk_dl.d.ts 导入到工程的 libs 目录，然后在代码中使用 loadLib 方法加载 appsdk_dl.js。例如

在代码中加载

DANGER

⚡ 注意 plugins/appsdk_dl.js 的导入时机，由于 Laya 的某些状态是在游戏启动后才能获取到，所以为了安全，请确保首场景渲染出来后再调用 plugins/appsdk_dl.js，并且确保此方法只调用一次。调用完后就可以GameHelper.init()实例化，然后可以使用 sdk 功能

使用说明：

1. 将lib-sdk目录下的appsdk_dl.js导入工程，并且勾选为插件，提示文件也在lib-sdk下的appsdk.d.ts。
2. 在进入游戏后调用GameHelper.init()，使用任何GameHelper方法前都必须保证调用完GameHelper.init()，并且是在GameHelper.init()的 callback 回调完后。
3. 目前GameHelper包含：公共功能模块、广告模块、统计模块、内购模块、登陆模块。使用任何功能优先在AppModule、AdsModule、GameStatistics、PayModule、LoginModule这些模块查找，如果没有最后再去AppApi查找。
4. 研发对接完后构建相应的平台资源，然后将资源导入相应的 Android、iOS 工程即可

游戏资源导入工程

获取落地页

确定对接之后，我方会提供落地页地址，其中包括：SDK 工程、可运行样例、对接文档、自动化运行报告。

下载工程模板的压缩包

点击落地页中的下载工程

将游戏资源导入工程

1. 添加 assets 资源到模板工程
   将导出项目中的 /unityLibrary/src/main/assets/下的资源移动到工程模板的/assets下

2. 添加 libs 资源

   • unity-class.jar: 将导出项目中的/unityLibrary/libs/unity-classes.jar复制到模板工程的 libs 目录下
     

   • libmain.so、libunity.so、libil2cpp.so：如果引擎版本 2020+，导出的项目缺少 libil2cpp.so 文件，需要编译该文件。如果引擎版本是 2019，忽略该步骤

编译 libil2cpp.so每次导出项目都需要编译最新的添加:

1. 需要有 gradle 环境
2. 导出的项目根目录执行：gradlew assemblerelease
3. 编译完成后，会自动导出到 unity 项目中的 下的 arm64-v8a 和 armeabi-v7a 目录下

将导出项目中的 unityLibrary/src/main/jniLibs 下的 arm64-v8a 和 armeabi-v7a 目录全部复制到模板工程的 libs

3. 运行工程模板即可

4. 打包使用 AndroidStudio 的 Build->Generate Signed App Bundle/APK

发 GP 市场和华为要提供 Bundle 打包(.aab)，国内其他市场可以直接打 APK 包，在发布市场前会进行二次签名，所以打包时签名使用任意签名均可。

---

符号表导出

每个正式版本都要保存与 APK/AAB 同一次构建生成的符号表，不能使用其他版本重新构建的文件替代。

1. 在 Unity 的 File -> Build Settings（新版本为 File -> Build Profiles）中选择 Android。
2. 将 Create symbols.zip 或 Debug Symbols 设置为 Public；需要文件名和行号时设置为 Debugging，并将输出格式设置为 .zip。
3. 当前流程勾选了 Export Project，Unity 会先把符号输出到导出工程的 unityLibrary/symbols/<ABI>/。执行 gradlew assembleRelease 后，再保存完整的 unityLibrary/symbols 目录；IL2CPP 项目应同时包含 libmain、libunity 和 libil2cpp 的符号。
4. 如果由 Unity 直接构建 APK/AAB，则保存输出目录中与安装包同时生成的 *.symbols.zip。

渠道要求上传 ZIP 时，压缩包根目录应直接是 ABI 目录，例如：

symbols.zip
├── arm64-v8a/
│   ├── libil2cpp.so
│   ├── libmain.so
│   └── libunity.so
└── armeabi-v7a/
    ├── libil2cpp.so
    ├── libmain.so
    └── libunity.so

如果 Release 构建开启了 R8/ProGuard，还要一并保存最终模板工程生成的 mapping.txt。Unity Android 符号说明可参考 Unity 官方文档。

Unity 引擎配置说明：在工程模板，导入开发者的游戏资源(Data、Native)

1. finder 里面，删除工程目录下的的Native和Data文件夹

• 引擎导出的原工程，把Data和Class/Native，两个文件夹放置在上图刚才删除的位置

  • Unity2022引擎版本的 Native对应在：Il2CppOutputProject/Source/il2cppOutput 下的文件

• Xcode 里重新引用Native整个文件夹（先移除，再重加），注：Xcode 里无需对Data进行任何处理。

• 如果游戏引用了第三方插件库，把插件库Libraries从原工程里 copy 到模板工程的Libraries下，模板工程里面重新添加

---

编译工程

配置好的工程正常运行并且 log 筛选【APP-SDK-初始化】，有输出，则配置无误

符号表导出

1. 在最终模板工程的 Xcode Build Settings 中，将 Release 配置的 Debug Information Format 设置为 DWARF with dSYM File。工程内存在 App、UnityFramework 等多个代码 Target 时，需要逐个确认。
2. 选择真机或 Any iOS Device (arm64)，执行 Product -> Archive。不要只使用普通的 Build 产物作为正式包符号表。
3. 在 Xcode 的 Organizer -> Archives 中选中本次发布的 Archive，点击 Show in Finder。
4. 对 .xcarchive 选择 Show Package Contents，保存其中完整的 dSYMs 目录；建议同时归档整个 .xcarchive。

dSYM 的 UUID 必须与最终发布二进制一致。重新编译得到的 dSYM 即使版本号相同也不能替代原文件。详细说明可参考 Apple 官方文档。

• 将assets资源导入 Android 模板工程的assets目录下

• 将libs资源导入 Android 模板工程的libs目录

在编译结束之后，可以通过两种方式获取libs资源。

方式一

方式二

• 修改libs下引擎库 so 文件，文件名不是libcocos2dcpp.so的话，请修改为libcocos2dcpp.so使用

• 然后运行相关工程，即可编译成功

  注意：此时只是能正常编译工程，运行会卡在启动页，请按对接文档完成 SDK 的初始化，方可正常进入游戏

打包使用 AndroidStudio 的 Build->Generate Signed App Bundle/APK

发 GP 市场和华为要提供 Bundle 打包(.aab)，国内其他市场可以直接打 APK 包，在发布市场前会进行二次签名，所以打包时签名使用任意签名均可。

---

符号表导出

Cocos Creator/Laya 的 Android 符号表要在引擎导出的原生工程中生成，并与复制到模板工程的引擎 .so 来自同一次 Release 构建。

1. Android Gradle Plugin 4.1 及以上版本，在引擎导出工程的 App 模块 build.gradle 中为 Release 构建配置：

android {
    buildTypes {
        release {
            ndk {
                debugSymbolLevel 'FULL'
            }
        }
    }
}

只需要函数名时可将 FULL 改为 SYMBOL_TABLE。FULL 还会保留文件名和行号，但文件更大。

2. 执行 gradlew assembleRelease 后，保存 App 模块下的：

build/outputs/native-debug-symbols/release/native-debug-symbols.zip

3. 如果没有生成 ZIP，通常表示导入的是已经被裁剪的预编译 .so。此时应从引擎原生工程的 CMake/NDK 构建中保存 obj/<ABI>/ 下未裁剪的同版本 .so，按 ABI 目录打包，不能从 APK 中提取已裁剪的 .so 代替。
4. 本文前面要求将引擎库重命名为 libcocos2dcpp.so；符号包内对应文件也必须使用相同名称。若模板工程开启了 R8/ProGuard，还要保存最终构建生成的 mapping.txt。

Gradle 的输出规则可参考 Android 官方文档。

• 将assets资源导入 iOS 工程模板的Resources目录下

编译工程

配置好的工程正常运行并且 log 筛选【APP-SDK-初始化】，有输出，则配置无误

---

符号表导出

1. 在最终模板工程的 Xcode Build Settings 中，将 Release 配置的 Debug Information Format 设置为 DWARF with dSYM File。工程内有多个包含原生代码的 Target 时，需要逐个确认。
2. 选择真机或 Any iOS Device (arm64)，执行 Product -> Archive。
3. 在 Organizer -> Archives 中选中本次发布的 Archive，点击 Show in Finder。
4. 对 .xcarchive 选择 Show Package Contents，保存其中完整的 dSYMs 目录；建议同时归档整个 .xcarchive。

必须保留最终模板工程归档产生的 dSYM，不要使用引擎导出工程单独编译的文件代替。dSYM 只能解析 Objective-C/C/C++ 等原生崩溃；如果项目还需要还原压缩后的 JavaScript 堆栈，应另外保存本次构建生成的 Source Map。

QA

Android打包后启动闪退/卡在启动页

• 这个是由于发行 SDK 签名问题导致的

• 解决方案：src - 包名 - GameApp.java 的调试模式打开（）