Unity Integration Guide

Everything you need to bring VNGGames to your game: sign-in, in-app purchase, analytics, ads, and player engagement: in one complete reference. Every method spells out its inputs and outputs field by field, and each one is directly linkable so you can jump straight to the call you need.

打造遊戲接入 VNGGames 所需的一切: 登入、應用程式內購買、分析、廣告與玩家互動: 全部整合於一份完整參考中。每個方法都逐一欄位說明其輸入與輸出，且每個方法都可直接連結，讓你能快速跳到所需的呼叫。

打造游戏接入 VNGGames 所需的一切: 登录、应用内购买、分析、广告与玩家互动: 全部整合于一份完整参考中。每个方法都逐一字段说明其输入与输出，且每个方法都可直接链接，让你能快速跳到所需的调用。

• VNGGames SDK package: obtain the latest VNGGames SDK zip file.
• Unity: 2021, 2022, 2023, or 6 (LTS).
• Dependency: com.unity.nuget.newtonsoft-json 3.0.1 (pulled in by the package).
• Build tooling: the iOS export needs macOS + Xcode 26+ (target iOS 13+). The Android export needs JDK 17, the Android SDK (API 23+ / Target 36), NDK 28+, AGP 8.5.1, a signing keystore, and Nexus access for vgsdk-unity + vgsdk-vn. Per-game config files (VGSDKService-Info.plist, pass-services.json, google-services.json) come from the OP Tool.

• VNGGames SDK 套件: 取得最新的 VNGGames SDK zip 檔案。
• Unity: 2021、2022、2023 或 6（LTS）。
• 相依套件: com.unity.nuget.newtonsoft-json 3.0.1（由套件自動引入）。
• 建置工具: iOS 匯出需要 macOS + Xcode 26+（目標 iOS 13+）。Android 匯出需要 JDK 17、Android SDK（API 23+／Target 36）、NDK 28+、AGP 8.5.1、簽署用 keystore，以及可解析 vgsdk-unity + vgsdk-vn 的 Nexus 存取權限。各遊戲的設定檔（VGSDKService-Info.plist、pass-services.json、google-services.json）由 OP Tool 提供。

• VNGGames SDK 包: 获取最新的 VNGGames SDK zip 文件。
• Unity: 2021、2022、2023 或 6（LTS）。
• 依赖包: com.unity.nuget.newtonsoft-json 3.0.1（由包自动引入）。
• 构建工具: iOS 导出需要 macOS + Xcode 26+（目标 iOS 13+）。Android 导出需要 JDK 17、Android SDK（API 23+／Target 36）、NDK 28+、AGP 8.5.1、签名用 keystore，以及可解析 vgsdk-unity + vgsdk-vn 的 Nexus 访问权限。各游戏的配置文件（VGSDKService-Info.plist、pass-services.json、google-services.json）由 OP Tool 提供。

Every third-party library the SDK brings into your build, one tab per build target. The Unity package itself adds only Newtonsoft.Json. The rest arrive with the natives it embeds: the pinned iOS framework set lands in your exported Xcode project, and the vgsdk-service Gradle plugin adds the Android coordinates to your exported Android project.

SDK 帶進你建置中的所有第三方函式庫，每個建置目標一個分頁。Unity 套件本身只加入 Newtonsoft.Json，其餘皆隨它嵌入的原生 SDK 一併帶入：已固定版本的 iOS framework 會出現在你匯出的 Xcode 專案中，而 vgsdk-service Gradle 外掛會將 Android 座標加入你匯出的 Android 專案。

SDK 带进你构建中的所有第三方库，每个构建目标一个标签页。Unity 包本身只加入 Newtonsoft.Json，其余皆随它嵌入的原生 SDK 一并带入：已固定版本的 iOS framework 会出现在你导出的 Xcode 项目中，而 vgsdk-service Gradle 插件会将 Android 坐标加入你导出的 Android 项目。

Add the SDK package to your Unity game, then export a native iOS or Android project. Run the helper scripts from the unzipped bundle folder (where add-vgsdk-package.sh and the export scripts live).

