Windows Upgrade Guide

See what changed between your current SDK version and the latest, with the exact steps to migrate.

查看你目前的 SDK 版本與最新版本之間的變更，以及確切的遷移步驟。

查看你当前的 SDK 版本与最新版本之间的变更，以及确切的迁移步骤。

1.2.0 replaces the two-case VNGGamesPlatform::LoginType with VGA::LoginType, which covers all eight VGA channels including the new Play Now channel. The two shared raw values are unchanged, so EmailPhone stays 0 and Zing stays 1.

1.2.0 以 VGA::LoginType 取代僅有兩個項目的 VNGGamesPlatform::LoginType，涵蓋全部八種 VGA 渠道，包含新的 Play Now 渠道。兩個共通的原始值維持不變，EmailPhone 仍為 0，Zing 仍為 1。

1.2.0 以 VGA::LoginType 取代仅有两个项的 VNGGamesPlatform::LoginType，涵盖全部八种 VGA 渠道，包含新的 Play Now 渠道。两个共通的原始值保持不变，EmailPhone 仍为 0，Zing 仍为 1。

↪ This form is replaced in 1.7.0, see: VGA::LoginType renamed to SdkLoginChannel

↪ 此寫法於 1.7.0 已被取代，請參見： VGA::LoginType 更名為 SdkLoginChannel

↪ 此写法于 1.7.0 已被取代，请参见： VGA::LoginType 更名为 SdkLoginChannel

1. Replace every VNGGamesPlatform::LoginType value you pass to DirectLogin with the matching VGA::LoginType value.
2. Pass the channel by const reference, which is what the new export expects.

1. 將傳入 DirectLogin 的每個 VNGGamesPlatform::LoginType 值改為對應的 VGA::LoginType 值。
2. 以 const 參考方式傳入渠道，這是新匯出項所預期的形式。

1. 将传入 DirectLogin 的每个 VNGGamesPlatform::LoginType 值改为对应的 VGA::LoginType 值。
2. 以 const 引用方式传入渠道，这是新导出项所预期的形式。

See the usage and full signature in the Integration guide:

請在整合指南中查看用法與完整簽名：

请在集成指南中查看用法与完整签名：

A project that includes the bundled header stops compiling, because VNGGamesPlatform::LoginType no longer exists. A project that resolves the export itself still builds but passes the channel in the old shape, so login fails.

引入隨附標頭檔的專案將無法編譯，因為 VNGGamesPlatform::LoginType 已不存在。自行解析匯出項的專案仍可建置，但會以舊形式傳入渠道，導致登入失敗。

引入随附头文件的工程将无法编译，因为 VNGGamesPlatform::LoginType 已不存在。自行解析导出项的工程仍可构建，但会以旧形式传入渠道，导致登录失败。

1.2.0 adds a way to read the running SDK version, which is what support tickets and crash reports need in order to tell releases apart. In this release it returns the version string directly.

1.2.0 新增讀取目前 SDK 版本的方式，這是客服工單與當機回報用來區分版本所需的資訊。在此版本中，它會直接回傳版本字串。

1.2.0 新增读取当前 SDK 版本的方式，这是客服工单与崩溃报告用来区分版本所需的信息。在此版本中，它会直接返回版本字符串。

Call GetSdkVersion and include the returned version string in your support and crash reporting.

呼叫 GetSdkVersion，並將回傳的版本字串附在客服與當機回報中。

调用 GetSdkVersion，并将返回的版本字符串附在客服与崩溃报告中。

See the usage and full signature in the Integration guide:

請在整合指南中查看用法與完整簽名：

请在集成指南中查看用法与完整签名：

This addition is opt-in. Nothing breaks if you skip it: your existing integration keeps working, you just don’t gain this capability.

此新增功能為選用。略過不會造成任何問題：你現有的整合仍可正常運作，只是不會獲得此功能。

此新增功能为可选。跳过不会造成任何问题：你现有的集成仍可正常运行，只是不会获得此功能。

From 1.4.0 the SDK config is packaged inside VNGGamesSDK.dll instead of being read from a file you ship and point at, so the configPath parameter is gone and error 101 ConfigFileNotFound no longer occurs.

自 1.4.0 起，SDK 設定改為封裝在 VNGGamesSDK.dll 內，不再從你自行發佈並指定路徑的檔案讀取，因此 configPath 參數已移除，錯誤碼 101 ConfigFileNotFound 也不會再出現。

自 1.4.0 起，SDK 配置改为封装在 VNGGamesSDK.dll 内，不再从你自行发布并指定路径的文件读取，因此 configPath 参数已移除，错误码 101 ConfigFileNotFound 也不会再出现。

↪ Also changed in 1.8.0, see: New Ctx entry points carry your own context to the callback

↪ 於 1.8.0 亦有變更，請參見： 新增 Ctx 進入點，可將你自己的 context 帶入回呼

↪ 于 1.8.0 亦有变更，请参见： 新增 Ctx 入口，可将你自己的 context 带入回调

1. Remove the config-path argument from your InitializeSdk call and pass only the callback.
2. Stop shipping the standalone SDK config file with your game.

1. 從 InitializeSdk 呼叫中移除設定檔路徑參數，只傳入回呼。
2. 不要再隨遊戲發佈獨立的 SDK 設定檔。

1. 从 InitializeSdk 调用中移除配置文件路径参数，只传入回调。
2. 不要再随游戏发布独立的 SDK 配置文件。

See the usage and full signature in the Integration guide:

請在整合指南中查看用法與完整簽名：

