メインコンテンツまでスキップ

ゲームサーバーにフルフィルメントを実装する

Last updated on November 4, 2026

注釈:本資料はAI技術を用いて翻訳されています。

概要​

この記事では、コード引き換えの実装方法と、ゲームサーバーがプレイヤーにアイテムを付与できるようにする方法について説明します。

コード引き換え​

プレイヤーはキャンペーンコードを引き換えて、ゲーム、ゲーム内アイテム、コインなどのエンタイトルメントを受け取ることができます。コードを引き換えるには、Fulfillment API の RedeemCode を呼び出します。次の条件を満たすと、コードが引き換えられ、プレイヤーはエンタイトルメントを受け取ります。

  • コードがゲームネームスペースに存在する
  • 最大引き換え回数に達していない
  • 引き換えの日時が引き換え期間内である
FString Code = FString("MyRedeemCode");
FString Region = FString("US"); // Leave it blank if you want to use the default value from user token
FString Language = FString("en"); // Leave it blank if you want to use the default value from user token

auto ApiClient = AccelByteOnlineSubsystemPtr->GetApiClient();
auto FulfillmentApi = ApiClient->GetFulfillmentApi().Pin();

FulfillmentApi->RedeemCode(Code, Region, Language, THandler<FAccelByteModelsFulfillmentResult>::CreateLambda([](const FAccelByteModelsFulfillmentResult& Result)
{
// Do something if RedeemCode succeeds
}),
FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if RedeemCode fails
UE_LOG(LogTemp, Log, TEXT("Error RedeemCode, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

ゲームサーバーがプレイヤーにアイテムを付与する​

信頼できるゲームサーバーまたはバックエンドからアイテムを付与するには、Fulfillment V3 を使用します。

PUT /platform/v3/admin/namespaces/{namespace}/users/{userId}/fulfillments/{transactionId}

対象の環境がこのエンドポイントをサポートしている必要があります。ADMIN:NAMESPACE:{namespace}:USER:{userId}:FULFILLMENT 権限と UPDATE アクション(2)を持つサーバーアクセストークンを使用してください。従来の CREATE 権限のみが設定されているクライアントには、この権限を追加する必要があります。サーバーの認証情報をゲームクライアントに含めないでください。

リクエストを送信する前に、論理的な付与処理ごとにトランザクション ID を生成し、永続化してください。その付与処理を再試行するときは、同じ ID とペイロードを使用します。ユーザー、アイテム、数量が同じでも、新しい報酬には新しい ID を使用する必要があります。再試行のたびに新しい ID を生成しないでください。

このエンドポイントは FulfillmentV2Request を受け取り、FulfillmentV2Result を返します。モデル名によってエンドポイントのバージョンが変わるわけではありません。FulfillmentV3Request は、別の一括処理用エンドポイントでのみ使用してください。

統合方法を選択する​

以下の公開済み Extend SDK バージョンには、後述の例で使用するメソッドが含まれています。これらは検証済みの参照バージョンであり、V3 が初めて導入された最小バージョンを示すものではありません。各 SDK のインストール手順に従い、アップグレード前に互換性を確認してください。

統合方法公開済みの参照バージョン付与メソッド
Go Extend SDKv0.89.1FulfillmentService.FulfillItemsV3Short
Java Extend SDKv0.82.0Fulfillment.fulfillItemsV3
C# Extend SDKv0.81.0Fulfillment.FulfillItemsV3
Python Extend SDKv0.85.1platform.fulfill_items_v3

Unreal SDK 28.10.1 と Unity SDK 17.17.1 の FulfillUserItem は、引き続き非推奨の V1 エンドポイントを呼び出します。V3 を使用するには、信頼できるサーバーから以下の REST リクエストを送信するか、Extend SDK で実装したバックエンドを呼び出してください。リクエストとレスポンスの構造が異なるため、V1 SDK メソッドの URL を V3 の URL に置き換えないでください。

REST リクエスト​

以下の環境変数をサーバーの値に置き換えてください。AB_BASE_URL は /platform を含まない環境の URL、AB_ACCESS_TOKEN はサーバーアクセストークンです。AB_ITEM_ID をカタログのアイテム ID に、AB_TRANSACTION_ID を今回の付与処理のために永続化した ID に置き換えてください。

curl --fail-with-body --request PUT \
"${AB_BASE_URL}/platform/v3/admin/namespaces/${AB_NAMESPACE}/users/${AB_USER_ID}/fulfillments/${AB_TRANSACTION_ID}" \
--header "Authorization: Bearer ${AB_ACCESS_TOKEN}" \
--header 'Content-Type: application/json' \
--data "{\"items\":[{\"itemId\":\"${AB_ITEM_ID}\",\"quantity\":1,\"source\":\"REWARD\"}]}"

HTTP 200 レスポンスでも、トランザクションの一部が失敗している場合があります。結果を処理するの説明に従い、state と stateInfo を確認してください。

Extend SDK の例​

以下の例では、対象環境で認証済みの sdk または fulfillmentService が初期化されていることを前提とします。プレースホルダーをネームスペース、プレイヤー ID、アイテム ID、永続化したトランザクション ID に置き換えてください。SDK の例外や返されたエラーは、アプリケーションのエラー処理方針に従って処理してください。

using System;
using System.Collections.Generic;
using AccelByte.Sdk.Api.Platform.Model;
using AccelByte.Sdk.Api.Platform.Operation;

var body = new FulfillmentV2Request
{
Items = new List<FulfillmentV2RequestItem>
{
new FulfillmentV2RequestItem
{
ItemId = "<ItemId>",
Quantity = 1,
Source = FulfillmentV2RequestItemSource.REWARD
}
}
};
var operation = FulfillItemsV3.Builder.Build(
body, "<YourNamespace>", "<PersistedTransactionId>", "<PlayerUserId>");
var result = sdk.Platform.Fulfillment.FulfillItemsV3(operation);
if (result == null || result.State != FulfillmentV2ResultState.FULFILLED)
{
// Inspect StateInfo and classify the failure before retrying.
throw new InvalidOperationException("Fulfillment is incomplete; inspect the transaction.");
}

結果を処理する​

  • state == "FULFILLED" は、トランザクションの完了を示します。entitlementSummaries が空でも失敗を意味しません。完了済みのトランザクションでは新たな付与は返されず、アイテムタイプによっては別のサマリーが使用されます。
  • FULFILL_FAILED の場合は、stateInfo.failedList とその中のバンドルの items を調べて、エラーを確認してください。処理に成功した構成アイテムは、付与済みのまま残る場合があります。再試行の前に原因を修正し、永続的な設定エラーに対して無制限に再試行しないでください。
  • Retry Fulfillment V3 を使用すると、リクエストボディを再送せずに、保存済みのトランザクションを再試行できます。または、同じトランザクション ID とペイロードで元の付与リクエストを再送してください。成功状態が保存されている構成アイテムはスキップされます。
  • アセットの書き込みとフルフィルメント状態の永続化は、アトミックな処理ではありません。処理が中断された場合やネットワーク障害で結果が不明な場合は、再試行する前にトランザクションと付与済みアセットを照合してください。V3 は、無条件に厳密に 1 回だけ実行されることを保証するものではありません。

サポートされるアイテムタイプ、リクエストフィールド、トランザクションのクエリ、取り消しの制限については、サードパーティストアでアイテムのフルフィルメントを管理するを参照してください。