將 SDK 套件加入你的 Unity 遊戲，然後匯出原生 iOS 或 Android 專案。請在解壓後的發佈包目錄（add-vgsdk-package.sh 與匯出指令碼所在處）執行這些輔助指令碼。

将 SDK 包添加到你的 Unity 游戏，然后导出原生 iOS 或 Android 工程。请在解压后的分发包目录（add-vgsdk-package.sh 与导出脚本所在处）运行这些辅助脚本。

Do this one of two ways: the automated script (recommended) or by hand in the Unity Editor:

有兩種方式可完成此步驟: 自動化指令碼（建議）或在 Unity 編輯器中手動操作：

有两种方式可完成此步骤: 自动化脚本（推荐）或在 Unity 编辑器中手动操作：

Importing by hand into a project that already has SDK-dependent scripts can fail to compile on open. The automated script avoids this by materializing the SDK first, so prefer it when you can.

若專案已包含依賴 SDK 的指令碼，直接手動匯入可能在開啟時編譯失敗。自動化指令碼會先放置 SDK 以規避此問題，因此建議盡量優先使用。

若工程已包含依赖 SDK 的脚本，直接手动导入可能在打开时编译失败。自动化脚本会先放置 SDK 以规避此问题，因此建议尽量优先使用。

Set your bundle / application id in Player Settings (or pass --bundle-id) and close the Unity Editor first: Unity can’t open the same project twice. Each exporter drives Unity headlessly and writes its output to an Exported/ folder beside your project.

請先在 Player Settings 設定 bundle / application id（或傳入 --bundle-id），並關閉 Unity 編輯器: Unity 無法同時開啟同一專案。每個匯出器都以無介面方式驅動 Unity，並將輸出寫入專案旁的 Exported/ 目錄。

请先在 Player Settings 设置 bundle / application id（或传入 --bundle-id），并关闭 Unity 编辑器: Unity 无法同时打开同一工程。每个导出器都以无界面方式驱动 Unity，并将输出写入工程旁的 Exported/ 目录。

iOS: Xcode project. Edit export-xcode.config (SCENE, TARGET, BUNDLE_ID), then:

iOS: Xcode 專案。 編輯 export-xcode.config（SCENE、TARGET、BUNDLE_ID），然後：

iOS: Xcode 工程。 编辑 export-xcode.config（SCENE、TARGET、BUNDLE_ID），然后：

Android: Gradle project. Edit export-android.config (SCENE, BUNDLE_ID), export, then configure the project for a current Android Studio (JDK 17 · AGP 8.5.1 · Gradle 8.9 · NDK 28+):

Android: Gradle 專案。 編輯 export-android.config（SCENE、BUNDLE_ID），匯出後再設定專案以符合最新的 Android Studio（JDK 17 · AGP 8.5.1 · Gradle 8.9 · NDK 28+）：

Android: Gradle 工程。 编辑 export-android.config（SCENE、BUNDLE_ID），导出后再配置工程以符合最新的 Android Studio（JDK 17 · AGP 8.5.1 · Gradle 8.9 · NDK 28+）：

Install Android Build Support → Android SDK & NDK Tools + OpenJDK for your editor via Unity Hub. Building the exported project needs JDK 17 and NDK ≥ 28 (16 KB page support, required by Google Play). The config step auto-detects both and stops with exact instructions if either is missing.

請透過 Unity Hub 為你的編輯器安裝 Android Build Support → Android SDK 與 NDK Tools + OpenJDK。建置匯出的專案需要 JDK 17 與 NDK ≥ 28（16 KB 頁支援，Google Play 要求）。設定步驟會自動偵測兩者，缺失時以精確的安裝說明停止。

请通过 Unity Hub 为你的编辑器安装 Android Build Support → Android SDK 与 NDK Tools + OpenJDK。构建导出的工程需要 JDK 17 与 NDK ≥ 28（16 KB 页支持，Google Play 要求）。配置步骤会自动检测两者，缺失时以精确的安装说明停止。

