Unity 方式

面向 Unity 游戏客户端。游戏侧只通过 C#（ZeusSdkManager）调用；Android 原生能力由随包提供的桥接与 AAR 完成。

当前 Unity 封装对应原生 有 UI 门面 com.zeus.sdk.api.SDK（含登录页 / 绑定页等）。请在 Android 真机 验证；Editor 下会跳过原生调用。

一、接入前准备

项	说明	提供方
Unity 接入包	含 `Scripts/ZeusSdk`、`Plugins/Android`	我方
`appId`	Zeus 后台分配的应用 ID	我方
`package name`	包名	我方
签名	jks，keystore 签名及密码	我方
第三方配置参数	Adjust / AppLovin / Facebook / Firebase / AdMob 等（需按产品裁剪）	我方
google-service.json	Firebase 谷歌服务文件	我方
商品表	Google Play 商品 ID	我方

二、环境要求

项	版本
JDK	11
Gradle	7.5.1
AGP	7.4.2
minSdk	≥ 24
targetSdk / compileSdk	≥ 36

三、接入流程

3.1、导入unitypackage

把接入包导入游戏 Unity 工程（覆盖/合并到 Assets/），结构如下：

text

Assets/
  Plugins/Android/
    AndroidManifest.xml
    LauncherManifest.xml          # 若包内提供
    mainTemplate.gradle           # Maven 依赖（unityLibrary）
    launcherTemplate.gradle
    baseProjectTemplate.gradle    # AGP 7.4.2
    settingsTemplate.gradle
    gradleTemplate.properties
    proguard-unity.txt
    ZeusUnityBridge.java
    google-services.json          # 仅接 Firebase 时需要，包名必须匹配
    libs/
      core-release.aar            # 必选
      data-release.aar            # 必选
      ui-release.aar              # 必选
      sdk-release.aar             # 必选
      plugin-adjust-release.aar   # 可选
      plugin-applovin-release.aar # 可选
      plugin-facebook-release.aar # 可选
      plugin-firebase-release.aar # 可选
    ZeusStrings.androidlib/
      res/values/zeus_strings.xml
  Scripts/ZeusSdk/
    ZeusSdkManager.cs             # 游戏主要调用入口
    ZeusSdkCallback.cs
    ZeusSdkBootstrap.cs
    ZeusSdkConfig.cs
    ZeusSdkModels.cs
    ZeusSdkNativeBridge.cs
    ZeusSdkDemoUI.cs / ZeusSdkLogger.cs / ZeusSdkUiFont.cs   # Demo，正式可删
    Editor/ZeusSdkSetup.cs
  Resources/
    ZeusSdkConfig.asset

包中的 Custom Manifest / Gradle 仅供参考，游戏要按实际配置

3.2、AndroidManifest 配置

在Project Setting > Player > Publishing Setting 下 build 选项开启 Custom Main Manifest，生成自定义的AndroidManifest

3.2.1、Application 指定

Application 必须指定 sdk 的 com.zeus.sdk.ZeusApplication

xml

 <application
        android:name="com.zeus.sdk.ZeusApplication"
        android:allowBackup="true"
        android:supportsRtl="true">
        ...
 </application>

3.2.2、Unity启动页

Unity 启动页。开启 Custom Main Manifest 后不会自动补回，必须手动保留。

xml

<activity
    android:name="com.unity3d.player.UnityPlayerActivity"
    android:theme="@style/UnityThemeSelector"
    android:exported="true">
    <intent-filter>
          <action android:name="android.intent.action.MAIN" />
          <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    <meta-data
          android:name="unityplayer.UnityActivity"
          android:value="true" />
</activity>

3.2.2、可选配置

3.2.2.1、Facebook

xml

<activity
    android:name="com.facebook.CustomTabActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="@string/fb_login_protocol_scheme" />
    </intent-filter>
</activity>

<meta-data
    android:name="com.facebook.sdk.ApplicationId"
    android:value="@string/facebook_app_id" />
<meta-data
    android:name="com.facebook.sdk.ClientToken"
    android:value="@string/facebook_client_token" />

3.2.2.2、AppLovin/Admob

xml

<meta-data
    xmlns:tools="http://schemas.android.com/tools"
    android:name="com.google.android.gms.ads.APPLICATION_ID"
    android:value="@string/admob_app_id"
    tools:replace="android:value" />

