# PC SDK Unreal連動ガイド

# 紹介

ゲームのためのSTOVEプラットフォームは、ゲームの配布·販売、コミュニティ、指標分析などを含めたゲーム発売の全過程をワンストップで処理できる統合サービスを提供しています。 STOVE PC SDK(Unrealバージョン、以下PC SDKという)を使えば、Stoveプラットフォームが提供するサービスをゲームに簡単に統合させることができます。

このページではPC SDK(Unreal)を連動する方法について説明します。

PC SDK(Unreal) 連動が初めてでしたら、PC SDK Unrealチュートリアルを先に読んでください。

# 事前準備

UNREALエンジン4.21.2以上でのみ動作し、以下のバージョンはNative StovePCSDK連動が必要です。
STOVE加入のアカウントと発売ゲーム用App key、App secret、Game IdをSTOVE Studio (opens new window)で発行されたかどうかを確認します。
ビジュアル・スタジオ2015アップデート3以上のコンパイラが設置されているか確認します。
PC SDKダウンロードページで、最新バージョンのUnreal配布ファイル(以下、Pluginと表記)をダウンロードします。

# `Plugin` 配布ファイルの構成

# 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 タイプのクラスであるUStoveSDKObjectクラスを使用します。そこにはStovePCSDKライブラリデータタイプとインタフェース及びコールバック関数が再定義されています。連動する前に Pluginで定義された UStoveSDKObjectを継承してゲームエンジン内にUMyStoveSDKObjectを構成してから使ってください。
Prefix
UMyStoveSDKObjectのPrefixはUnreal Engine内でUObjectタイプを相続したクラスに接頭辞Uを貼る規則をそのまま従いました。相続したUObjectでPluginにImportされたインタフェースをSuperを通じて呼び出しています。
Super
受け継いだ親の関数を呼び出すためにアンリアルで提供するキーワードはSuperです。

FStoveResult UMyStoveSDKObject::StoveSDKInit(const FStoveConfig& fConfig)
{
    FStoveResult fResult = Super::StoveSDKInit(fConfig);
}

1
2
3
4

Plugin の環境構成についてはPC SDK Unrealチュートリアルのプロジェクト環境を構成するの 1~3番項目をご覧ください。

# 1) Config, Callback 設定

PC SDK初期化のためには、まず FStoveConfig構造体に値を入れた後、継承されたActorの UStoveSDKObject::StoveSDKInit 関数を呼び出します。
下記のコードを参考にFStoveConfig構造体のフィールド値を入れてください。

FStoveConfig Config{"LIVE",
                    "YOUR_APP_KEY",
                    "YOUR_SECRET_KEY",
                    "YOUR_GAME_ID",
                    StovePCLogLevel::STOVE_PC_LOG_LEVEL_DEBUG,
                    ""}; // Logpath

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, OnInitComplete, 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
18

# 2) SDK初期化

PCSDKの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の有効性確認を除くその他の作業を非同期状態で処理します。非同期作業が問題なく終わった場合、 UMyStoveSDKObject::OnInitCompleteコールバックが呼び出され、初期化時にエラーが発生した場合、UMyStoveSDKobject::OnError関数に伝達されたStovePCError構造体を通じてエラーコード、メッセージなどを確認できます。 StovePCError構造体パラメータのfError.result.result値は、StovePCResultenumと同じで、エラーコードによりエラー状況が推測できます。

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::OnError(const FStoveError& fError)
{
// たぶんすぐにアプリを停止するのではなく、ユーザーにアプリの停止に関するメッセージを表示した後
// ユーザーアクション(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

UMyStoveSDKObject::OnInitCompleteコールバックが来る前に、PC SDKの初期化状態値を調べる必要がある場合、UMyStoveSDKObject::GetInitState関数を使うことができます。

/*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連動時の注意事項

StovePCConfig構造体のログレベル設定時テスト実施にあたってはStovePCLogLevel::STOVE_PC_LOG_LEVEL_DEBUG値に設定し、正式発売時にはStovePCLogLevel::STOVE_PC_LOG_LEVEL_ERROR値に設定してください。

PC SDKの初期化が完了する前に GetToken、 GetUser、 GetOwnership関数を呼び出すと、正常に結果が得られないことがあります。つまり、 OnInitComplete コールバックが正常に受信された後に 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 関数でログインしているユーザー情報を照会します。 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::StoveSDKetUser関数がエラーなく実行されるとUMyStoveSDKobject::OnUserコールバックが呼び出されます。
コールバックで配信される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

トークンとは？ STOVEランチャーにログインしたユーザーのアクセストークン（Access Token）で、ゲームサーバーはこのアクセストークンをSTOVE認証サーバーに渡してログインしたユーザーの検証を行うことができます。アクセストークンの詳細な説明は、store.support@smilegate.comで技術サポートを受けることができます。

# 7) 所有権情報を得る

UMyStoveSDKobject::StoveSDKGetOwnership関数でSTOVEランチャーのユーザーがSTOVEStudioに登録されたゲームを購入し、所有しているかどうかを照会できます。


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 lineの確認コードは不要です。

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 ID)所有権があるため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実行時に以下の案内メッセージ(例)を出力してゲームを終了します。
- 韓国語以外のOS : Please log in to STOVE Client with the account that has purchased the game.
- 韓国語: 게임을 구매한 계정으로 STOVE 클라이언트에 로그인하시기 바랍니다.

ゲーム所有権があるアカウントがなくても所有権機能をテストすることができ、詳しい方法は FAQをご確認ください。

# エラー確認

PC SDK使用中に発生するエラーの確認方法は、大きく以下の２つに分かれます。

# 関数の呼び出し後にリターンされるStovePCResult enum値

PC SDKの全ての関数は、呼び出した後に呼び出しの成功可否を表す StovePCResult enum 値を戻します。全体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

← PC SDK Unity連動ガイド PC SDK Native連動ガイド →