请在集成指南中查看用法与完整签名：

A project that includes the bundled header stops compiling on the extra argument. A project that resolves the export itself still builds, but the DLL reads your callback pointer as the first parameter and initialization never completes.

引入隨附標頭檔的專案會因多餘參數而無法編譯。自行解析匯出項的專案仍可建置，但 DLL 會把你的回呼指標當成第一個參數讀取，初始化將永遠無法完成。

引入随附头文件的工程会因多余参数而无法编译。自行解析导出项的工程仍可构建，但 DLL 会把你的回调指针当成第一个参数读取，初始化将永远无法完成。

1.5.0 moves GetSdkVersion onto the same asynchronous result-callback envelope every other export uses, so it no longer returns a string pointer whose lifetime the game had to reason about.

1.5.0 將 GetSdkVersion 改為採用與其他匯出項相同的非同步結果回呼封套，因此不再回傳需要遊戲自行判斷生命週期的字串指標。

1.5.0 将 GetSdkVersion 改为采用与其他导出项相同的异步结果回调封套，因此不再返回需要游戏自行判断生命周期的字符串指针。

1. Pass a ResultCallback to GetSdkVersion instead of reading its return value.
2. Read the version from the result JSON your callback receives.

1. 改為將 ResultCallback 傳入 GetSdkVersion，而非讀取其回傳值。
2. 從回呼收到的結果 JSON 中讀取版本。

1. 改为将 ResultCallback 传入 GetSdkVersion，而非读取其返回值。
2. 从回调收到的结果 JSON 中读取版本。

See the usage and full signature in the Integration guide:

請在整合指南中查看用法與完整簽名：

请在集成指南中查看用法与完整签名：

A project that includes the bundled header stops compiling, because the export no longer returns a value. A project that resolves the export itself still builds but reads a meaningless pointer as the version.

引入隨附標頭檔的專案將無法編譯，因為該匯出項已不再有回傳值。自行解析匯出項的專案仍可建置，但會把一個無意義的指標當成版本讀取。

引入随附头文件的工程将无法编译，因为该导出项已不再有返回值。自行解析导出项的工程仍可构建，但会把一个无意义的指针当成版本读取。

1.5.0 lets the game read the country the SDK resolved for the current user from the publishing market, so region-specific content and pricing can be selected without a call of your own.

1.5.0 讓遊戲可讀取 SDK 依發行市場為目前使用者判定的國家，因此不需自行呼叫即可選擇地區專屬內容與定價。

1.5.0 让游戏可读取 SDK 依发行市场为当前用户判定的国家，因此不需自行调用即可选择地区专属内容与定价。

↪ Also changed in 1.8.0, see: New Ctx entry points carry your own context to the callback

↪ 於 1.8.0 亦有變更，請參見： 新增 Ctx 進入點，可將你自己的 context 帶入回呼

↪ 于 1.8.0 亦有变更，请参见： 新增 Ctx 入口，可将你自己的 context 带入回调

Call GetCachedCountryCode after initialization and read the country code from the result JSON.

在初始化之後呼叫 GetCachedCountryCode，並從結果 JSON 讀取國家代碼。

在初始化之后调用 GetCachedCountryCode，并从结果 JSON 读取国家代码。

See the usage and full signature in the Integration guide:

請在整合指南中查看用法與完整簽名：

请在集成指南中查看用法与完整签名：

This addition is opt-in. Nothing breaks if you skip it: your existing integration keeps working, you just don’t gain this capability.

此新增功能為選用。略過不會造成任何問題：你現有的整合仍可正常運作，只是不會獲得此功能。

此新增功能为可选。跳过不会造成任何问题：你现有的集成仍可正常运行，只是不会获得此功能。

1.6.0 adds the Customer Support portal as a first-class SDK screen. The game passes the player and role details it already holds, and the SDK opens the portal with that context attached, plus a new 7xx error band.

1.6.0 將客服入口納入 SDK 的正式畫面。遊戲傳入既有的玩家與角色資料，SDK 便會以該情境開啟入口，並新增 7xx 錯誤碼區段。

1.6.0 将客服入口纳入 SDK 的正式画面。游戏传入既有的玩家与角色资料，SDK 便会以该上下文打开入口，并新增 7xx 错误码区段。

↪ This form is replaced in 1.7.2, see: ShowCustomerSupport requires a login channel

↪ 此寫法於 1.7.2 已被取代，請參見： ShowCustomerSupport 需傳入登入渠道

↪ 此写法于 1.7.2 已被取代，请参见： ShowCustomerSupport 需传入登录渠道

Call ShowCustomerSupport with the player’s user id, server id, role name, level, guild, and message to open the support portal.

以玩家的使用者 ID、伺服器 ID、角色名稱、等級、公會與訊息呼叫 ShowCustomerSupport，即可開啟客服入口。

以玩家的用户 ID、服务器 ID、角色名称、等级、公会与消息调用 ShowCustomerSupport，即可打开客服入口。

See the usage and full signature in the Integration guide:

請在整合指南中查看用法與完整簽名：

请在集成指南中查看用法与完整签名：

This addition is opt-in. Nothing breaks if you skip it: your existing integration keeps working, you just don’t gain this capability.

此新增功能為選用。略過不會造成任何問題：你現有的整合仍可正常運作，只是不會獲得此功能。

此新增功能为可选。跳过不会造成任何问题：你现有的集成仍可正常运行，只是不会获得此功能。