• iOS: open Exported/Xcode-device/Unity-iPhone.xcodeproj, select your team & provisioning profile, enable the declared capabilities (Push, Sign in with Apple) for your App ID in the Apple Developer portal, then build & run (use the Xcode-simulator project for the Simulator).
• Android: open Exported/Android/ in Android Studio, let Gradle sync, then Run on a device/emulator or Build → Build APK / Bundle. Sign store builds with your own release keystore.

• iOS: 用 Xcode 開啟 Exported/Xcode-device/Unity-iPhone.xcodeproj，選擇你的團隊與 provisioning profile，在 Apple Developer 後台為你的 App ID 啟用已宣告的功能（推播、Sign in with Apple），然後建置並執行（模擬器請改用 Xcode-simulator 專案）。
• Android: 用 Android Studio 開啟 Exported/Android/，等待 Gradle 同步，然後在真機／模擬器上 Run 或 Build → Build APK / Bundle。正式發佈請使用你自己的發佈 keystore 簽署。

• iOS: 用 Xcode 打开 Exported/Xcode-device/Unity-iPhone.xcodeproj，选择你的团队与 provisioning profile，在 Apple Developer 后台为你的 App ID 启用已声明的能力（推送、Sign in with Apple），然后构建并运行（模拟器请改用 Xcode-simulator 工程）。
• Android: 用 Android Studio 打开 Exported/Android/，等待 Gradle 同步，然后在真机／模拟器上 Run 或 Build → Build APK / Bundle。正式发布请使用你自己的发布 keystore 签名。

• The export scripts run Unity in batch mode and generate a throwaway build script deleted on exit: they leave no files in your project.
• The SDK’s native wiring runs automatically during export: iOS plists / capabilities via the iOS post-process, Android Gradle files via IPostGenerateGradleAndroidProject.
• Re-running is safe: each export wipes and recreates its own output folder (Exported/Xcode-* or Exported/Android), and importing the SDK is idempotent.
• iOS Simulator: Unity stamps the device SDK onto the project. The exporter auto-normalizes the Simulator project back to iphonesimulator so it builds.
• Keep the helper scripts, the .unitypackage, and VNGGamesSDKDemo/ together at the bundle root: the scripts auto-detect the project and package as siblings.

• 匯出指令碼以批次模式執行 Unity，並產生一個一次性的建置指令碼，退出時刪除: 不會在你專案裡留下檔案。
• SDK 的原生接線會在匯出時自動完成：iOS 的 plist／功能由 iOS 後處理完成，Android 的 Gradle 檔案由 IPostGenerateGradleAndroidProject 完成。
• 可安全重複執行: 每次匯出都會清空並重建自己的輸出目錄（Exported/Xcode-* 或 Exported/Android），且匯入 SDK 是幂等的。
• iOS 模擬器：Unity 會寫入真機 SDK。匯出器會自動修正模擬器專案回 iphonesimulator 以便建置。
• 請將輔助指令碼、.unitypackage 與 VNGGamesSDKDemo/ 一起放在發佈包根目錄: 指令碼會將專案與套件作為同級目錄自動偵測。

• 导出脚本以批处理模式运行 Unity，并生成一个一次性的构建脚本，退出时删除: 不会在你工程里留下文件。
• SDK 的原生接线会在导出时自动完成：iOS 的 plist／能力由 iOS 后处理完成，Android 的 Gradle 文件由 IPostGenerateGradleAndroidProject 完成。
• 可安全重复运行: 每次导出都会清空并重建自己的输出目录（Exported/Xcode-* 或 Exported/Android），且导入 SDK 是幂等的。
• iOS 模拟器：Unity 会写入真机 SDK。导出器会自动修正模拟器工程回 iphonesimulator 以便构建。
• 请将辅助脚本、.unitypackage 与 VNGGamesSDKDemo/ 一起放在分发包根目录: 脚本会将工程与包作为同级目录自动检测。

Sign the player in through the SDK’s channel picker or a specific channel, and delete the signed-in account. Every login callback delivers the signed-in player’s info on success, or an error on cancel/failure. Zero-interaction quick login and VGA account management live in the Quick Authentication section.

透過 SDK 的頻道選擇器或指定頻道讓玩家登入，並可刪除已登入的帳號。每次登入回呼在成功時會傳回已登入玩家的資訊，在取消或失敗時則傳回錯誤。零互動的快速登入與 VGA 帳號管理位於 Quick Authentication 區段。