填写 ZeusStrings.androidlib 与 ZeusSdkConfig.asset（换成你们的正式值）
首个场景挂 ZeusSdkBootstrap（或菜单 ZeusSDK/Setup Scene）
正式包去掉 Demo UI（可选）
代码：LoadConfig() → Init 成功 → Login / Purchase / 广告等
Android 真机打包验证

3.3、SDK依赖

在 Project Settings > Player > Publishing Settings 开启 Custom Main Gradle Template，生成 mainTemplate.gradle。AAR 不带传递依赖，拷贝哪个 AAR，就要在这里声明对应 Maven 依赖。四个 plugin 彼此独立，不用的不要放 AAR，也不要加依赖。

3.3.1、核心依赖

gradle

    // --- sdk 核心第三方依赖 io / org ---
    implementation("io.insert-koin:koin-core:3.4.3")
    implementation("io.insert-koin:koin-android:3.4.3")
    implementation("io.ktor:ktor-client-auth:2.3.12")
    implementation("io.ktor:ktor-client-cio:2.3.12")
    implementation("io.ktor:ktor-client-content-negotiation:2.3.12")
    implementation("io.ktor:ktor-client-core:2.3.12")
    implementation("io.ktor:ktor-client-logging:2.3.12")
    implementation("io.ktor:ktor-client-okhttp:2.3.12")
    implementation("io.ktor:ktor-serialization-kotlinx-json:2.3.12")
    implementation("org.jetbrains.kotlin:kotlin-stdlib:1.9.22")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.6.4")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.4")
    implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.4.1")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.3")

    // --- sdk 核心第三方依赖 androidx ---
    implementation("androidx.annotation:annotation-experimental:1.4.0")
    implementation("androidx.appcompat:appcompat:1.6.1")
    implementation("androidx.cardview:cardview:1.0.0")
    implementation("androidx.datastore:datastore-preferences:1.0.0")
    implementation("co.touchlab:kermit:1.2.2")

    // --- sdk 核心第三方依赖 billing / ads id ---
    implementation("com.android.billingclient:billing:9.1.0")
    implementation("com.google.android.gms:play-services-ads-identifier:18.0.1")

3.3.2、可选依赖

3.3.2.1、Adjust

gradle

    // --- plugin-adjust（同时放入 plugin-adjust.aar）---
    implementation("com.adjust.sdk:adjust-android:5.6.0")
    implementation("com.android.installreferrer:installreferrer:2.2")

3.3.2.2、AppLovin

接 AppLovin（含 Mintegral / Pangle 中介）时，再开启 Custom Gradle Settings Template，在 settingsTemplate.gradle 的 dependencyResolutionManagement.repositories 中增加：

gradle

maven { url "https://dl-maven-android.mintegral.com/repository/mbridge_android_sdk_oversea" }
maven { url "https://artifact.bytedance.com/repository/pangle" }

gradle

    // --- plugin-applovin（同时放入 plugin-applovin.aar）---
    implementation("androidx.lifecycle:lifecycle-process:2.2.0")
    implementation("com.applovin:applovin-sdk:13.2.0")
    // MAX 中介网络。需同时配置上面的 Mintegral / Pangle 仓库
    implementation("com.applovin.mediation:google-adapter:23.6.0.0")
    implementation("com.applovin.mediation:vungle-adapter:7.4.3.0")
    implementation("com.applovin.mediation:facebook-adapter:6.20.0.0")
    implementation("com.applovin.mediation:mintegral-adapter:17.1.81.0")
    implementation("com.applovin.mediation:bytedance-adapter:8.3.0.4.1")
    implementation("com.applovin.mediation:unityads-adapter:4.16.0.0")
    implementation("com.google.android.gms:play-services-base:18.7.2")
    implementation("com.google.android.ump:user-messaging-platform:2.1.0")

google-adapter 保持 23.6.0.0（对齐 compileSdk 34）。unityads-adapter 不要升到 4.21+，该版本用 Kotlin 2.1 编译，会和当前 Kotlin 1.9 冲突。

3.3.2.3、Facebook

gradle

    // --- plugin-facebook（同时放入 plugin-facebook.aar）---
    implementation("com.facebook.android:facebook-core:18.0.3")
    implementation("com.facebook.android:facebook-login:18.0.3")

3.3.2.4、Firebase

