用户行为上报

游戏方可以在用户启动游戏、创建或登录游戏角色等时候上报行为信息，在游戏过程中上报心跳信息。

备注

上报信息用于记录用户游戏登录天数、玩游戏的时长、创角等数据，供平台产运人员进行数据分析，运营活动等。

启动游戏上报

SDK 方法名称

XL_PlayGame 或 XL_PlayGameW（宽字符接口）

C++ 调用示例

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

// 玩游戏上报接口导出为 XL_PlayGame
HMODULE hModule = GetModuleHandle(_T("XLGameLauncher.dll"));
if (hModule || (hModule = LoadLibrary(_T("XLGameLauncher.dll"))))
{
    int(WINAPI * XL_PlayGame)(LPCSTR, LPCSTR, LPCSTR);

    (PVOID &)XL_PlayGame = GetProcAddress(hModule, "XL_PlayGame");

    if (XL_PlayGame)
    {
        XL_PlayGame(gameId, serverId, userId);
        // 如 XL_PlayGame("123", "123", "123");
    }
}

// 玩游戏上报宽字符接口导出为 XL_PlayGameW
HMODULE hModule = GetModuleHandle(_T("XLGameLauncher.dll"));
if (hModule || (hModule = LoadLibrary(_T("XLGameLauncher.dll"))))
{
    int(WINAPI * XL_PlayGameW)(LPCWSTR, LPCWSTR, LPCWSTR);

    (PVOID &)XL_PlayGameW = GetProcAddress(hModule, "XL_PlayGameW");

    if (XL_PlayGameW)
    {
        XL_PlayGameW(gameId, serverId, userId);
        // 如 XL_PlayGameW(L"123", L"123", L"123");
    }
}

信息

• 打开游戏客户端需要上报一次。
• serverId 区服标识，可以为空，传 "" 或者 NULL，都表示没有 serverId

调用参数说明

参数	类型	说明
gameId	string	平台的游戏 ID
serverId	string	游戏的区服 ID
userId	string	平台的用户 ID

心跳上报

SDK 方法名称

XL_Heartbeat 或 XL_HeartbeatW（宽字符接口）

调用示例

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

// 心跳上报接口导出为 XL_Heartbeat
HMODULE hModule = GetModuleHandle(_T("XLGameLauncher.dll"));
if (hModule || (hModule = LoadLibrary(_T("XLGameLauncher.dll"))))
{
    int(WINAPI * XL_Heartbeat)(LPCSTR, LPCSTR);

    (PVOID &)XL_Heartbeat = GetProcAddress(hModule, "XL_Heartbeat");

    if (XL_Heartbeat)
    {
        XL_Heartbeat(gameId, userId);
        // 如 XL_Heartbeat("123", "123");
    }
}

// 心跳上报宽字符接口导出为 XL_HeartbeatW
HMODULE hModule = GetModuleHandle(_T("XLGameLauncher.dll"));
if (hModule || (hModule = LoadLibrary(_T("XLGameLauncher.dll"))))
{
    int(WINAPI * XL_HeartbeatW)(LPCWSTR, LPCWSTR);

    (PVOID &)XL_HeartbeatW = GetProcAddress(hModule, "XL_HeartbeatW");

    if (XL_HeartbeatW)
    {
        XL_HeartbeatW(gameId, userId);
        // 如 XL_HeartbeatW(L"123", L"123");
    }
}

信息

游戏方需自行实现定时上报，即定时执行心跳上报方法，建议上报间隔为 10s 。

调用参数说明

参数	类型	说明
gameId	string	平台的游戏 ID
userId	string	平台的用户 ID

具体游戏行为上报

SDK 方法名称

XL_Report 或 XL_ReportW（宽字符接口）

调用示例

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