1.7.0 adds the Legacy login platform alongside VGA, so the channel enum is no longer VGA-specific and moves out of the VGA namespace under the name SdkLoginChannel. All eight raw values are unchanged.

1.7.0 在 VGA 之外加入 Legacy 登入平台，因此渠道列舉不再專屬於 VGA，並以 SdkLoginChannel 之名移出 VGA 命名空間。全部八個原始值維持不變。

1.7.0 在 VGA 之外加入 Legacy 登录平台，因此渠道枚举不再专属于 VGA，并以 SdkLoginChannel 之名移出 VGA 命名空间。全部八个原始值保持不变。

↪ This form is replaced in 1.7.2, see: DirectLogin takes the channel by value, not by reference

↪ 此寫法於 1.7.2 已被取代，請參見： DirectLogin 改為以值傳入渠道，而非參考

↪ 此写法于 1.7.2 已被取代，请参见： DirectLogin 改为以值传入渠道，而非引用

1. Rename every VGA::LoginType reference in your code to SdkLoginChannel, keeping the same value names.
2. Rename your DirectLoginErrorCode::UnsupportedLoginType reference to UnsupportedSdkLoginChannel, which keeps error code 204.

1. 將程式碼中每個 VGA::LoginType 參照改名為 SdkLoginChannel，值的名稱維持不變。
2. 將 DirectLoginErrorCode::UnsupportedLoginType 參照改名為 UnsupportedSdkLoginChannel，錯誤碼仍為 204。

1. 将代码中每个 VGA::LoginType 引用改名为 SdkLoginChannel，值的名称保持不变。
2. 将 DirectLoginErrorCode::UnsupportedLoginType 引用改名为 UnsupportedSdkLoginChannel，错误码仍为 204。

See the usage and full signature in the Integration guide:

請在整合指南中查看用法與完整簽名：

请在集成指南中查看用法与完整签名：

A project that includes the bundled header stops compiling on every VGA::LoginType reference. A project that resolves the export itself is unaffected at build time, because the underlying values did not change.

引入隨附標頭檔的專案會在每個 VGA::LoginType 參照處無法編譯。自行解析匯出項的專案在建置階段不受影響，因為底層值並未改變。

引入随附头文件的工程会在每个 VGA::LoginType 引用处无法编译。自行解析导出项的工程在构建阶段不受影响，因为底层值并未改变。

1.7.2 changes the Direct Login entry point to take SdkLoginChannel by value. A const reference is a pointer at the DLL boundary, so this changes what the exported function actually receives from the caller.

1.7.2 將 Direct Login 進入點改為以值傳入 SdkLoginChannel。在 DLL 邊界上，const 參考實際上是指標，因此匯出函式從呼叫端收到的內容也隨之改變。

1.7.2 将 Direct Login 入口改为以值传入 SdkLoginChannel。在 DLL 边界上，const 引用实际上是指针，因此导出函数从调用方收到的内容也随之改变。

↪ Also changed in 1.8.0, see: New Ctx entry points carry your own context to the callback

↪ 於 1.8.0 亦有變更，請參見： 新增 Ctx 進入點，可將你自己的 context 帶入回呼

↪ 于 1.8.0 亦有变更，请参见： 新增 Ctx 入口，可将你自己的 context 带入回调

1. Update your DirectLogin function-pointer type to take SdkLoginChannel by value.
2. Re-test each Direct Login channel your game offers.

1. 將你的 DirectLogin 函式指標型別改為以值傳入 SdkLoginChannel。
2. 重新測試遊戲提供的每個 Direct Login 渠道。

1. 将你的 DirectLogin 函数指针类型改为以值传入 SdkLoginChannel。
2. 重新测试游戏提供的每个 Direct Login 渠道。

See the usage and full signature in the Integration guide:

請在整合指南中查看用法與完整簽名：

请在集成指南中查看用法与完整签名：

A project that keeps the old function-pointer type still builds, but the DLL reads the pointer as a channel number, so Direct Login fails with 204 UnsupportedLoginChannel or opens the wrong channel.

沿用舊函式指標型別的專案仍可建置，但 DLL 會把指標當成渠道編號讀取，導致 Direct Login 以 204 UnsupportedLoginChannel 失敗，或開啟錯誤的渠道。

沿用旧函数指针类型的工程仍可构建，但 DLL 会把指针当成渠道编号读取，导致 Direct Login 以 204 UnsupportedLoginChannel 失败，或打开错误的渠道。

1.7.2 adds a required loginChannel parameter right after userId, so the support portal knows which channel the player signed in with instead of inferring it.

1.7.2 在 userId 之後新增必填的 loginChannel 參數，讓客服入口直接得知玩家的登入渠道，而非自行推斷。

1.7.2 在 userId 之后新增必填的 loginChannel 参数，让客服入口直接得知玩家的登录渠道，而非自行推断。

↪ Also changed in 1.8.0, see: New Ctx entry points carry your own context to the callback

↪ 於 1.8.0 亦有變更，請參見： 新增 Ctx 進入點，可將你自己的 context 帶入回呼

↪ 于 1.8.0 亦有变更，请参见： 新增 Ctx 入口，可将你自己的 context 带入回调

1. Insert the player’s SdkLoginChannel as the second argument of every ShowCustomerSupport call.
2. Re-test the support portal and confirm the ticket carries the right account.

1. 在每個 ShowCustomerSupport 呼叫的第二個參數插入玩家的 SdkLoginChannel。
2. 重新測試客服入口，確認工單帶有正確的帳號。