gradle

    // --- plugin-firebase（同时放入 plugin-firebase.aar）---
    // Crashlytics / google-services 插件必须加在 Unity launcher 应用模块，不能加在本 library template。
    implementation(platform("com.google.firebase:firebase-bom:32.8.1"))
    implementation("com.google.firebase:firebase-messaging")
    implementation("com.google.firebase:firebase-analytics")
    implementation("com.google.firebase:firebase-crashlytics")
    implementation("com.google.firebase:firebase-auth")
    implementation("com.google.firebase:firebase-installations")
    implementation("com.google.android.gms:play-services-auth:20.7.0")

3.4、SDK参数配置

SDK 配置文件在Assets/Plugins/Android/ZeusStrings.androidlib/res/values

下，文件名称为 zeus_strings.xml

3.4.1、核心必填配置

xml

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <!-- 必填：API 基址（末尾不要 /） -->
    <string name="api_base_url" translatable="false">https://sdkapi.zeusai.dev</string>
</resources>

缺省键会读成空字符串，不会因此编译失败；但 api_base_url 为空时网络请求会失败。

3.4.2、可选插件配置

按需替换具体的参数内容，若使用不到可以删除插件相关配置

xml

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <!-- ════ Adjust 归因（plugin-adjust） ════ -->
    <string name="adjust_token" translatable="false">imr86...</string>

    <!-- ════ AppLovin MAX 广告（plugin-applovin） ════ -->
    <string name="applovin_max_sdk_key" translatable="false">3l6R_KZPq...</string>
    <string name="applovin_max_app_open_ad" translatable="false">28f2...</string>
    <string name="applovin_max_banner_ad" translatable="false">0fab...</string>
    <string name="applovin_max_inter_ad" translatable="false">9735...</string>
    <string name="applovin_max_reward_ad" translatable="false">624b...7</string>
    <string name="applovin_max_native_ad" translatable="false">5e78...</string>

    <!-- ════ Firebase / Google 登录（plugin-firebase） ════ -->
    <string name="firebase_app_id" translatable="false">1:863071:a648b...</string>
    <string name="google_client_id" translatable="false">8630....</string>

    <!-- ════ Facebook 登录（plugin-facebook） ════ -->
    <string name="facebook_app_id" translatable="false">610127403506312</string>
    <string name="fb_login_protocol_scheme" translatable="false">fb6101...</string>
    <string name="facebook_client_token" translatable="false">ce5a243d...</string>

    <!-- ════ AdMob（AppLovin 中介常用） ════ -->
    <string name="admob_app_id" translatable="false">ca-app-pub-x...</string>

    <!-- ════ 合规链接（GDPR 弹窗） ════ -->
    <string name="privacy_policy_url" translatable="false">https://www...</string>
    <string name="terms_of_service_url" translatable="false">https://www...</string>
</resources>

3.5、SDK 运行时配置

路径必须为：Assets/Resources/ZeusSdkConfig.asset。可通过 Unity 菜单 ZeusSDK/Create Config Asset，或 Create → ZeusSDK → Config 方式创建。其配置项如下：

字段	说明
`dev`	`true` = 测试/沙盒环境，否则正式环境
`appId`	我方分配的 App ID
`lang`	默认游戏语言，如 `en`
`gdpr`	是否走 GDPR/UMP（发欧洲填 `true`）
`loginBrand`	登录页品牌文案
`testSkuId`	仅 Demo 购买按钮用；正式业务请传真实 SKU

3.6、Firebase 插件设置

仅在对接 Firebase 插件 时需要配置

3.6.1、添加Gradle配置

在Project Setting > Player > Publishing Setting 下 build 选项开启 Custom Launcher Gradle Template，生成自定义的launcherTemplate.gradle，在 apply 写入以下配置：

gradle

apply plugin: 'com.google.gms.google-services'
apply plugin: 'com.google.firebase.crashlytics'

在Project Setting > Player > Publishing Setting 下 build 选项开启 Custom Base Gradle Template，生成自定义的baseProjectTemplate.gradle，在 plugins 中补上以下配置：

gradle

plugins {
    id 'com.android.application' version '7.4.2' apply false
    id 'com.android.library' version '7.4.2' apply false
    id 'com.google.gms.google-services' version '4.4.2' apply false
    id 'com.google.firebase.crashlytics' version '2.9.9' apply false
    **BUILD_SCRIPT_DEPS**
}

3.6.2、添加JSON文件

