实名认证

应国家法律法规要求，上线运营的游戏必须接入国家层面的实名验证系统。为了确保游戏能正常运行和支付，此步骤必须接入。

SDK 方法名称

XL_UserAuthentic 或 XL_UserAuthenticW（宽字符接口）

调用示例

C++ 调用示例

// 以下代码依赖 Windows API
#include <windows.h>

// 实名认证调用接口导出为 XL_UserAuthentic
HMODULE hModule = GetModuleHandle(_T("XLGameLauncher.dll"));
if (hModule || (hModule = LoadLibrary(_T("XLGameLauncher.dll"))))
{
    int(WINAPI * XL_UserAuthentic)(HWND, LPCSTR, LPCSTR);

    XL_UserAuthentic = (int(WINAPI *)(HWND, LPCSTR, LPCSTR))GetProcAddress(hModule, "XL_UserAuthentic");
    if (XL_UserAuthentic)
    {
        int nResult = XL_UserAuthentic(hwnd, gameId, userId); // hwnd 为游戏窗口句柄
        // 如 int nResult = XL_UserAuthentic(hwnd, "123", "123");
    }
}

// 实名认证调用宽字符接口导出为 XL_UserAuthenticW
HMODULE hModule = GetModuleHandle(_T("XLGameLauncher.dll"));
if (hModule || (hModule = LoadLibrary(_T("XLGameLauncher.dll"))))
{
    int(WINAPI * XL_UserAuthenticW)(HWND, LPCWSTR, LPCWSTR);

    XL_UserAuthenticW = (int(WINAPI *)(HWND, LPCWSTR, LPCWSTR))GetProcAddress(hModule, "XL_UserAuthenticW");
    if (XL_UserAuthenticW)
    {
        int nResult = XL_UserAuthenticW(hwnd, gameId, userId); // hwnd 为游戏窗口句柄
        // 如 int nResult = XL_UserAuthenticW(hwnd, L"123", L"123");
    }
}

调用参数说明

参数	类型	说明
hwnd	HWND	游戏的窗口句柄
gameId	string	平台的游戏 ID
userId	string	平台的用户 ID

返回值说明

返回值	说明
0	实名认证不通过，用户不能进行游戏
1	实名认证通过，用户可以进行游戏

信息

实名认证不通过（返回值为 0）的原因包括：

• 用户未实名。
• 用户已实名但未成年。
• 平台未查询到该用户的记录。
• 用户未填写实名信息就关闭了实名弹窗。

此时，游戏方需要阻止用户进行游戏，并关闭游戏窗口，退出游戏。

Unity C# 代码示例

using System;
using System.Runtime.InteropServices;
using UnityEngine;

/// <summary>
/// 迅雷游戏平台 API 调用示例 (32位版本)
/// </summary>
public class XLGamePlatform : MonoBehaviour
{
    private const string DLL_NAME = "XLGameLauncher.dll";

    #region DLL Import

    /// <summary>
    /// 实名认证 ANSI 版本
    /// </summary>
    /// <param name="hWnd">游戏窗口句柄</param>
    /// <param name="gameId">平台的游戏 ID</param>
    /// <param name="userId">平台的用户 ID</param>
    /// <returns>0 表示认证不通过，1 表示认证通过</returns>
    [DllImport(DLL_NAME, CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Ansi)]
    private static extern int XL_UserAuthentic(
        IntPtr hWnd,
        [MarshalAs(UnmanagedType.LPStr)] string gameId,
        [MarshalAs(UnmanagedType.LPStr)] string userId
    );

    /// <summary>
    /// 实名认证 Unicode 版本（宽字符）
    /// </summary>
    /// <param name="hWnd">游戏窗口句柄</param>
    /// <param name="gameId">平台的游戏 ID</param>
    /// <param name="userId">平台的用户 ID</param>
    /// <returns>0 表示认证不通过，1 表示认证通过</returns>
    [DllImport(DLL_NAME, CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Unicode)]
    private static extern int XL_UserAuthenticW(
        IntPtr hWnd,
        [MarshalAs(UnmanagedType.LPWStr)] string gameId,
        [MarshalAs(UnmanagedType.LPWStr)] string userId
    );

    #endregion

    #region Public API

    /// <summary>
    /// 实名认证（使用 Unicode 宽字符版本）
    /// </summary>
    /// <param name="hWnd">游戏窗口句柄，如果传入 IntPtr.Zero 将自动获取当前活动窗口</param>
    /// <param name="gameId">平台的游戏 ID</param>
    /// <param name="userId">平台的用户 ID</param>
    /// <returns>0 表示认证不通过，1 表示认证通过，-1 表示 DLL 未加载错误</returns>
    public static int UserAuthentic(IntPtr hWnd, string gameId, string userId)
    {
        if (hWnd == IntPtr.Zero)
            hWnd = GetActiveWindow();
            
        if (!IsDllLoaded())
        {
            Debug.LogError("[XLGamePlatform] 迅雷游戏平台 DLL 未加载");
            Debug.LogError("[XLGamePlatform] 游戏需要从迅雷游戏客户端启动才能正确使用 DLL，如有疑问请联系迅雷游戏平台技术人员");
            return -1;
        }
        
        Debug.Log($"[XLGamePlatform] XL_UserAuthenticW({gameId}, {userId})");
        return XL_UserAuthenticW(hWnd, gameId, userId);
    }

    /// <summary>
    /// 实名认证（使用 ANSI 版本）
    /// </summary>
    /// <param name="hWnd">游戏窗口句柄，如果传入 IntPtr.Zero 将自动获取当前活动窗口</param>
    /// <param name="gameId">平台的游戏 ID</param>
    /// <param name="userId">平台的用户 ID</param>
    /// <returns>0 表示认证不通过，1 表示认证通过，-1 表示 DLL 未加载错误</returns>
    public static int UserAuthenticAnsi(IntPtr hWnd, string gameId, string userId)
    {
        if (hWnd == IntPtr.Zero)
            hWnd = GetActiveWindow();
            
        if (!IsDllLoaded())
        {
            Debug.LogError("[XLGamePlatform] 迅雷游戏平台 DLL 未加载");
            Debug.LogError("[XLGamePlatform] 游戏需要从迅雷游戏客户端启动才能正确使用 DLL，如有疑问请联系迅雷游戏平台技术人员");
            return -1;
        }
        
        Debug.Log($"[XLGamePlatform] XL_UserAuthentic({gameId}, {userId})");
        return XL_UserAuthentic(hWnd, gameId, userId);
    }

    /// <summary>
    /// 检查迅雷游戏平台 DLL 是否已经加载
    /// </summary>
    /// <returns>true 表示 DLL 已加载，false 表示未加载</returns>
    public static bool IsDllLoaded()
    {
        return GetModuleHandle(DLL_NAME) != IntPtr.Zero;
    }

    #endregion

    #region Windows API

    [DllImport("user32.dll")]
    private static extern IntPtr GetActiveWindow();

    [DllImport("kernel32.dll")]
    private static extern IntPtr GetModuleHandle(string lpModuleName);

    #endregion

    #region 示例

    /// <summary>
    /// 示例：测试实名认证接口
    /// </summary>
    public void TestUserAuthentic()
    {
        int result = UserAuthentic(IntPtr.Zero, "123", "456");
        Debug.Log($"[XLGamePlatform] UserAuthentic result={result}");
    }

    #endregion
}