STOVE Store Developer Guide alpha

# PC SDK Unreal对接指南

# 介绍

独立游戏的STOVE平台提供包括游戏发行及销售、社区、指标分析等在内的游戏上市所有过程一站式处理综合服务。 使用PC SDK（Unreal,以下简称PC SDK）可以轻松将Stove平台提供的服务整合到游戏中。

这里说明连接PC SDK的方法。

confirm 如果是第一次对接PC SDK，请先阅读PC SDK Unreal示例。

# 事前准备

  • 仅在 UNREAL 引擎 4.2 1.2 以上运行，以下版本需要Native StovePCSDK对接。
  • 确认是否在STOVE Studio (opens new window)上获得了加入STOVE的账户和游戏上线用Appkey、App secret、Game Id。
  • 确认是否安装了Visual Studio 2015更新3以上的编译器。
  • 在PC SDK 下载 页面上，下载最新版本的"Unreal分发文件（以下标记为Plugin）。。

# Plugin 分发文件配置

Figure1

# 1) include 文件夹

下载Plugin并解压时， Plugins\StoveSDKPlugin\Binaries\ThirdParty\StoveSDKPluginLibrary\include文件夹包含以下文件。

  • StovePCDefine.h
    宣示了用于游戏项目和PC SDK之间交流的API呼叫结果(StovePCResult)、错误结果结构体(StovePCError)、回传函数、API结构体参数等。
  • StovePCSDK.h
    宣示用于游戏项目和PC SDK之间交流的 API 函数。

# 2) bin 文件夹

Plugins\StoveSDKPlugin\Binaries\ThirdParty\StoveSDKPluginLibrary\bin 文件夹需包含每个平台( Win32/x64)和配置( Debug/ Release) 所需的二进制文件。

  • concrt140.dll
  • msvcp100.dll
  • msvcp140.dll
  • msvcr100.dll
  • sgup_api(64).dll
  • StovePCSDK.dll
  • vcruntime140.dll

# 3) StoveSDKPlugin.uplugin

用于在虚幻中识别插件的文件 。 应安排在游戏计划内的Plugins内。

# 对接

  • StovePCSDK_Unreal 使用虚幻引擎的UObject类型的classUSToveSDKObject。 这里重新定义了StovePCSDK库的数据类型和接口及回拨函数。 对接前，您必须继承Plugin"定义的UStoveSDKObject，在游戏项目内组构成UMyStoveSDKObject后使用。

  • Prefix
    UMyStoveSDKObject的 Prefix 遵循了 Unreal Engine 中的继承UObject类型的class加上前缀U的规则。

通过 Super 调用继承的 UObject 中的 Plugin Import 接口。

  • Super
    为了呼叫继承父母函数，Unreal提供的关键词是Super。
FStoveResult UStoveSDKObject::StoveSDKInit(const FStoveConfig Config)
{
    FStoveResult ErrorResult = Super::StoveSDKInit(Config);
    return ErrorResult;
}
1
2
3
4
5

Plugin环境构成请参考PC SDK Unreal 示例的项目环境构成1~3号项目。

# 1) Config, Callback 配置

为了初始化 PC SDK， 首先向FStoveConfig结构填值， 然后调用继承的Actor相关UStoveSDKObject:: StoveSDKInit函数。
参考以下代码填充FStoveConfig结构中的每个字段值:

FStoveConfig fConfig{"LIVE",
                    "YOUR_APP_KEY",
                    "YOUR_SECRET_KEY",
                    "YOUR_GAME_ID",
                    StovePCLogLevel::STOVE_PC_LOG_LEVEL_DEBUG,
                    ""};
1
2
3
4
5
6

有关 FStoveConfig 结构的描述， 请参阅 Plugins\StoveSDKPlugin\Source\StoveSDKPlugin\Public 文件夹中的 StoveSDKStruct.h 文件 。