1. 在每个 ShowCustomerSupport 调用的第二个参数插入玩家的 SdkLoginChannel。
2. 重新测试客服入口，确认工单带有正确的账号。

See the usage and full signature in the Integration guide:

請在整合指南中查看用法與完整簽名：

请在集成指南中查看用法与完整签名：

A call that still passes seven arguments shifts every value after userId by one position, so the portal opens with the server id read as a login channel and the player’s details are wrong or missing.

仍傳入七個參數的呼叫會使 userId 之後的每個值都位移一格，導致入口把伺服器 ID 當成登入渠道讀取，玩家資料因而錯誤或缺漏。

仍传入七个参数的调用会使 userId 之后的每个值都位移一格，导致入口把服务器 ID 当成登录渠道读取，玩家资料因而错误或缺失。

1.8.0 adds a ResultCallbackCtx form of every asynchronous export, so a result can be routed back to the object that started it instead of a global handler. Use the Ctx form for all new code: every API added after 1.8.0 is context-only, and the plain ResultCallback twins are deprecated.

1.8.0 為每個非同步匯出項新增 ResultCallbackCtx 形式，讓結果可回送到發起呼叫的物件，而不必經由全域處理器。所有新程式碼都請使用 Ctx 形式：1.8.0 之後新增的 API 一律只提供 context 形式，原本的 ResultCallback 版本已標記為棄用。

1.8.0 为每个异步导出项新增 ResultCallbackCtx 形式，让结果可回送到发起调用的对象，而不必经由全局处理器。所有新代码都请使用 Ctx 形式：1.8.0 之后新增的 API 一律只提供 context 形式，原本的 ResultCallback 版本已标记为弃用。

↪ This form is replaced in 1.9.0, see: Bundled header symbols moved into the VNGGamesSDK namespace

↪ 此寫法於 1.9.0 已被取代，請參見： 隨附標頭檔的符號移入 VNGGamesSDK 命名空間

↪ 此写法于 1.9.0 已被取代，请参见： 随附头文件的符号移入 VNGGamesSDK 命名空间

Switch each call to the replacement shown in the table above.

將每個呼叫改為上表所示的替代項目。

将每个调用改为上表所示的替代项。

ResultCallback and its plain entry points still work today, but they are deprecated and scheduled for removal. Your build breaks once a later release deletes them, and nothing added after 1.8.0 is reachable.

ResultCallback 與原本的進入點目前仍可運作，但已標記為棄用並列入移除計畫。待日後版本刪除後，你的建置將失敗，且無法使用 1.8.0 之後新增的任何功能。

ResultCallback 与原本的入口目前仍可运行，但已标记为弃用并列入移除计划。待日后版本删除后，你的构建将失败，且无法使用 1.8.0 之后新增的任何功能。

1.9.0 ships the bundled vnggamessdk.h with everything inside namespace VNGGamesSDK, and turns the error-code enums into scoped enums whose members drop their redundant prefixes. Every numeric error value is unchanged, so a game that switches on raw integers is not affected. Three codes stop occurring, namely 106, 206, and 701.

1.9.0 發佈的 vnggamessdk.h 將所有內容置於 namespace VNGGamesSDK 之下，並將錯誤碼列舉改為具範圍的列舉，成員名稱去除冗餘前綴。所有數值錯誤碼維持不變，因此以原始整數判斷的遊戲不受影響。其中 106、206、701 三個錯誤碼將不再出現。

1.9.0 发布的 vnggamessdk.h 将所有内容置于 namespace VNGGamesSDK 之下，并将错误码枚举改为限定作用域的枚举，成员名称去除冗余前缀。所有数值错误码保持不变，因此以原始整数判断的游戏不受影响。其中 106、206、701 三个错误码将不再出现。

Switch each call to the replacement shown in the table above.

將每個呼叫改為上表所示的替代項目。

将每个调用改为上表所示的替代项。

A project that includes the bundled header stops compiling on every unqualified SDK type and error constant. A project that resolves the exports itself is unaffected, because the exported function names and the numeric error values did not change.

引入隨附標頭檔的專案會在每個未加命名空間限定的 SDK 型別與錯誤常數處無法編譯。自行解析匯出項的專案不受影響，因為匯出函式名稱與數值錯誤碼皆未改變。

引入随附头文件的工程会在每个未加命名空间限定的 SDK 类型与错误常量处无法编译。自行解析导出项的工程不受影响，因为导出函数名称与数值错误码均未改变。

1.9.0 turns the bundled vnggamessdk.h into a loader you can use directly. Constructing VNGGamesSDK::SDK with your loaded module resolves every export once and exposes them as member functions, replacing a hand-written GetProcAddress block per API. Writing your own loader is still supported.

1.9.0 將隨附的 vnggamessdk.h 變成可直接使用的載入器。以你載入的模組建構 VNGGamesSDK::SDK，即會一次解析所有匯出項並以成員函式提供，取代逐一手寫的 GetProcAddress 區塊。自行實作載入器仍然受支援。

1.9.0 将随附的 vnggamessdk.h 变成可直接使用的加载器。以你加载的模块构造 VNGGamesSDK::SDK，即会一次解析所有导出项并以成员函数提供，取代逐一手写的 GetProcAddress 块。自行实现加载器仍然受支持。

1. Add the release’s vnggamessdk.h to your project’s include paths.
2. Construct a VNGGamesSDK::SDK with the module handle from LoadLibrary and call the SDK through it.

1. 將此版本的 vnggamessdk.h 加入專案的 include 路徑。
2. 以 LoadLibrary 取得的模組控制代碼建構 VNGGamesSDK::SDK，並透過它呼叫 SDK。