// 游戏行为上报接口导出为 XL_Report
HMODULE hModule = GetModuleHandle(_T("XLGameLauncher.dll"));
if (hModule || (hModule = LoadLibrary(_T("XLGameLauncher.dll"))))
{
    int(WINAPI * XL_Report)(LPCSTR, LPCSTR, int, LPCSTR);

    (PVOID &)XL_Report = GetProcAddress(hModule, "XL_Report");

    if (XL_Report)
    {
        XL_Report(gameId, userId, actionType, params);
        // 如 XL_Report("123", "123", 4, "")
    }
}

// 游戏行为上报宽字符接口导出为 XL_ReportW
HMODULE hModule = GetModuleHandle(_T("XLGameLauncher.dll"));
if (hModule || (hModule = LoadLibrary(_T("XLGameLauncher.dll"))))
{
    int(WINAPI * XL_ReportW)(LPCWSTR, LPCWSTR, int, LPCWSTR);

    (PVOID &)XL_ReportW = GetProcAddress(hModule, "XL_ReportW");

    if (XL_ReportW)
    {
        XL_ReportW(gameId, userId, actionType, params);
        // 如 XL_ReportW(L"123", L"123", 4, L"")
    }
}

调用参数说明

参数	类型	说明
gameId	string	平台的游戏 ID
userId	string	平台的用户 ID
actionType	int	上报行为的类型
params	string	上报参数，是 JSON 字符串

上报行为的类型 actionType

参数	类型	说明	上报时机
0	int	未知
1	int	创建角色	当用户创建角色完成时
2	int	登录角色	当用户登录角色完成时
3	int	启动下载器	当用户启动下载器时
4	int	启动游戏	当用户启动游戏时

上报参数 actionType

在必传参数的基础上可以扩展传递的参数。

事件	参数	类型	说明
创建角色	roleId	string	角色标识，游戏方自己定义，可以是角色 ID
	roleName	string	角色名称
	serverId	string	区服标识，有则填写，否则为空
	serverName	string	区服名称，有则填写，否则为空
登录角色	roleId	string	角色标识，游戏方自己定义，可以是角色 ID
	roleName	string	角色名称
	serverId	string	区服标识，有则填写，否则为空
	serverName	string	区服名称，有则填写，否则为空
启动下载器	无
启动游戏	无

信息