将与包名匹配的 google-services.json 放到 Assets/Plugins/Android/。Crashlytics Gradle 插件只能加在 launcher 应用模块，不能打进 AAR。缺了会在启动时闪退：IllegalStateException: The Crashlytics build ID is missing。

Crashlytics Gradle 插件 3.x 需要 AGP 8.1+。当前 SDK 是 AGP 7.4.2，插件保持 2.9.9，不要升到 3.x。不接 Firebase 时不要拷 plugin-firebase-*.aar，也不要加上述插件和 google-services.json。

四、场景启动

4.1、挂载Unity桥接SDK

在首个场景挂载 ZeusSdkBootstrap，ZeusSdkBootstrap 会创建：

ZeusSdkCallback（GameObject 名必须是此名，原生回调依赖它）
ZeusSdkManager
ZeusSdkLogger / ZeusSdkDemoUI（联调面板）

正式包需要删除 Bootstrap 中创建 Demo UI / Logger 的逻辑，或直接去掉对应脚本。

4.2、桥接接口调用时序

text

场景启动（ZeusSdkBootstrap）
    → ZeusSdkManager.Start（注册回调、广告 Listener）
    → LoadConfig()
    → Init(callback)
    → Init 成功后再 Login / Purchase / 广告 / TrackEvent

注意：不要在 ZeusSdkManager 尚未 Start 之前调业务接口。

4.3、回调说明

所有异步结果经 ZeusSdkCallback.OnZeusCallback 回到主线程，再分发给你传入的 Action<SdkCallbackData>。

csharp

public class SdkCallbackData
{
    public string op;      // 操作名，如 init / login / purchase
    public bool success;   // 等价于 status==200 && code==0
    public int status;
    public int code;
    public string message;
    public string data;    // JSON 字符串，需二次解析
}

OP 含义

`op`	含义
`init`	初始化
`login`	登录
`bindThird`	绑定三方
`switchAccount`	切换账号
`logout`	登出
`purchase`	购买
`processPendingPurchases`	待补单处理
`finishPurchase`	完成消费
`adLoaded`	广告加载完成
`adRewarded`	激励发放（`data` 含 `format` / `label` / `amount`）

五、接口说明

统一入口：

csharp

using ZeusSdk;

var sdk = ZeusSdkManager.Instance;

5.1、配置与初始化

csharp

sdk.LoadConfig();
sdk.Init(result =>
{
    if (!result.success)
    {
        Debug.LogError($"Init fail: {result.message}");
        return;
    }
    Debug.Log("Init OK");
});

Init 使用 ZeusSdkConfig 中的 dev / appId / lang / gdpr / loginBrand，无额外参数。

5.2、账号

方法	参数	说明
`Login(callback)`	`callback` 可选	弹出 SDK 登录流程
`BindThird(callback)`	可选	绑定三方
`SwitchAccount(callback)`	可选	切换账号
`Logout(callback)`	可选	登出
`GetUserId()`	无	返回当前 userId 字符串；未登录可能为空

csharp

sdk.Login(result =>
{
    if (!result.success) return;
    var user = JsonUtility.FromJson<SdkLoginResult>(result.data);
    Debug.Log($"userId={user.userId}, token={user.token}");
});

sdk.BindThird(r => Debug.Log(JsonUtility.ToJson(r)));
sdk.SwitchAccount(r => Debug.Log(JsonUtility.ToJson(r)));
sdk.Logout(r => Debug.Log(JsonUtility.ToJson(r)));
Debug.Log(sdk.GetUserId());

5.3、支付

5.3.1、拉起支付

接口：Purchase

参数	类型	必填	说明
`skuId`	`string`	是	Google Play 商品 ID
`productType`	`PayProductType`	否	默认 `IN_APP`；另有 `SUBSCRIPTION`、`NON_RENEWING_SUBSCRIPTION`
`cpOrderId`	`string`	否	CP 订单号，可空
`callback`	`Action<SdkCallbackData>`	否	异步结果

5.3.2、查询并处理补单

接口：ProcessPendingPurchases

参数	说明
`callback`	查询并处理待补单（一步完成）

启动后或适当时机补单

csharp

sdk.ProcessPendingPurchases(r => Debug.Log(JsonUtility.ToJson(r)));

5.3.3、消费商品

仅适用客户端发奖，服务端发奖不可接入

接口：FinishPurchase

参数	说明
`payResult`	`SdkPayResult`，勿漏字段
`productType`	与购买时一致
`callback`	可选

csharp