1. 将此版本的 vnggamessdk.h 加入工程的 include 路径。
2. 以 LoadLibrary 取得的模块句柄构造 VNGGamesSDK::SDK，并通过它调用 SDK。

This addition is opt-in. Nothing breaks if you skip it: your existing integration keeps working, you just don’t gain this capability.

此新增功能為選用。略過不會造成任何問題：你現有的整合仍可正常運作，只是不會獲得此功能。

此新增功能为可选。跳过不会造成任何问题：你现有的集成仍可正常运行，只是不会获得此功能。

1.9.0 adds an init entry point that lets the game supply its own general settings, namely the package name, the running game version, and the concurrent-instance cap, on top of the packaged config. The existing InitializeSdk and InitializeSdkCtx entry points replace nothing and still work unchanged.

1.9.0 新增一個初始化進入點，讓遊戲可在封裝設定之上提供自己的一般設定，包含套件名稱、執行中的遊戲版本，以及同時執行的實例上限。既有的 InitializeSdk 與 InitializeSdkCtx 進入點未被取代，且維持原樣可用。

1.9.0 新增一个初始化入口，让游戏可在封装配置之上提供自己的常规设置，包含包名、运行中的游戏版本，以及同时运行的实例上限。既有的 InitializeSdk 与 InitializeSdkCtx 入口未被取代，且保持原样可用。

1. Call InitializeSdkWithConfig at startup and pass a JSON string whose general object carries your package name, game version, and instance cap.
2. Pass a null config string instead when you want to keep the packaged defaults.

1. 在啟動時呼叫 InitializeSdkWithConfig，並傳入一個 general 物件包含套件名稱、遊戲版本與實例上限的 JSON 字串。
2. 若想保留封裝的預設值，請改為傳入空的設定字串。

1. 在启动时调用 InitializeSdkWithConfig，并传入一个 general 对象包含包名、游戏版本与实例上限的 JSON 字符串。
2. 若想保留封装的默认值，请改为传入空的配置字符串。

See the usage and full signature in the Integration guide:

請在整合指南中查看用法與完整簽名：

请在集成指南中查看用法与完整签名：

This addition is opt-in. Nothing breaks if you skip it: your existing integration keeps working, you just don’t gain this capability.

此新增功能為選用。略過不會造成任何問題：你現有的整合仍可正常運作，只是不會獲得此功能。

此新增功能为可选。跳过不会造成任何问题：你现有的集成仍可正常运行，只是不会获得此功能。

1.9.0 adds a login entry point that presents the SDK’s own login form, so the game no longer has to build a channel picker and drive Direct Login per channel. Which channels the form offers is configured for your game, and failures surface in a new 8xx error band.

1.9.0 新增一個登入進入點，直接呈現 SDK 內建的登入表單，遊戲不必再自行製作渠道選擇畫面並逐一驅動 Direct Login。表單提供哪些渠道由你的遊戲設定決定，失敗則以新的 8xx 錯誤碼區段呈現。

1.9.0 新增一个登录入口，直接呈现 SDK 内置的登录表单，游戏不必再自行制作渠道选择界面并逐一驱动 Direct Login。表单提供哪些渠道由你的游戏配置决定，失败则以新的 8xx 错误码区段呈现。

1. Call ShowLoginForm to present the SDK login form instead of your own channel picker.
2. Read the signed-in user from the result JSON, and handle the 8xx codes for failure and cancellation.

1. 呼叫 ShowLoginForm 以呈現 SDK 登入表單，取代自製的渠道選擇畫面。
2. 從結果 JSON 讀取已登入的使用者，並處理代表失敗與取消的 8xx 錯誤碼。

1. 调用 ShowLoginForm 以呈现 SDK 登录表单，取代自制的渠道选择界面。
2. 从结果 JSON 读取已登录的用户，并处理代表失败与取消的 8xx 错误码。

See the usage and full signature in the Integration guide:

請在整合指南中查看用法與完整簽名：

请在集成指南中查看用法与完整签名：

This addition is opt-in. Nothing breaks if you skip it: your existing integration keeps working, you just don’t gain this capability.

此新增功能為選用。略過不會造成任何問題：你現有的整合仍可正常運作，只是不會獲得此功能。

此新增功能为可选。跳过不会造成任何问题：你现有的集成仍可正常运行，只是不会获得此功能。

1.9.0 lets the game hand its main window handle to the SDK, so SDK screens such as the login form are positioned and layered against the game window instead of floating on their own.

1.9.0 讓遊戲可將主視窗控制代碼交給 SDK，使登入表單等 SDK 畫面能相對於遊戲視窗定位與疊放，而非各自獨立浮動。

1.9.0 让游戏可将主窗口句柄交给 SDK，使登录表单等 SDK 界面能相对于游戏窗口定位与叠放，而非各自独立浮动。

Call SetGameWindow with your main window handle once the window exists and initialization has finished.

在視窗建立且初始化完成後，以主視窗控制代碼呼叫 SetGameWindow。

在窗口创建且初始化完成后，以主窗口句柄调用 SetGameWindow。

See the usage and full signature in the Integration guide:

請在整合指南中查看用法與完整簽名：

请在集成指南中查看用法与完整签名：

This addition is opt-in. Nothing breaks if you skip it: your existing integration keeps working, you just don’t gain this capability.

此新增功能為選用。略過不會造成任何問題：你現有的整合仍可正常運作，只是不會獲得此功能。