上报参数 params 需要转换为 json 字符串，然后传递给 XL_Report。
如 "{\"roleId\":\"12312312\",\"roleName\":\"测试角色\"}"

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

    [DllImport(DLL_NAME, CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Ansi)]
    private static extern int XL_PlayGame(
        [MarshalAs(UnmanagedType.LPStr)] string gameId,
        [MarshalAs(UnmanagedType.LPStr)] string serverId,
        [MarshalAs(UnmanagedType.LPStr)] string userId
    );

    [DllImport(DLL_NAME, CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Unicode)]
    private static extern int XL_PlayGameW(
        [MarshalAs(UnmanagedType.LPWStr)] string gameId,
        [MarshalAs(UnmanagedType.LPWStr)] string serverId,
        [MarshalAs(UnmanagedType.LPWStr)] string userId
    );

    [DllImport(DLL_NAME, CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Ansi)]
    private static extern int XL_Heartbeat(
        [MarshalAs(UnmanagedType.LPStr)] string gameId,
        [MarshalAs(UnmanagedType.LPStr)] string userId
    );

    [DllImport(DLL_NAME, CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Unicode)]
    private static extern int XL_HeartbeatW(
        [MarshalAs(UnmanagedType.LPWStr)] string gameId,
        [MarshalAs(UnmanagedType.LPWStr)] string userId
    );

    [DllImport(DLL_NAME, CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Ansi)]
    private static extern int XL_Report(
        [MarshalAs(UnmanagedType.LPStr)] string gameId,
        [MarshalAs(UnmanagedType.LPStr)] string userId,
        int actionType,
        [MarshalAs(UnmanagedType.LPStr)] string extraInfo
    );

    [DllImport(DLL_NAME, CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Unicode)]
    private static extern int XL_ReportW(
        [MarshalAs(UnmanagedType.LPWStr)] string gameId,
        [MarshalAs(UnmanagedType.LPWStr)] string userId,
        int actionType,
        [MarshalAs(UnmanagedType.LPWStr)] string extraInfo
    );

    #endregion

    #region Public API

    /// <summary>
    /// 启动游戏上报
    /// </summary>
    /// <param name="gameId">平台的游戏 ID</param>
    /// <param name="serverId">游戏的区服 ID，可以为空字符串</param>
    /// <param name="userId">平台的用户 ID</param>
    /// <returns>上报结果（0 表示成功，-1 表示 DLL 未加载错误）</returns>
    public static int PlayGame(string gameId, string serverId, string userId)
    {
        if (!IsDllLoaded())
        {
            Debug.LogError("[XLGamePlatform] 迅雷游戏平台 DLL 未加载");
            Debug.LogError("[XLGamePlatform] 游戏需要从迅雷游戏客户端启动才能正确使用 DLL，如有疑问请联系迅雷游戏平台技术人员");
            return -1;
        }
        Debug.Log($"[XLGamePlatform] XL_PlayGameW({gameId}, {serverId}, {userId})");
        return XL_PlayGameW(gameId, serverId, userId);
    }

    /// <summary>
    /// 启动游戏上报（ANSI 字符版本，优先使用上面的 PlayGame 方法，一般不使用此方法）
    /// </summary>
    /// <param name="gameId">平台的游戏 ID</param>
    /// <param name="serverId">游戏的区服 ID，可以为空字符串</param>
    /// <param name="userId">平台的用户 ID</param>
    /// <returns>上报结果（0 表示成功，-1 表示 DLL 未加载错误）</returns>
    public static int PlayGameAnsi(string gameId, string serverId, string userId)
    {
        if (!IsDllLoaded())
        {
            Debug.LogError("[XLGamePlatform] 迅雷游戏平台 DLL 未加载");
            Debug.LogError("[XLGamePlatform] 游戏需要从迅雷游戏客户端启动才能正确使用 DLL，如有疑问请联系迅雷游戏平台技术人员");
            return -1;
        }
        Debug.Log($"[XLGamePlatform] XL_PlayGame({gameId}, {serverId}, {userId})");
        return XL_PlayGame(gameId, serverId, userId);
    }

    /// <summary>
    /// 心跳上报
    /// </summary>
    /// <param name="gameId">平台的游戏 ID</param>
    /// <param name="userId">平台的用户 ID</param>
    /// <returns>上报结果（0 表示成功，-1 表示 DLL 未加载错误）</returns>
    public static int Heartbeat(string gameId, string userId)
    {
        if (!IsDllLoaded())
        {
            Debug.LogError("[XLGamePlatform] 迅雷游戏平台 DLL 未加载");
            Debug.LogError("[XLGamePlatform] 游戏需要从迅雷游戏客户端启动才能正确使用 DLL，如有疑问请联系迅雷游戏平台技术人员");
            return -1;
        }
        Debug.Log($"[XLGamePlatform] XL_HeartbeatW({gameId}, {userId})");
        return XL_HeartbeatW(gameId, userId);
    }

    /// <summary>
    /// 心跳上报（ANSI 字符版本，优先使用上面的 Heartbeat 方法，一般不使用此方法）
    /// </summary>
    /// <param name="gameId">平台的游戏 ID</param>
    /// <param name="userId">平台的用户 ID</param>
    /// <returns>上报结果（0 表示成功，-1 表示 DLL 未加载错误）</returns>
    public static int HeartbeatAnsi(string gameId, string userId)
    {
        if (!IsDllLoaded())
        {
            Debug.LogError("[XLGamePlatform] 迅雷游戏平台 DLL 未加载");
            Debug.LogError("[XLGamePlatform] 游戏需要从迅雷游戏客户端启动才能正确使用 DLL，如有疑问请联系迅雷游戏平台技术人员");
            return -1;
        }
        Debug.Log($"[XLGamePlatform] XL_Heartbeat({gameId}, {userId})");
        return XL_Heartbeat(gameId, userId);
    }

    /// <summary>
    /// 具体游戏行为上报
    /// </summary>
    /// <param name="gameId">平台的游戏 ID</param>
    /// <param name="userId">平台的用户 ID</param>
    /// <param name="actionType">上报行为的类型</param>
    /// <param name="extraInfo">上报参数，JSON 字符串</param>
    /// <returns>上报结果（0 表示成功，-1 表示 DLL 未加载错误）</returns>
    public static int Report(string gameId, string userId, int actionType, string extraInfo)
    {
        if (!IsDllLoaded())
        {
            Debug.LogError("[XLGamePlatform] 迅雷游戏平台 DLL 未加载");
            Debug.LogError("[XLGamePlatform] 游戏需要从迅雷游戏客户端启动才能正确使用 DLL，如有疑问请联系迅雷游戏平台技术人员");
            return -1;
        }
        Debug.Log($"[XLGamePlatform] XL_ReportW({gameId}, {userId}, {actionType}, {extraInfo})");
        return XL_ReportW(gameId, userId, actionType, extraInfo);
    }

    /// <summary>
    /// 具体游戏行为上报（ANSI 字符版本，优先使用上面的 Report 方法，一般不使用此方法）
    /// </summary>
    /// <param name="gameId">平台的游戏 ID</param>
    /// <param name="userId">平台的用户 ID</param>
    /// <param name="actionType">上报行为的类型</param>
    /// <param name="extraInfo">上报参数，JSON 字符串</param>
    /// <returns>上报结果（0 表示成功，-1 表示 DLL 未加载错误）</returns>
    public static int ReportAnsi(string gameId, string userId, int actionType, string extraInfo)
    {
        if (!IsDllLoaded())
        {
            Debug.LogError("[XLGamePlatform] 迅雷游戏平台 DLL 未加载");
            Debug.LogError("[XLGamePlatform] 游戏需要从迅雷游戏客户端启动才能正确使用 DLL，如有疑问请联系迅雷游戏平台技术人员");
            return -1;
        }
        Debug.Log($"[XLGamePlatform] XL_Report({gameId}, {userId}, {actionType}, {extraInfo})");
        return XL_Report(gameId, userId, actionType, extraInfo);
    }

    /// <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 OnGameStart(string gameId, string serverId, string userId)
    {
        int result = PlayGame(gameId, serverId, userId);
        Debug.Log($"[XLGamePlatform] PlayGame result={result}");
    }

    /// <summary>
    /// 示例：用户创建角色完成后上报
    /// </summary>
    public void OnRoleCreated(string gameId, string userId, string roleId, string roleName, string serverId, string serverName)
    {
        // 构建 JSON 参数
        string json = $"{{\"roleId\":\"{roleId}\",\"roleName\":\"{roleName}\",\"serverId\":\"{serverId}\",\"serverName\":\"{serverName}\"}}";
        int result = Report(gameId, userId, 1, json);
        Debug.Log($"[XLGamePlatform] Report(CreateRole) result={result}");
    }

    /// <summary>
    /// 示例：用户登录角色完成后上报
    /// </summary>
    public void OnRoleLogin(string gameId, string userId, string roleId, string roleName, string serverId, string serverName)
    {
        // 构建 JSON 参数
        string json = $"{{\"roleId\":\"{roleId}\",\"roleName\":\"{roleName}\",\"serverId\":\"{serverId}\",\"serverName\":\"{serverName}\"}}";
        int result = Report(gameId, userId, 2, json);
        Debug.Log($"[XLGamePlatform] Report(LoginRole) result={result}");
    }

    #endregion
}