STOVE Store Developer Guide alpha

# PC SDK Native連動ガイド

# 紹介

ゲームのためのSTOVEプラットフォームは、ゲームの配布と販売、コミュニティ、指標分析などを含む、ゲームリリースのすべてのプロセスをワンストップで処理できる統合サービスを提供します。 PC SDK（Native）を使用すると、Stoveプラットフォームが提供するサービスをゲームに簡単に統合できます。

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

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

# 事前準備

*STOVE加入アカウントとリリースするゲーム用のApp key、App secret、Game IdをSTOVE Studio (opens new window)で発行されたことを確認します。

  • PC SDK ダウンロード ページから、最新バージョンの Native(C/C++) 配布ファイル (以下 StovePCSDK と表記) をダウンロードします。

# StovePCSDK配布ファイルの構成

# 1) includeフォルダー

Stove PC SDKをダウンロードして解凍したらincludeフォルダーの中に下記のフォルダーが含まれています。

  • StovePCDefine.h
    ゲームとPC SDKのコミュニケーションのため使われるAPI呼び出し結果（StovePCResult）、エラー結果構造体（StovePCError）、コールバック関数、API構造体パラメータなどが宣言されています。

  • StovePCSDK.h
    ゲームとPC SDKのコミュニケーションのため使われるAPI関数プロトタイプが宣言されています。

# 2) binフォルダー

binフォルダーの下にはプラットフォーム(Win32/x64)及び構成(Debug/Release)別に必要なバイナリーが含まれています。

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

confirm StovePCSDK.libを除く上記のリストのDllファイルは、ゲームクライアントをエンドユーザーに配布するときに必ず含める必要があります。

# 3) sampleフォルダー

sample フォルダーの下には、 StovePCSDKの動作確認ができる StovePCSDKTestMfc.exe GUIアプリケーションが各プラットフォーム(Win32/x64)ごとにReleaseビルドで入っています。
まず、 StovePCConfig.MFC.ini ファイルにApp key、App secretなどを入力した後 StovePCSDKTestMfc.exeを実行します。また、StovePCSDKTestMfcを直接実行してSetting UIにAppKey、SecretKeyなどを直接入力することもできます。

# StovePCSDKビルド環境構築

ビルド環境の構成についてはPC SDK Nativeチュートリアルの プロジェクトの環境構築 項目をご覧ください。

# 連動開始

# 1) Config、Callback設定

PC SDK初期化のためには、まずStovePCConfigと StovePCCallback 構造体に値を入れた後、StovePC_Init 関数を呼び出します。 下記のコードを参考に StovePCConfig 構造体の各フィールド値を入れます。

StovePCConfig config{"live",
                    "YOUR_APP_KEY",
                    "YOUR_SECRET_KEY",
                    "YOUR_GAME_ID",
                    StovePCLogLevel::STOVE_PC_LOG_LEVEL_DEBUG,
                    ""};
1
2
3
4
5
6

StovePCConfig 構造体についての説明は StovePCDefine.h ファイルをご覧ください。

ゲームとPC SDKの間のコミュニケーションは、StovePCCallback構造体に関連付けられたコールバック関数を使用します。 ゲームコードでは、以下の StovePCCallback 構造体のコールバックポインタに接続する関数ポインタを事前に定義し、定義された関数のポインタご連結ください。

struct StovePCCallback
{
    /// StovePCSDKでエラーが発生すると呼び出されるコールバック
    void(*OnError)(const StovePCError error);

    /// PC SDK初期化が完了した際に呼び出されるコールバック
    void(*OnInitComplete)();

    /// GetToken処理が完了した際に呼び出されるコールバック
    void(*OnToken)(const StovePCToken token);

    /// GetUser処理が完了した際に呼び出されるコールバック
    void(*OnUser)(const StovePCUser user);