此新增功能为可选。跳过不会造成任何问题：你现有的集成仍可正常运行，只是不会获得此功能。

2.2.0 adds the VGSDKAnalytics exports, about forty named entry points grouped by funnel stage covering conversion rate, onboarding, main and daily activities, social and communities, and the rest, plus a VNGGamesSDK::VGSDKAnalytics loader class. Each call is fire-and-forget and returns no result.

2.2.0 新增 VGSDKAnalytics 匯出項，約四十個依漏斗階段分組的具名進入點，涵蓋轉換率、新手引導、主線與日常活動、社群與公會等類別，並提供 VNGGamesSDK::VGSDKAnalytics 載入器類別。每個呼叫皆為送出即結束，不回傳結果。

2.2.0 新增 VGSDKAnalytics 导出项，约四十个依漏斗阶段分组的具名入口，涵盖转化率、新手引导、主线与日常活动、社交与社群等类别，并提供 VNGGamesSDK::VGSDKAnalytics 加载器类。每个调用皆为发出即结束，不返回结果。

↪ Also changed in 2.6.0, see: New VGSDKAnalytics_SendCustomEvent sends unprefixed events to chosen providers

↪ 於 2.6.0 亦有變更，請參見： 新增 VGSDKAnalytics_SendCustomEvent，可將未加前綴的事件送往指定供應商

↪ 于 2.6.0 亦有变更，请参见： 新增 VGSDKAnalytics_SendCustomEvent，可将未加前缀的事件发往指定提供商

1. Call VGSDKAnalytics_MiscConfigAnalytics with the player’s role id and role name as soon as the role is known.
2. Send the named VGSDKAnalytics event that matches each moment in your game, using the Integration guide’s Analytics sections as the catalog.
3. Send anything the catalog does not cover through VGSDKAnalytics_MiscCustomEvent.

1. 在得知角色後，立即以玩家的角色 ID 與角色名稱呼叫 VGSDKAnalytics_MiscConfigAnalytics。
2. 依整合指南 Analytics 章節所列目錄，在遊戲的各個時機送出對應的 VGSDKAnalytics 具名事件。
3. 目錄未涵蓋的內容請透過 VGSDKAnalytics_MiscCustomEvent 送出。

1. 在得知角色后，立即以玩家的角色 ID 与角色名称调用 VGSDKAnalytics_MiscConfigAnalytics。
2. 依集成指南 Analytics 章节所列目录，在游戏的各个时机发出对应的 VGSDKAnalytics 具名事件。
3. 目录未涵盖的内容请通过 VGSDKAnalytics_MiscCustomEvent 发出。

See the usage and full signature in the Integration guide:

請在整合指南中查看用法與完整簽名：

请在集成指南中查看用法与完整签名：

This addition is opt-in. Nothing breaks if you skip it: your existing integration keeps working, you just don’t gain this capability.

此新增功能為選用。略過不會造成任何問題：你現有的整合仍可正常運作，只是不會獲得此功能。

此新增功能为可选。跳过不会造成任何问题：你现有的集成仍可正常运行，只是不会获得此功能。

2.4.0 adds the LevelUp multi-account flow. GetAccount signs the player in with the account the launcher already holds, and SelectAccount opens the picker so the player can switch. Both report failures in a new 9xx error band.

2.4.0 新增 LevelUp 多帳號流程。GetAccount 會以啟動器既有的帳號登入玩家，SelectAccount 則開啟選擇畫面讓玩家切換。兩者的失敗都以新的 9xx 錯誤碼區段回報。

2.4.0 新增 LevelUp 多账号流程。GetAccount 会以启动器既有的账号登录玩家，SelectAccount 则打开选择界面让玩家切换。两者的失败都以新的 9xx 错误码区段返回。

↪ This form is replaced in 2.6.0, see: AccountErrorCode renamed to MultiAccountErrorCode

↪ 此寫法於 2.6.0 已被取代，請參見： AccountErrorCode 更名為 MultiAccountErrorCode

↪ 此写法于 2.6.0 已被取代，请参见： AccountErrorCode 更名为 MultiAccountErrorCode

1. Call GetAccount at startup to sign in with the account the launcher already holds.
2. Call SelectAccount from your switch-account control to let the player pick another account.
3. Handle the 9xx codes and fall back to your normal login when they are returned.

1. 在啟動時呼叫 GetAccount，以啟動器既有的帳號登入。
2. 在切換帳號的操作中呼叫 SelectAccount，讓玩家選擇其他帳號。
3. 處理 9xx 錯誤碼，並在收到時退回你原本的登入流程。

1. 在启动时调用 GetAccount，以启动器既有的账号登录。
2. 在切换账号的操作中调用 SelectAccount，让玩家选择其他账号。
3. 处理 9xx 错误码，并在收到时退回你原本的登录流程。

See the usage and full signature in the Integration guide:

請在整合指南中查看用法與完整簽名：

请在集成指南中查看用法与完整签名：

This addition is opt-in. Nothing breaks if you skip it: your existing integration keeps working, you just don’t gain this capability.

此新增功能為選用。略過不會造成任何問題：你現有的整合仍可正常運作，只是不會獲得此功能。

此新增功能为可选。跳过不会造成任何问题：你现有的集成仍可正常运行，只是不会获得此功能。

2.6.0 adds an in-app WebView so events and announcements open inside the game instead of in an external browser. It runs on an embedded Chromium runtime, so the release also ships runtime files your game must distribute next to VNGGamesSDK.dll.