为了在游戏项目中呼叫PC SDK的API并确认其结果，请使用回传函数。 游戏项目中使用的回传函数如下。

    //StovePCSDK Callback
public:
    void OnError(FStoveError Error) final;
    void OnInitComplete() final;
    void OnToken(FStoveToken Token) final;
    void OnUser(FStoveUser User) final;
    void OnOwnership(int Size, FStoveOwnership* Ownerships) final;
1
2
3
4
5
6
7

除了必须对接的OnError、OnInit Complete、OnOwnership回调函数外，其余回调函数可在必要时对接。 例如，仅使用所有权(Ownership)功能时，可对接如下。

/*只使用所有权（Ownership）功能时，
除了必须进行回拨的OnError、OnInitcomplte
添加OnOwnership进行连接 。*/
void UMyStoveSDKObject::OnInitComplete()
{
    // 初始化成功后的处理内容
}

void UMyStoveSDKObject::OnError(FStoveError Error)
{
    // 错误处理内容
}

void UMyStoveSDKObject::OnOwnership(int size, FStoveOwnership* Ownership)
{
    // 所有权查询后处理内容
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 2) SDK 初始化

在使用 PC SDK 的 API 之前， 在 MyStoveSDKObject.cpp 中的 UMyStoveSDKObject::StoveSDKInit 函数中输入初始化代码， 如以下代码所示:

FStoveResult UMyStoveSDKObject::StoveSDKInit(const FStoveConfig& Config)
{
    FStoveResult ErrorResult = Super::StoveSDKInit(Config);
    if (ErrorResult.Result == StovePCResult::STOVE_PC_NO_ERROR)
    {
        /*StovePCSDK init 成功*/
       
    }
}
1
2
3
4
5
6
7
8
9

UMyStoveSDKObject::StoveSDKInit 函数仅检查 config 和 callback 是否有效， 然后立即返回FStovePCResult enum 类型值。 如果成功，则返回STOVE_PC_NO_ERROR值。 失败时,应返还相应错误代码,并结束游戏。 全部错误代码列表只需查看StovePCDefine.h 文件中的StovePCResult enum 。

在UMyStoveSDKObject::StoveSDKInit 函数内进行 config 和 callback 有效性的检查， 其它任务将由 PCSDK 执行非同步处理。 PC SDK 的异步操作成功时， 调用UMyStoveSDKObject::OnInitComplete 回拨， 发生错误时， 调用UMyStoveSDKObject:::OnError 回程。 如果初始化时发生错误，则可以通过传递到UMyStoveSDKObject:: OnError 函数的 StovePCError 结构检查错误代码、 信息等 。 StovePCError结构参数中的 fError.result.result 值与 StovePCResult enum 相同， 可以用错误代码推测错误情况。

void UMyStoveSDKObject::OnInitComplete()
{
    OnLog("[OnInitComplete]");
}

void UMyStoveSDKObject::OnError(const FStoveError& Error)
{
    switch (Error.FunctionType)
    {
    case STOVE_PC_INIT:
    case STOVE_PC_GET_USER:
    case STOVE_PC_GET_OWNERSHIP:
        QuitApplicationDueToError();
        break;
    }
}