    /// GetOwnership処理が完了した際に呼び出されるコールバック
    void(*OnOwnership)(int size, StovePCOwnership* ownership);
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

StovePCCallback 構造体のinstanceは使用する前に必ずNULL初期化が必要です。

/*StovePCCallback構造体instance生成*/
StovePCCallback callback;
/*全ての関数ポインタをNULLに初期化*/
memset(&callback, 0, sizeof(StovePCCallback));
/*作成した関数ポインタに繋げる*/
callback.OnError = OnMyErrorCallback;
callback.OnInitComplete = OnMyInitCompleteCallback;
callback.OnToken = OnMyTokenCallback;
callback.OnUser = OnMyUserInfoCallback;
callback.OnOwnership = OnMyOwnershipCallback;
1
2
3
4
5
6
7
8
9
10

必須連動の OnError, OnInitComplete, OnOwnership コールバック関数以外の残りのコールバック関数は必要なときにのみ連動を行うことができます。 たとえば、オーナーシップ機能のみを使用する場合は、次のように接続できます。

/*所有権(Ownership)機能のみ使用する場合、
必須のコールバックであるOnError、OnInitcomplte以外に
OnOwnershipコールバックのみ作成して繋げます。*/
callback.OnError = OnMyErrorCallback;
callback.OnInitComplete = OnMyInitCompleteCallback;
callback.OnOwnership = OnMyOwnershipCallback;
1
2
3
4
5
6

# 2) SDK初期化

StovePCConfigとStovePCCallback構造体の初期化とコールバック関数の接続が完了したら、PC SDKを初期化するためにStovePC_Init関数を呼び出します。

StovePCResult result = StovePC_Init(config, callback);
if (result == StovePCResult::STOVE_PC_NO_ERROR)
{
    /*StovePCSDK init成功
    タイマーなどを利用し、定期的にStovePC_RunCallback()を呼び出す*/

}
1
2
3
4
5
6
7

StovePC_Init 関数はconfigとcallbackの有効性可否のみ確認し、すぐ StovePCResult enumタイプの値を戻します。
成功した場合、STOVE_PC_NO_ERRORの値が返されます。 失敗した場合は、対応するエラーコードを返し、ゲームの終了を処理する必要があります。 完全なエラーコードのリストは、StovePCDefine.hファイルのStovePCResult enumごチェックください。

戻り値が STOVE_PC_NO_ERROR、即ち「成功」である場合、 StovePC_RunCallback 関数を定期的に呼び出します。
繋がっているコールバックが正常に呼び出されるためには、StovePC_RunCallback 関数を定期的に呼び出す必要があります。
呼び出しの間隔が長いとコールバックが返す速度も遅くなるため、適切な呼び出しの間隔を保つ方がいいです。このガイドのサンプルコードは、呼び出し周期を0.5秒に設定しました。

confirm PC SDKに繋がってるコールバックは StovePC_RunCallback 関数を呼び出したスレッドでのみ呼び出されます。

StovePC_Init 関数はconfigとcallbackの有効性確認を除くその他の作業を非同期状態で処理します。
非同期作業が問題なく終わった場合、 OnInitComplete コールバックが呼び出され、エラーが発生した場合には OnError コールバックが呼び出されます。
エラーが発生した場合、送られた StovePCError 構造体からエラーコードとメッセージなどを確認できます。

void OnInitComplete()
{
    printf("pc sdk init success");
}

void OnError(const StovePCError error)
{
	switch (Error.functionType)
	{
	case STOVE_PC_INIT:
	case STOVE_PC_GET_USER:
	case STOVE_PC_GET_OWNERSHIP:
		QuitApplicationDueToError();
		break;
	}
}

void QuitApplicationDueToError()
{
// たぶんすぐにアプリを停止するのではなく、ユーザーにアプリの停止に関するメッセージを表示した後
// ユーザーアクション(e.g. 終了ボタンをクリック)によってアプリを中断したいかもしれません。
// その場合は、ここでQuitApplicationをクリアして独自のロジックを実装します。
// 推奨する必須の事前処理エラーに関するメッセージは次のとおりです。
// 韓国語 : 필수 사전 작업이 실패하여 게임을 종료합니다.
//その他の言語：The required pre-task fails and exits the game
	OnStoveLog("QuitApplicationDueToError");
	exit(0)
}
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

OnInitCompleteコールバックが来る前に、PC SDKの初期化状態値を照会する必要がある場合、StovePC_GetInitState関数を使用することができます。

/*StovePC_Init呼び出し後。..*/
while(StovePC_GetInitState()
        == StovePCInitState::STOVE_PC_INIT_PENDING)
{
    sleep(500ms);
    StovePC_RunCallback();
}

if (StovePC_GetInitState()
            == StovePCInitState::STOVE_PC_INIT_COMPLETE)
{
    /*初期化完了
    OnInitCompleteコールバックが呼び出される*/
}
else
{
    /*初期化失敗
    OnErrorコールバックが呼び出される*/
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 3) SDK連動時の注意事項

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

confirm PC SDKの初期化が完了する前に GetToken、 GetUser、 GetOwnership関数を呼び出すと、正常に結果が得られないことがあります。 つまり、 OnInitComplete コールバックが正常に受信された後に GetToken、 GetUser、 GetOwnership 関数を呼び出さなければ正常に結果を受け取ることができます。

# 4) SDK終了

PC SDKの使用が終わった後、StovePC_UnInit関数を呼び出し、使用中のリソースを整理します。

StovePCResult result = StovePC_UnInit();
if (result == StovePCResult::STOVE_PC_NO_ERROR)
{
    /*成功処理*/
}
...
1
2
3
4
5
6

# 5)ユーザー情報を取得

Stove PC_GetUser関数でSTOVEランチャーにログインしたユーザー情報を照会します。

StovePCResult result = StovePC_GetUser();
if (result == StovePCResult::STOVE_PC_NO_ERROR)
{
    /*成功処理*/
}
1
2
3
4
5

StovePC_GetUser 関数が正常に処理されたら OnUser コールバックが呼び出されます。
コールバックで配信される「StovePCUser」構造体を通じて、ユーザーのメンバーナンバー、ニックネーム、ゲームユーザーのID情報などを確認できます。 StovePCUser 構造体についての説明は StovePCDefine.h ファイルをご覧ください。

void OnUser(const StovePCUser user)
{
    /*사용자 정보 출력*/
    printf("User Info(memberNo = %I64d, nickname = %S, gameUserId = %s)",
                      user.memberNo, user.nickname, user.gameUserId);
}
1
2
3
4
5
6

# 6)トークン情報を取得

StovePC_GetToken関数でSTOVEランチャーにログインしたユーザーのトークン情報を確認できます。

StovePCResult result = StovePC_GetToken();
if (result == StovePCResult::STOVE_PC_NO_ERROR)
{
    /*成功処理*/
}
1
2
3
4
5

StovePC_GetToken 関数が正常に処理されたら OnToken コールバックが呼び出されます。
コールバックに送られる StovePCToken 構造体にはトークン文字列が含まれています。

void OnToken(const StovePCToken token)
{
    /*トークン情報出力*/
    printf("Token : %s", token.accessToken);
}
1
2
3
4
5

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

# 7) 所有権情報を得る

「StovePC_GetOwnership」の関数で、ユーザーがそのゲームを購入して所有しているかどうかを確認できます。


StovePCResult result = StovePC_GetOwnership();
if (result == STOVE_PC_NO_ERROR)
{
    /* 成功処理*/
    /*所有権に関する情報はOnOwnershipコールバックにお送りします。*/ 
}
1
2
3
4
5
6
7

「StovePC_GetOwnership」の関数が正常に処理されると、OnOwnershipのコールバックが呼び出されます。
OnOwnershipコールバックのパラメータである「StovePCOwnership」構造体に対する詳細情報はStovePCDEfine.hファイルをご参照ください。

以下はOnOwnershipコールバックでゲームを購入するかどうかを判断する例コードです。
DLCがないパッケージゲームの場合、20~23 lineの確認コードは不要です。

void OnOwnership(int size, StovePCOwnership* ownership)
{
    bool owned = false;
 
    StovePCOwnership* 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実行時に以下の案内メッセージ(例)を出力してゲームを終了します。
    • 韓国語以外のOS : Please log in to STOVE Client with the account that has purchased the game.
    • 韓国語: 게임을 구매한 계정으로 STOVE 클라이언트에 로그인하시기 바랍니다.

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

# エラー確認

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

# 関数の呼び出し後に戻されるStovePCResult enum値

PC SDKの全ての関数は、呼び出し直後に呼び出しの成功可否を表すStovePCResult enum 値を戻します。
全体値は、PC SDKエラーコードページから確認できます。

# OnErrorコールバックで送られるStovePCError構造体

PC SDK関数の中、非同期で動作する関数からエラーが発生した場合には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はSTOVEプラットフォームのゲームサポートサービスをゲームに統合できるようにAPIを提供しています。 PCSDKが対応しているゲーム対応サービスには、スタット、業績、リーダーボードがあります。 それぞれのサービスは以下のように定義します。

  • スタット:ユーザーの様々なゲームPlay Dataを数値で記録してくれるサービス
  • 業績:ゲームPlayチャレンジ課題を設定し、ユーザーごとに達成情報を提供してくれるサービス
  • リーダーボード:特定のゲームPlay Dataのユーザーランキング情報を提供するサービス

PC SDKゲーム支援サービスAPIを使用するためには、Studioでのゲーム支援サービスのメタデータ登録が先行される必要があります。

メタデータの管理についての内容は簡単なコンソール使用マニュアルを参照してください。

# 1) Callback 設定

ゲーム支援サービスAPIを使用してPCSDKとコミュニケーションするためには、以下の「StovePCCallbak」構造体のコールバックポインターに連結するコールバック関数をご定義ください。

struct StovePCCallback
{
    void(*OnError)(const StovePCError error);
    void(*OnInitComplete)();
    void(*OnToken)(const StovePCToken token);
    void(*OnUser)(const StovePCUser user);
    void(*OnOwnership)(int size, StovePCOwnership* ownership);

    // GetStat処理が完了した時に呼び出されるコールバック
    void(*OnStat)(const StovePCStat stat);

    // SetStat処理が完了した時に呼び出されるコールバック
    void(*OnSetStat)(const StovePCStatValue statValue);

    // GetAchievement処理が完了した時に呼び出されるコールバック
    void(*OnAchievement)(StovePCAchievement achievement);

    // GetAllAchievement処理が完了した時に呼び出されるコールバック
    void(*OnAllAchievement)(int size, StovePCAchievement* achievement);

    // GetRank API 呼び出し時に応答を受けるコールバック関数ポインタ
    void(*OnRank)(int size, StovePCRank* rank, unsigned int rankTotalCount);
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

連動する1）Config、Callbak設定のようにStove PCCallback構造体のコールバックポインタにコールバック関数を接続します。

// StovePCCallback構造体インスタンス作成
StovePCCallback callback;

// すべての関数ポインタをNULLに初期化
memset(&callback, 0, sizeof(StovePCCallback));

// 実装した関数ポインタを接続
callback.OnError = OnMyErrorCallback; /* 全域で定義したコールバック関数*/
callback.OnInitComplete = OnMyInitCompleteCallback; /* 全域で定義したコールバック関数*/
callback.OnToken = OnMyTokenCallback; /* 全域で定義したコールバック関数*/
callback.OnUser = OnMyUserInfoCallback; /* 全域で定義したコールバック関数*/
callback.OnOwnership = OnMyOwnershipCallback; /* 全域で定義したコールバック関数*/
 
 // ゲームサポートサービス 
callback.OnStat = OnMyStat; /* 全域で定義したコールバック関数*/ 
callback.OnSetStat = OnMySetStat; /* 全域で定義したコールバック関数*/
callback.OnAchievement=OnMyAchievement;/*全域で定義したコールバック関数*/
callback.OnAllAchievement=OnMyAllAchievement;/*全域で定義したコールバック関数*/
callback.OnRank=OnMyRank;/*全域で定義したコールバック関数*/
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

OnStat、OnSetStat、OnAchievement、OnAllAchievement、OnRankコールバック関数を必ず実現する必要はありません。

ゲームで使用するゲームサポートサービスに合わせて必要なコールバック関数を実装して接続できます。

# 2) 使用者スタットアップデートする

StovePC_SetStat関数でログインした使用者の当該ゲームに対する特定スタットをアップデートします。

// 入力パラメータ
// constchar*statId：Studioで登録したスタット識別子
//const int statValue：アップデートするスタット値
StovePCResult result = StovePC_SetStat("STAT_ID", STAT_VALUE);
if(result == StovePCResult::STOVE_PC_NO_ERROR)
{
    /* 成功処理 */
}
1
2
3
4
5
6
7
8

StovePC_SetStat関数が正常に処理されれば、OnSetStatコールバックが呼び出されます。
コールバックに伝達されるStovePCStatValue構造体には現在スタット値とアップデートの状態を示すフラグやエラーメッセージが含まれています。

スタット価格が完全に反映されてアップデートされたなら、Updatedフィールドはtrue、ErrorMessageフィールドは、空の文字列が含まれ、スタット価格が部分的にアップデートしたら、Updatedフィールドはtrue、ErrorMessageフィールドは"integer overflow"のような文字列が含まれます。

例えば、INCREMENTタイプスタットの現在スタット価格が2,147,483,000と仮定してStovePC_SetStatAPIを通じて1,000を合算しとするなら、Int32タイプが持つことのできる値の範囲を脱することになるため、アップデートを要請した値(1,000)の一部だけが反映され、現在価格がInt32タイプの最大値の2,147,483,647にアップデートされている場合ErrorMessageフィールドに"integer overflow"のような文字列が含まれます。

下表はStovePCStatValue構造体を通じて得られる結果の一覧です。

スタット類型 Updated ErrorMessage 結果
すべての類型 True ""(空の文字列) 要請の価格が現在価格に完全にアップデートすること
INCREMENT True
INCREMENT False "integer overflow" ストレージ容量超過でアップデートされない
MIN False
MAX False
REPLACE Fasle 
void OnSetStat(const StovePCStatValue statValue)
{
    // スタットアップデート結果情報出力
    printf("OnSetStat");
    printf(" - statValue.currentValue : %d", statValue.currentValue);
    printf(" - statValue.updated : %s", statValue.updated ? "true" : "false");
    printf(" - statValue.errorMessage : %s", statValue.errorMessage);
}
1
2
3
4
5
6
7
8

confirm 注意事項) コールバックパラメータStovePCStatValue構造体の有効な範囲は、コールバック関数スコープに限定されます。 PC SDKは、コールバック関数の実行が完了するとすぐに、内部で割り当てたメモリを解除します。 したがって、コールバック関数スコープの外で「StovePCStatValue」構造体の情報を使用するために保存が必要な場合は、必ず深いコピー(DeepCopy)を使ってコピーを生成し、コピーの使用が完了したらメモリご解除ください。

「StovePC_SetStat」の関数が実行中にエラーが発生すると「OnError」のコールバックが呼び出されます。

「Stove PC Error」構造体のExternal Errorフィールドで外部エラーを確認できます。

ExternalError 説明
2000 Invalid Access
3000 Wrong API Usage
4000 Stats ID Not Found
9000 Service Error

# 3) ユーザースタット情報を得る

Stove PC_Get Stat関数でログインしたユーザーの該当ゲームの特定のスタット情報を照会します。

// 入力パラメータ
// constchar*statId:Studioで登録したスタット識別子
StovePCResult result = StovePC_GetStat("STAT_ID");
if(result == StovePCResult::STOVE_PC_NO_ERROR)
{
    /* 成功処理 */
}
1
2
3
4
5
6
7

「StovePC_GetStat」の関数が正常に処理されると「OnStat」のコールバックが呼び出されます。

コールバックにお届けする「StovePCtat」構造体には現在のスタット値が含まれています。

void OnStat(const StovePCStat stat)
{
    // スタット情報出力
    printf("OnStat");
    wprintf(L" - stat.statFullId.gameId : %s", stat.statFullId.gameId);
    printf(" - stat.statFullId.statId : %s", stat.statFullId.statId);
    printf(" - stat.memberNo : %llu", stat.memberNo);
    printf(" - stat.currentValue : %d", stat.currentValue);
    printf(" - stat.updatedAt : %llu", stat.updatedAt);
}
1
2
3
4
5
6
7
8
9
10

confirm 注意事項) コールバックパラメータ「StovePCStat」構造体の有効な範囲はコールバックSTOVEのみとなります。 PC SDKはコールバックの実行が終わるとすぐに内部で割り当てたメモリを解除します。 したがって、コールバックSTOVEの外で「StovePCStat」構造体の情報を使用するために保存が必要な場合は、必ず深いコピー(Deep Copy)を使ってコピーを生成し、コピーの使用が完了したらメモリご解除ください。

StovePC_GetStatの関数が実行中にエラーが発生すると、OnErrorのコールバックが呼び出されます。

Stove PC Error構造体のExternal Errorフィールドで外部エラーを確認できます。

ExternalError 説明
2000 Invalid Access
3000 Wrong API Usage
4000 Stats ID Not Found
9000 Service Error

# 4)ユーザー単一業績情報を得る

Stove PC_Get Achievement関数でログインしたユーザーの当該ゲームの特定の単一業績情報を照会します。

// 入力パラメータ
// constchar*achievement Id:Studioで生成した業績識別子
StovePCResult result = StovePC_GetAchievement("ACHIEVEMENT_ID");
if(result == StovePCResult::STOVE_PC_NO_ERROR)
{
    /* 成功処理 */
}
1
2
3
4
5
6
7

StovePC_GetAchievementの関数が正常に処理されると、OnAchievementのコールバックが呼び出されます。

コールバックに配信されるStovePCAchievement構造体には、現在の業績値と業績達成状態、および業績のメタ情報が含まれています。

void OnAchievement(const StovePCAchievement achievement)
{
    // 単一業績情報出力
    printf("OnAchievement");

    printf(" - achievement.achievementId : %s", achievement.achievementId);
    wprintf(L" - achievement.name : %s", achievement.name);
    wprintf(L" - achievement.description : %s", achievement.description);
    wprintf(L" - achievement.defaultImage : %s", achievement.defaultImage);
    wprintf(L" - achievement.achievedImage : %s", achievement.achievedImage);
    printf(" - achievement.condition.goalValue : %d", achievement.condition.goalValue);
    printf(" - achievement.condition.valueOperation : %s", achievement.condition.valueOperation);
    printf(" - achievement.condition.type : %s", achievement.condition.type);
    printf(" - achievement.value : %d", achievement.value);
    printf(" - achievement.status : %s", achievement.status);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

confirm 注意事項) コールバックパラメータ「StovePCAchievement」構造体の有効な範囲はコールバックSTOVEのみとなります。 PC SDKはコールバックの実行が終わるとすぐに内部で割り当てたメモリを解除します。 したがって、コールバックSTOVEの外で「StovePCAchievement」構造体の情報を使用するために保存が必要な場合は、必ずディープコピー(Deep Copy)でコピーを生成し、コピーの使用が完了したらメモリをご解除ください。

StovePC_GetAchievementの関数が実行中にエラーが発生すると、OnErrorのコールバックが呼び出されます。

Stove PC Error構造体のExternal Errorフィールドで外部エラーを確認できます。

ExternalError 説明
1200 Not found achievement
9000 Service Error

# 5) ユーザー全体の業績情報を得る

Stove PC_Get All Achievement関数でログインしたユーザーの当該ゲームのすべての業績情報を照会します。

StovePCResult result = StovePC_GetAllAchievement();
if(result == StovePCResult::STOVE_PC_NO_ERROR)
{
    /* 成功処理 */
}
1
2
3
4
5

StovePC_GetAllAchievementの関数が正常に処理されると、OnAllAchievementのコールバックが呼び出されます。

コールバックに配信される「StovePCAchievement」構造体には、現在の業績値と業績達成状態、および業績のメタ情報が含まれています。

void OnAllAchievement(int size, StovePCAchievement* achievements)
{
    // 全業績情報出力
    printf("OnAllAchievement");
    printf(" - achievements size : %d", size);

    for (int i = 0; i < size; i++, achievements++)
    {
        printf(" - achievements[%d].achievementId : %s", i, achievements->achievementId);
        wprintf(L" - achievements[%d].name : %s", i, achievements->name);
        wprintf(L" - achievements[%d].description : %s", i, achievements->description);
        wprintf(L" - achievements[%d].defaultImage : %s", i, achievements->defaultImage);
        wprintf(L" - achievements[%d].achievedImage : %s", i, achievements->achievedImage);
        printf(" - achievements[%d].condition.goalValue : %d", i, achievements->condition.goalValue);
        printf(" - achievements[%d].condition.valueOperation : %s", i, achievements->condition.valueOperation);
        printf(" - achievements[%d].condition.type : %s", i, achievements->condition.type);
        printf(" - achievements[%d].value : %d", i, achievements->value);
        printf(" - achievements[%d].status : %s", i, achievements->status);
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

confirm 注意事項) コールバックパラメータ「StovePCAchievement」構造体配列の有効な範囲は、コールバック関数スコープに限られます。 PC SDKは、コールバック関数の実行が完了するとすぐに、内部で割り当てたメモリを解除します。 したがって、コールバック関数スコープ外で「StovePCAchievement」構造体配列の情報を使用するために保存が必要な場合は、必ずディープコピー(Deep Copy)を使ってコピーを生成し、コピーの使用が完了したらメモリをご解除ください。

StovePC_GetAllAchievementの関数が実行中にエラーが発生すると、OnErrorのコールバックが呼び出されます。

Stove PC Error構造体のExternal Errorフィールドで外部エラーを確認できます。

ExternalError 説明
9000 Service Error

# 6) リーダーボードランキング情報を得る

「Stove PC_Get Rank」関数で、該当ゲームの特定リーダーボードの順位情報を照会します。

// 入力パラメータ
// const char*leaderboardId:Studioで作成したリーダーボード識別子
// constunsigned int pageIndex : 照会するページ番号 (1 <= pageIndex)
// const unsigned int pageSize : 照会順位の個数 (1 <= pageSize <= 50)
// constbool includeMyRank:照会結果にログインしたユーザーの順位を含むかどうか
StovePCResult result = StovePC_GetRank("LEADERBOARD_ID", PAGE_INDEX, PAGE_SIZE, INCLUDE_MY_RANK);
if(result == StovePCResult::STOVE_PC_NO_ERROR)
{
    /* 成功処理 */
}
1
2
3
4
5
6
7
8
9
10

「StovePC_GetRank」の関数が正常に処理されると「OnRank」のコールバックが呼び出されます。

コールバックに送られる「StovePCRank」構造体には、特定のユーザーの点数と順位情報が含まれます。

// コールバックパラメータ
// unsigned intrankTotalCount:照会したリーダーボードに集計された全体順位数
void OnRank(int size, StovePCRank* ranks, unsigned int rankTotalCount)
{
    // 順位情報出力
    printf("OnRank");
    printf(" - ranks.Length : %d", size);

    for (int i = 0; i < size; i++, ranks++)
    {
        printf(" - ranks[%d].memberNo : %llu", i, ranks->memberNo);
        printf(" - ranks[%d].score : %d", i, ranks->score);
        printf(" - ranks[%d].rank : %u", i, ranks->rank);
        wprintf(L" - ranks[%d].nickname : %s", i, ranks->nickname);
        wprintf(L" - ranks[%d].profileImage : %s", i, ranks->profileImage);
    }

    printf(" - rankTotalCount : %u", rankTotalCount);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

confirm 注意事項) コールバックパラメータ StovePCRank 構造体配列の有効な範囲は、コールバック関数スコープに限定されます。 PC SDKは、コールバック関数の実行が完了するとすぐに、内部で割り当てたメモリを解除します。 したがって、コールバック関数スコープの外で「StovePCRank」構造体配列の情報を使用するために保存が必要な場合は、必ず深いコピー(DeepCopy)を使ってコピーを生成し、コピーの使用が完了したらメモリをご解除ください。

StovePC_GetRankの関数が実行中にエラーが発生すると、OnErrorのコールバックが呼び出されます。

Stove PC Error構造体のExternal Errorフィールドで外部エラーを確認できます。

ExternalError 説明
1251 Invalid Parameter
1252 CannotFindData
3603 ErrorLeaderBoardNotFound
3631 ErrorMembershipAPI
500 External Server Error
Last Updated: 2023/12/14 14:24:57

← ゲーム支援サービスStudioガイド →