通过 SDK 的渠道选择器或指定渠道让玩家登录，并可删除已登录的账号。每次登录回调在成功时会返回已登录玩家的信息，在取消或失败时则返回错误。零交互的快速登录与 VGA 账号管理位于 Quick Authentication 部分。

Show the login form

PassSDK.Instance.ShowFormLogin(result =>
{
    result.Match(
        user => { /* Signed in: user.UserId, user.DisplayName, user.SessionId */ },
        error => { /* Handle cancel/failure: error.Code, error.Message */ });
});

Auto login

PassSDK.Instance.AutoLogin(result =>
{
    result.Match(
        user => { /* Same result as ShowFormLogin */ },
        error => { /* Handle failure */ });
});

Direct login to a channel

PassSDK.Instance.DirectLogin(LoginChannel.Google, result =>
{
    result.Match(
        user => { /* signed in */ },
        error => { /* handle failure */ });
});

Recover a Guest account

PassSDK.Instance.DirectLogin(LoginChannel.RecoveryAccount, result =>
{
    result.Match(
        user => { /* recovered, reported on the Guest channel */ },
        error => { /* cancel or failure */ });
});

Log out

PassSDK.Instance.Logout();

Is delete-account enabled

PassSDK.Instance.DeleteAccountEnabled(result =>
{
    result.Match(
        enabled => { /* "true"/"false": whether delete-account is available */ },
        error => { /* error.Code == 404 when unsupported on this platform */ });
});

Delete account

PassSDK.Instance.DeleteAccount(result =>
{
    result.Match(
        ok => { /* account deletion flow completed */ },
        error => { /* error.Code == 404 when unsupported on this platform */ });
});

Zero-interaction sign-in and VGA account management: available only with VGA login. v1 (PassSDK.shared) is the first-generation API: quick login resolves on the login callback. v2 (VGSDKQuickAuth) is the listener-based facade: the listener’s onSuccess delivers the player’s info, onError the failure reason. Manage account opens the VGA account-management screen and applies to accounts signed in with either version.

零互動登入與 VGA 帳號管理: 僅在使用 VGA 登入時可用。v1（PassSDK.shared）為第一代 API：快速登入透過登入回呼回傳結果。v2（VGSDKQuickAuth）為以監聽器為基礎的門面：監聽器的 onSuccess 會傳回玩家資訊，onError 則傳回失敗原因。管理帳號 會開啟 VGA 帳號管理畫面，且適用於以任一版本登入的帳號。

零交互登录与 VGA 账号管理: 仅在 VGA 登录时可用。v1（PassSDK.shared）为第一代 API：快速登录在登录回调上返回结果。v2（VGSDKQuickAuth）为基于监听器的门面：监听器的 onSuccess 返回玩家信息，onError 返回失败原因。管理账号 会打开 VGA 账号管理界面，且适用于以任一版本登录的账号。

Quick login

PassSDK.Instance.QuickLogin(result =>
{
    result.Match(
        user => { /* signed in */ },
        error => { /* error on failure */ });
});

Sign in

VGSDKQuickAuth.ShowLogin(result =>
{
    result.Match(
        user => { /* signed in */ },
        error => { /* failed */ });
});

Play as guest

VGSDKQuickAuth.PlayAsGuest(result =>
{
    result.Match(
        user => { /* signed in as guest */ },
        error => { /* failed */ });
});

Show channel selection

VGSDKQuickAuth.ShowChannelSelection(result =>
{
    result.Match(
        user => { /* signed in */ },
        error => { /* failed */ });
});

Open account management

PassSDK.Instance.ManageAccount(result =>
{
    result.Match(
        manage => { /* manage.Action (AccountBound/AccountSwitched/...), manage.UserInfo */ },
        error => { /* handle failure */ });
});

Validate a signed-in player from your own backend. Every login path in this guide, the channel picker, auto login, direct login and quick login alike, ends with a userID and a sessionID in the game client. Neither proves anything on its own: a client can claim any session. This is the server-to-server check that settles it, so it has no SDK call and no client-side equivalent.