2.6.0 新增應用程式內 WebView，讓活動與公告在遊戲內開啟，而非跳出外部瀏覽器。它以內嵌 Chromium 執行環境運作，因此此版本也一併提供執行環境檔案，需與 VNGGamesSDK.dll 一起發佈。

2.6.0 新增应用内 WebView，让活动与公告在游戏内打开，而非跳出外部浏览器。它以内嵌 Chromium 运行时运作，因此此版本也一并提供运行时文件，需与 VNGGamesSDK.dll 一起发布。

1. Ship the embedded WebView runtime files from the release next to VNGGamesSDK.dll, namely VNGGamesSDK.webview, libcef.dll, the .pak resources, and the locales/ folder.
2. Call VGSDKEngage_OpenWebView with the page URL where you previously opened an external browser.
3. Handle the 10xx codes and fall back to your old browser path when the WebView reports 1001.

1. 將此版本的內嵌 WebView 執行環境檔案與 VNGGamesSDK.dll 一起發佈，包含 VNGGamesSDK.webview、libcef.dll、.pak 資源檔與 locales/ 資料夾。
2. 在原本會開啟外部瀏覽器之處，改以頁面網址呼叫 VGSDKEngage_OpenWebView。
3. 處理 10xx 錯誤碼，並在 WebView 回報 1001 時退回原本的瀏覽器流程。

1. 将此版本的内嵌 WebView 运行时文件与 VNGGamesSDK.dll 一起发布，包含 VNGGamesSDK.webview、libcef.dll、.pak 资源文件与 locales/ 文件夹。
2. 在原本会打开外部浏览器之处，改以页面网址调用 VGSDKEngage_OpenWebView。
3. 处理 10xx 错误码，并在 WebView 报告 1001 时退回原本的浏览器流程。

See the usage and full signature in the Integration guide:

請在整合指南中查看用法與完整簽名：

请在集成指南中查看用法与完整签名：

Nothing breaks if you skip the feature. If you call it without shipping the runtime files, every call returns 1001 Unsupported and no page is shown.

若不採用此功能，不會有任何損壞。但若在未發佈執行環境檔案的情況下呼叫，每次呼叫都會回傳 1001 Unsupported，且不會顯示任何頁面。

若不采用此功能，不会有任何损坏。但若在未发布运行时文件的情况下调用，每次调用都会返回 1001 Unsupported，且不会显示任何页面。

2.6.0 adds a custom-event entry point that sends the event name exactly as you wrote it, with no SDK prefix, and takes a bitmask naming which analytics providers should receive it. It does not replace VGSDKAnalytics_MiscCustomEvent, which is still supported.

2.6.0 新增一個自訂事件進入點，會原樣送出你所撰寫的事件名稱、不加 SDK 前綴，並以位元遮罩指定哪些分析供應商應收到該事件。它並未取代 VGSDKAnalytics_MiscCustomEvent，後者仍受支援。

2.6.0 新增一个自定义事件入口，会原样发出你所编写的事件名称、不加 SDK 前缀，并以位掩码指定哪些分析提供商应收到该事件。它并未取代 VGSDKAnalytics_MiscCustomEvent，后者仍受支持。

1. Reach for VGSDKAnalytics_SendCustomEvent when you want the exact event name you wrote, or only some providers to receive it.
2. Pass the provider bitmask for the providers that should receive the event.
3. Keep VGSDKAnalytics_MiscCustomEvent where you want the SDK prefix and delivery to every provider. It stays supported, so those call sites do not need to migrate.

1. 當你希望事件名稱完全照你所寫，或只讓部分供應商收到該事件時，請使用 VGSDKAnalytics_SendCustomEvent。
2. 傳入位元遮罩，指定哪些供應商應收到該事件。
3. 若你希望保留 SDK 前綴並送往所有供應商，請繼續使用 VGSDKAnalytics_MiscCustomEvent。它仍受支援，這些呼叫點不需要遷移。

1. 当你希望事件名称完全照你所写，或只让部分提供商收到该事件时，请使用 VGSDKAnalytics_SendCustomEvent。
2. 传入位掩码，指定哪些提供商应收到该事件。
3. 若你希望保留 SDK 前缀并发往所有提供商，请继续使用 VGSDKAnalytics_MiscCustomEvent。它仍受支持，这些调用点不需要迁移。

See the usage and full signature in the Integration guide:

請在整合指南中查看用法與完整簽名：

请在集成指南中查看用法与完整签名：

Nothing breaks and your existing custom-event calls keep working, but every event name keeps the SDK prefix and every event still goes to every provider, so dashboards cannot separate the events you own from the SDK’s own.

不會有任何損壞，既有的自訂事件呼叫仍可運作，但每個事件名稱都會保留 SDK 前綴，且每個事件仍會送往所有供應商，因此報表無法區分你自有的事件與 SDK 本身的事件。

不会有任何损坏，既有的自定义事件调用仍可运作，但每个事件名称都会保留 SDK 前缀，且每个事件仍会发往所有提供商，因此报表无法区分你自有的事件与 SDK 本身的事件。

2.6.0 renames the multi-account error enum so its name matches the flow it belongs to. All five values keep their numbers, 900 through 904.

2.6.0 將多帳號錯誤列舉更名，使名稱與其所屬流程一致。五個值的編號維持 900 至 904 不變。

2.6.0 将多账号错误枚举更名，使名称与其所属流程一致。五个值的编号保持 900 至 904 不变。

Switch each call to the replacement shown in the table above.