sdk.Purchase("your_sku_id", PayProductType.IN_APP, null, result =>
{
    if (!result.success) return;
    var pay = JsonUtility.FromJson<SdkPayResult>(result.data);
    if (pay.clientSendReward)
    {
        sdk.FinishPurchase(pay, PayProductType.IN_APP, r =>
        {
            Debug.Log($"finish: {r.success} {r.message}");
        });
    }
});

5.4、埋点与设备信息

方法	参数	说明
`TrackEvent(eventName, paramsJson)`	`paramsJson` 默认 `"{}"`	事件名 + JSON 对象字符串
`GetSdkInfoJson()`	无	原始 JSON
`GetSdkInfo()`	无	反序列化为 `SdkDeviceInfo`

csharp

sdk.TrackEvent("level_complete", "{\"level\":\"3\"}");

var info = sdk.GetSdkInfo();
Debug.Log($"androidId={info.androidId}, deviceId={info.deviceId}, adjustId={info.adjustId}");

5.5、广告

需继承 plugin-applovin，未放入 plugin-applovin 时，广告接口会静默无效。

方法	参数	说明
`PreloadAd(format)`	`INTERSTITIAL` / `REWARDED` 等	预加载
`IsAdReady(format)`	同上	是否就绪
`ShowInterstitialAd(placement)`	广告位名，默认 `default`	插屏
`ShowRewardedAd(placement)`	同上	激励

csharp

sdk.PreloadAd("REWARDED");
if (sdk.IsAdReady("REWARDED"))
{
    sdk.ShowRewardedAd("level_end");
}

// 激励结果：在 Init 后注册 adRewarded，或由 Demo 已注册
ZeusSdkCallback.Instance.Register(SdkOpType.adRewarded, r =>
{
    var reward = JsonUtility.FromJson<SdkAdRewardData>(r.data);
    Debug.Log($"reward {reward.label} x{reward.amount}");
});

Unity 方式 ​

一、接入前准备 ​

二、环境要求 ​

三、接入流程 ​

3.1、导入unitypackage ​

3.2、AndroidManifest 配置 ​

3.2.1、Application 指定 ​

3.2.2、Unity启动页 ​

3.2.2、可选配置 ​

3.2.2.1、Facebook ​

3.2.2.2、AppLovin/Admob ​

3.3、SDK依赖 ​

3.3.1、核心依赖 ​

3.3.2、可选依赖 ​

3.3.2.1、Adjust ​

3.3.2.2、AppLovin ​

3.3.2.3、Facebook ​

3.3.2.4、Firebase ​

3.4、SDK参数配置 ​

3.4.1、核心必填配置 ​

3.4.2、可选插件配置 ​

3.5、SDK 运行时配置 ​

3.6、Firebase 插件设置 ​

3.6.1、添加Gradle配置 ​

3.6.2、添加JSON文件 ​

四、场景启动 ​

4.1、挂载Unity桥接SDK ​

4.2、桥接接口调用时序 ​

4.3、回调说明 ​

五、接口说明 ​

5.1、配置与初始化 ​

5.2、账号 ​

5.3、支付 ​

5.3.1、拉起支付 ​

5.3.2、查询并处理补单 ​

5.3.3、消费商品 ​

5.4、埋点与设备信息 ​

5.5、广告 ​

Unity 方式

一、接入前准备

二、环境要求

三、接入流程

3.1、导入unitypackage

3.2、AndroidManifest 配置

3.2.1、Application 指定

3.2.2、Unity启动页

3.2.2、可选配置

3.2.2.1、Facebook

3.2.2.2、AppLovin/Admob

3.3、SDK依赖

3.3.1、核心依赖

3.3.2、可选依赖

3.3.2.1、Adjust

3.3.2.2、AppLovin

3.3.2.3、Facebook

3.3.2.4、Firebase

3.4、SDK参数配置

3.4.1、核心必填配置

3.4.2、可选插件配置

3.5、SDK 运行时配置

3.6、Firebase 插件设置

3.6.1、添加Gradle配置

3.6.2、添加JSON文件

四、场景启动

4.1、挂载Unity桥接SDK

4.2、桥接接口调用时序

4.3、回调说明

五、接口说明

5.1、配置与初始化

5.2、账号

5.3、支付

5.3.1、拉起支付

5.3.2、查询并处理补单

5.3.3、消费商品

5.4、埋点与设备信息

5.5、广告