從你自己的後端驗證已登入的玩家。本指南中的每一種登入路徑，無論是頻道選單、Auto login、Direct login 或 Quick login，最後都會在遊戲用戶端留下一組 userID 與 sessionID。這兩個值本身都不能證明任何事：用戶端可以宣稱任何工作階段。這就是用來確認的伺服器對伺服器檢查，因此它沒有 SDK 呼叫，用戶端也沒有等價做法。

从你自己的后端验证已登录的玩家。本指南中的每一种登录路径，无论是渠道选单、Auto login、Direct login 或 Quick login，最后都会在游戏客户端留下一组 userID 与 sessionID。这两个值本身都不能证明任何事：客户端可以声称任何会话。这就是用来确认的服务器对服务器检查，因此它没有 SDK 调用，客户端也没有等价做法。

Check the login session (server-side only)

# Host and secret key come from your server's environment, never from a literal.
TIMESTAMP=$(date +%s)
SIG=$(printf '%s%s%s%s%s' "$SECRET_KEY" "$GAME_ID" "$USER_ID" "$TIMESTAMP" "$SESSION_ID" | md5sum | cut -d' ' -f1)
 
curl -X POST "$HOST/api/login/checkSession" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode "gameID=$GAME_ID" \
  --data-urlencode "userID=$USER_ID" \
  --data-urlencode "sessionID=$SESSION_ID" \
  --data-urlencode "timestamp=$TIMESTAMP" \
  --data-urlencode "sig=$SIG"

Check the login session (server-side only)

# Host and secret key come from your server's environment, never from a literal.
# $HOST is your VN or SEA host, whichever your game was issued.
TIMESTAMP=$(date +%s)
SIG=$(printf '%s%s%s%s%s' "$SECRET_KEY" "$GAME_ID" "$USER_ID" "$SESSION_ID" "$TIMESTAMP" | md5sum | cut -d' ' -f1)
 
curl -X POST "$HOST/api/login/checkSession" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode "gameID=$GAME_ID" \
  --data-urlencode "userID=$USER_ID" \
  --data-urlencode "sessionID=$SESSION_ID" \
  --data-urlencode "timestamp=$TIMESTAMP" \
  --data-urlencode "sig=$SIG"

Query the sellable products, then run a purchase through Google Play Billing / App Store In-App Purchase. Products and purchase status are delivered on listener closures.

查詢可販售的商品，然後透過 Google Play Billing／App Store In-App Purchase 執行購買。商品與購買狀態會透過監聽器閉包傳回。

先查询可售商品，然后通过 Google Play Billing / App Store In-App Purchase 执行购买。商品与购买状态在监听器闭包上返回。

Get products

VGSDKPayment.GetProducts(new[] { "com.game.pack1", "com.game.pack2" }, result =>
{
    result.Match(
        products => { foreach (var p in products.Products) { /* p.ItemId, p.DisplayPrice */ } },
        error => { /* handle failure */ });
});

Purchase

var info = new Dictionary<string, string>
{
    { "userId", userId },
    { "serverId", serverId },
    { "roleId", roleId },
    { "itemId", "com.game.pack1" },
    { "appTransId", appTransId },
};
VGSDKPayment.Purchase(info, result =>
{
    result.Match(
        receipt => { /* purchase completed */ },
        error => { /* error.Code 9009 = user canceled, 9014 = pay failed */ });
});

Check item reward

VGSDKPayment.CheckReward(result =>
{
    result.Match(
        status => { /* "available": a reward is pending. "unavailable": none */ },
        error => { /* error.Code 9007: the check failed */ });
});

Verify reward

var info = new Dictionary<string, string>
{
    { "userId", userId },
    { "appTransId", appTransId },
    { "roleId", roleId },
    { "serverId", serverId },
    { "addInfo", "" },
};
VGSDKPayment.VerifyReward(info, result =>
{
    result.Match(
        status => { /* "success": the reward was granted */ },
        error => { /* error.Code 9007: retry. 9000: do not retry */ });
});

Check device support