將每個呼叫改為上表所示的替代項目。

将每个调用改为上表所示的替代项。

See the usage and full signature in the Integration guide:

請在整合指南中查看用法與完整簽名：

请在集成指南中查看用法与完整签名：

A project that includes the bundled header stops compiling on every AccountErrorCode reference. A project that compares raw integers is unaffected, because the five error numbers did not change.

引入隨附標頭檔的專案會在每個 AccountErrorCode 參照處無法編譯。以原始整數比較的專案不受影響，因為這五個錯誤編號並未改變。

引入随附头文件的工程会在每个 AccountErrorCode 引用处无法编译。以原始整数比较的工程不受影响，因为这五个错误编号并未改变。

From 2.8.0 the per-game config is no longer packaged inside VNGGamesSDK.dll. Each release now publishes a separate vnggamessdk.dat that the SDK reads from disk at startup, which is why the same DLL can serve a game whose config is reissued. Initialization reports config problems with the new codes 114, 115, and 116 in place of 103.

自 2.8.0 起，各遊戲的設定不再封裝於 VNGGamesSDK.dll 內。每個版本改為另外發佈 vnggamessdk.dat，由 SDK 在啟動時從磁碟讀取，因此同一個 DLL 可服務設定重新簽發的遊戲。初始化改以新的 114、115、116 錯誤碼取代 103 回報設定問題。

自 2.8.0 起，各游戏的配置不再封装于 VNGGamesSDK.dll 内。每个版本改为另外发布 vnggamessdk.dat，由 SDK 在启动时从磁盘读取，因此同一个 DLL 可服务配置重新签发的游戏。初始化改以新的 114、115、116 错误码取代 103 报告配置问题。

1. Ship the release’s vnggamessdk.dat next to your game executable, or call VGSDKConfig_SetConfigPath with its full path before initializing.
2. Replace your handling of error 103 with the new 114, 115, and 116 config codes.
3. Re-test a clean install and confirm initialization succeeds.

1. 將此版本的 vnggamessdk.dat 與遊戲執行檔一起發佈，或在初始化前以其完整路徑呼叫 VGSDKConfig_SetConfigPath。
2. 將原本針對錯誤碼 103 的處理改為新的 114、115、116 設定錯誤碼。
3. 重新測試全新安裝，確認初始化能夠成功。

1. 将此版本的 vnggamessdk.dat 与游戏可执行文件一起发布，或在初始化前以其完整路径调用 VGSDKConfig_SetConfigPath。
2. 将原本针对错误码 103 的处理改为新的 114、115、116 配置错误码。
3. 重新测试全新安装，确认初始化能够成功。

See the usage and full signature in the Integration guide:

請在整合指南中查看用法與完整簽名：

请在集成指南中查看用法与完整签名：

A build that ships only the new DLL still compiles, but initialization fails at runtime with 114 ConfigNotFound and no SDK feature works, because the config the DLL used to carry is no longer inside it.

只發佈新 DLL 的建置仍可編譯，但執行時初始化會以 114 ConfigNotFound 失敗，所有 SDK 功能皆無法使用，因為原本由 DLL 攜帶的設定已不在其中。

只发布新 DLL 的构建仍可编译，但运行时初始化会以 114 ConfigNotFound 失败，所有 SDK 功能均无法使用，因为原本由 DLL 携带的配置已不在其中。

From 2.9.0, when the launcher context or the primary session is missing, GetAccount and SelectAccount show the SDK login form and complete with the signed-in user, instead of reporting 901 InvalidNexusContext or 904 PrimarySessionError. Those two codes are still returned when the game is not running under the launcher at all.

自 2.9.0 起，當啟動器情境或主要工作階段不存在時，GetAccount 與 SelectAccount 會顯示 SDK 登入表單並以登入後的使用者完成，而非回報 901 InvalidNexusContext 或 904 PrimarySessionError。若遊戲根本不是在啟動器下執行，這兩個錯誤碼仍會回傳。

自 2.9.0 起，当启动器上下文或主会话不存在时，GetAccount 与 SelectAccount 会显示 SDK 登录表单并以登录后的用户完成，而非返回 901 InvalidNexusContext 或 904 PrimarySessionError。若游戏根本不是在启动器下运行，这两个错误码仍会返回。

1. Make your success path accept a user that arrived through the login form, not only one from the launcher.
2. Remove the 901 and 904 branches that used to open your own login screen.
3. Re-test the multi-account flow with no launcher session present.

1. 讓成功路徑也能接受透過登入表單返回的使用者，而不只是來自啟動器的使用者。
2. 移除原本用來開啟自製登入畫面的 901 與 904 分支。
3. 在沒有啟動器工作階段的情況下重新測試多帳號流程。

1. 让成功路径也能接受通过登录表单返回的用户，而不只是来自启动器的用户。
2. 移除原本用来打开自制登录界面的 901 与 904 分支。
3. 在没有启动器会话的情况下重新测试多账号流程。

See the usage and full signature in the Integration guide:

請在整合指南中查看用法與完整簽名：

请在集成指南中查看用法与完整签名：

Your 901 and 904 branches stop running, so a game that only signed players in from those branches now reaches a success callback it does not handle and the player is left on the login screen.

你的 901 與 904 分支將不再執行，因此只在那些分支中完成登入的遊戲，現在會收到未處理的成功回呼，玩家將停留在登入畫面。

你的 901 与 904 分支将不再执行，因此只在那些分支中完成登录的游戏，现在会收到未处理的成功回调，玩家将停留在登录界面。