void UMyStoveSDKObject::QuitApplicationDueToError()
{
	// 或许，与其说您立即中断应用程序，不如向用户展示关于中断应用程序的信息后，
	// 根据用户动作(e.g.点击结束按钮)中断应用程序。
	// 那么，请在此删除 QuitApplication ，以实现您的专属逻辑。
	// 推荐的错误信息如下。
	// 韩语: 필수 사전 작업이 실패하여 게임을 종료합니다.
	// 其它语言 : The required pre-task fails and exits the game.
	OnStoveLog("QuitApplicationDueToError");
	FGenericPlatformMisc::RequestExit(false);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
/*调用 StovePC_Init 后...*/
while (Super::GetInitState().State
    == StovePCInitState::STOVE_PC_INIT_PENDING)
{
    FPlatformProcess::Sleep(0.5f);
    RunCallback();
}

if (Super::GetInitState().State
    == StovePCInitState::STOVE_PC_INIT_COMPLETE)
{
    /*初始化完成
    OnInitComplete 回调会被调用*/
    return FStoveResult{STOVE_PC_NO_ERROR};
}
else
{
    /*初始化失败
    会调用 OnError 回调*/
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# 3) 对接SDK时的注意事项

confirm StovePCCConfig结构体设置日志级别时，测试时请设置StovePCLogLevel:::STOVE_PC_LOG_LEVEL_DEBUG值，正式上市时请设置StovePCLogLevel::: STOVE_LOG_ERROR值。

confirm 在 PCSDK 初始化之前调用GetToken,GetUser,GetOwnership 函数可能无法正常获得结果。 也就是说，在正常接收到OnInit Complete回拨后，必须调用GetToken、GetUser、GetOwnership函数才能正常接收到结果。

# 4) SDK 退出

PC SDK 使用结束后，调用StoveSDKUnInit函数来整理使用中的资源。 调用StoveSDKUnInit 函数后， PCSDK 的 API 将停止工作。

FStoveResult UMyStoveSDKObject::StoveSDKUnInit()
{
    FStoveResult ErrorResult = Super::StoveSDKUnInit();
    if (ErorrResult.Result == StovePCResult::STOVE_PC_NO_ERROR)
    {
        /*成功处理*/
    }
    return ErrorResult;
}
1
2
3
4
5
6
7
8
9

# 5) 获取用户信息

以UMyStoveSDKObject::StoveSDKGetUser函数查询登录STOVE客户端 (opens new window)) 的用户信息。

FStoveResult UMyStoveSDKObject::StoveSDKGetUser()
{
    FStoveResult ErrorResult = Super::StoveSDKGetUser();
    if (ErrorResult.Result == StovePCResult::STOVE_PC_NO_ERROR)
    {
        /*成功处理*/
    }

    return ErrorResult; 
}
1
2
3
4
5
6
7
8
9
10

如果调用UMyStoveSDKObject::StoveSDKGetUser函数没有问题， 则调用UMyStoveSDKObject:::OnUser回调。
通过Callback上传达的StovePCUser结构体，可以了解用户的会号、昵称、游戏用户ID信息。

void UMyStoveSDKObject::OnUser(FStoveUser fUser)
{
    /* 输出用户信息*/
    OnLog("[User]");
    OnLog("MemberNo : %u", User.MemberNo);
    OnLog("Nickname : %s", *(User.Nickname));
    OnLog("GameUserId: %s", *(User.GameUserId));
}
1
2
3
4
5
6
7
8

# 6) 获取令牌信息

通过UMyStoveSDKObject::StoveSDKGetToken函数获取已登录到 STOVE客户端 的用户令牌信息 。

FStoveResult UMyStoveSDKObject::StoveSDKGetToken()
{
    FStoveResult ErrorResult = Super::StoveSDKGetToken();
    if (ErrorResult.Result == StovePCResult::STOVE_PC_NO_ERROR)
    {
        /*成功处理*/
    }
 
    return ErrorResult;
}
1
2
3
4
5
6
7
8
9
10

正常处理UMyStoveSDKObject::StoveSDKGetToken函数后， 调用UMyStoveSDKObject:::OnToken回拨。
传递到回拨的StovePCToken 结构包含令牌字符串。

void UMyStoveSDKObject::OnToken(FStoveToken Token)
{
    /*令牌信息输出*/
    OnLog("AccessToken : %s", *(Token.AccessToken));
}
1
2
3
4
5

confirm 令牌是什么? 通过登录STOVE Launcher的用户的Access Token,游戏服务器可以将该Access Token传达给Stove认证服务器,进行登录用户的有效性验证。 有关Access Token的详细说明，请咨询store.support@smilegate.com获得技术支援。

# 7) 获取所有权信息

通过UMyStoveSDKObject::StoveSDKGetOwnership函数，您可以查询登录 STOVE客户端 的用户是否购买并拥有 STOVE Studi所注册的游戏。


FStoveResult UMyStoveSDKObject::StoveSDKGetOwnership()
{
    FStoveResult Result = Super::StoveSDKGetOwnership();
    if (ErrorResult.Result == StovePCResult::STOVE_PC_NO_ERROR)
    {
        /*成功处理*/
        /*所有权相关信息将通过OnOwnership回馈传达。*/ 
    }

    return ErrorResult; 
}
1
2
3
4
5
6
7
8
9
10
11
12

正常处理UMyStoveSDKObject::StoveSDKGetOwnership函数后，将调用UMyStoveSDKObject:::OnOwnership回调。
有关StovePCOwnership结构体的详细信息， 请参阅StovePCDefine.h文件 。

下面是OnOwnership呼叫中判断是否购买游戏的示例代码。 没有DLC时，20~23行的确认代码可以去掉。

void UMyStoveSDKObject::OnOwnership(int size, FStoveOwnership* Ownership)
{
    bool owned = false;
 
    FStoveOwnership* data = Ownership;
    for (int i = 0; i < size; i++, data++)
    {
        if ((data->MemberNo != LOGIN_USER_MEMBER_NO /*StovePCUser 구조체의 memberNo*/)
            || (data->OwnershipCode != 1/*1:所有权获得,2:所有权解除(取消购买时)*/))
        {
            continue;
        }
 
        if (0 == wcscmp(L"YOUR_GAME_ID", *(data->GameId)) && data->GameCode == 3/* 3: BASIC, 4: DEMO*/)
        {
           设置为 owned = true; // 所有权确认变量 true
        }
 
        /*销售DLC时需要*/
        if (0 == wcscmp(L"YOUR_DLC_ID", *(data->GameId)) && data->GameCode == 5 /* 5: DLC*/)
        {
            /*因为拥有YOUR_DLC_ID(DLC)所有权，所以允许使用DLC*/
        }
    }
 
    if(owned)
    {
        // 所有权验证正常完成后创建进入游戏的逻辑
    }
    else
    {
        // 所有权验证失败后终止游戏，进行错误信息显示逻辑
    }
     
     
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
  • 用购买游戏的账户（拥有所有权）登录STOVE客户端后即可正常游戏。
  • 用没有游戏所有权的账号登录STOVE客户端后，运行exe时显示以下提示信息（示例）后终止游戏。
    • 韩语以外的操作系统 : Please log in to STOVE Client with the account that has purchased the game.
    • 韩语：게임을 구매한 계정으로 STOVE 클라이언트에 로그인하시기 바랍니다.

confirm 即使没有拥有游戏所有权的账号，也可以测试所有权功能，详细方法请确认FAQ。

# 确认错误

PC SDK使用过程中发生的错误大致可分为两种情况。

# 调用函数后返回的 StovePCResultenum 值

PC SDK 中的所有函数在调用后立即返回StovePCResult enum 值， 显示调用是否成功 。
全部值可在PC SDK 错误代码 页面上查看。

# 通过 OnError 回拨传递的 StovePCError 结构

在 PC SDK 函数中， 在非同步操作函数发生错误时， 调用UMyStoveSDKObject:: OnError 回拨， 传递包含错误描述的StovePCError 结构。

/*OnError 回拨将在调用时传递 。*/
struct StovePCError
{
    /*表示呼出函数的enum值*/
    StovePCFunctionType functionType;

    /* 表示错误类型的enum值*/
    StovePCResult result;

    /* 错误消息*/
    char* message;

    /* 发生外部错误（http 错误，外部模块错误）时，相应错误代码*/
    int externalError; 
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Last Updated: 2024/3/4 13:52:06

← PC SDK Native对接指引 →