if (VGSDKPayment.IsAdvancedCommerceSupported())
{
    // Show the shop that sells declared items
}

Purchase a declared item

var info = new Dictionary<string, string>
{
    { "itemId", "sword-of-dawn" },
    { "serverId", serverId },
    { "amount", "49000" },
    { "currency", "VND" },
    { "genericProductId", "com.game.generic" },
    { "displayName", "Sword of Dawn" },
};
VGSDKPayment.PurchaseAdvancedCommerce(info, result =>
{
    result.Match(
        receipt => { /* purchase completed */ },
        error => { /* this flow reports its own codes */ });
});

One facade for every analytics provider, organised by use case. Configure analytics first, then send ad-hoc custom events or the structured use-case funnels (Conversion Rate = app launch → play, Onboarding = new user → early monetization, Main & Daily Activities, Social & Communities). Providers: AppsFlyer, Firebase, Data Platform, Facebook, CleverTap, ThinkingData. Every call is fire-and-forget. Every event also carries a set of default parameters the SDK fills in automatically: see Analytics default parameters.

Notice: Every event the VNGGames SDK APIs trigger starts with the vgsdk_ prefix and follows the formula vgsdk_{prefix}_{event name}: for example, vgsdk_af_app_open. See Analytics platform prefixes.

涵蓋所有分析供應商的單一門面，依使用情境組織。請先設定分析，然後傳送臨時的自訂事件，或使用結構化的使用情境漏斗（Conversion Rate＝應用程式啟動 → 遊玩、Onboarding＝新使用者 → 早期營利、Main & Daily Activities、Social & Communities）。供應商：AppsFlyer、Firebase、Data Platform、Facebook、CleverTap、ThinkingData。每個呼叫都是 fire-and-forget。每個事件還會帶有一組由 SDK 自動填入的預設參數: 請參閱 分析預設參數。

注意： VNGGames SDK API 觸發的每個事件都以 vgsdk_ 前綴開頭，並遵循 vgsdk_{prefix}_{event name} 公式: 例如 vgsdk_af_app_open。請參閱 分析平台前綴。

面向所有分析提供方的统一门面，按使用场景组织。先配置分析，然后发送临时自定义事件或结构化的使用场景漏斗（Conversion Rate = 应用启动 → 游玩，Onboarding = 新用户 → 早期变现，Main & Daily Activities，Social & Communities）。提供方：AppsFlyer、Firebase、Data Platform、Facebook、CleverTap、ThinkingData。每次调用都是 fire-and-forget。每个事件还会携带一组由 SDK 自动填充的默认参数: 请参阅 分析默认参数。

注意： VNGGames SDK API 触发的每个事件都以 vgsdk_ 前缀开头，并遵循公式 vgsdk_{prefix}_{event name}: 例如 vgsdk_af_app_open。请参阅 分析平台前缀。

Configure analytics

// Bind role context once after login, before sending events
VGSDKAnalytics.MiscConfigAnalytics("role-1", "Hero");

Rules & limits

Send a custom event

// Pick the providers to send to (constructor: provider, prefix; "" = no per-provider prefix)
var facebook = new VGSDKAnalyticsPlatform(VGSDKAnalyticsProvider.Facebook, "");
VGSDKAnalytics.SendCustomEvent(
    "level_up",
    new Dictionary<string, string> { { "level", "5" } },
    new List<VGSDKAnalyticsPlatform> { facebook });

Misc: custom event

// Sends to the SDK's default provider set (no platforms list)
VGSDKAnalytics.MiscCustomEvent("my_event", new Dictionary<string, string> { { "k", "v" } });

1. App open

VGSDKAnalytics.RegAppOpen(new Dictionary<string, string>());

2. Get configuration

VGSDKAnalytics.RegGetConfiguration(new Dictionary<string, string>());

3. Check configuration start

VGSDKAnalytics.RegCheckConfigurationStart(new Dictionary<string, string>());

4. Check configuration end

VGSDKAnalytics.RegCheckConfigurationEnd(new Dictionary<string, string>());

5. CDN download start

VGSDKAnalytics.RegCDNDownloadStart("10MB", new Dictionary<string, string>());