タイトルで管理される実績の更新

[アーティクル]
05/09/2023

このトピックでは、以下の内容を説明します。

実績のロックを解除する
実績の進行状況を更新する

実績のロックを解除する

パートナーセンターで実績を構成し、開発サンドボックスに公開した後は、タイトルで XblAchievementsUpdateAchievementAsync API を呼び出すことにより実績のロックを解除できます。詳細については、次のセクションのサンプルコードを参照してください。

実績のロックを解除するには、percentComplete を 100 に設定します。ユーザーがオンラインの場合、要求は Xbox サービス実績サービスに直ちに送信されて、次のユーザーエクスペリエンスをトリガーします。

ユーザーは実績ロック解除通知を受け取ります。
タイトルのユーザーの実績リストで、通知に示されている実績がロック解除として示されます。
ロック解除された実績は、ユーザーのアクティビティフィードに追加されます。

注意

ユーザーエクスペリエンスは、イベントに基づく実績またはタイトルで管理される実績のいずれかを使用する実績でも視覚的に同様です。

ユーザーがオフラインの場合、ロック解除要求はユーザーのデバイス上のローカルのキューに入れられます。これがネットワークとの接続を再び確立すると、要求が実績サービスに自動的に送信され (これをトリガーするためにゲームから行う必要があるアクションはありません)、前述のユーザーエクスペリエンスが発生します。

実績の進行状況を更新する

実績ロック解除に向けたユーザーの進行状況の更新を行うには、XblAchievementsUpdateAchievementAsync を呼び出します。 percentComplete 引数を 1 〜 100 の間の整数に設定します。詳細については、次のサンプルコードを参照してください。

実績の完了率の値は、増加のみが許可されます。 percentComplete が実績の最後の percentComplete 値よりも小さい数値に設定されている場合、更新は無視されます。たとえば、実績の percentComplete が以前 75 に設定されていた場合、値が 25 の更新の送信は無視されます。実績は 75％完了として表示されます。

percentComplete が 100 に設定されている場合、実績のロックが解除されます。

percentComplete が 100 より大きい数値に設定されている場合、API は数値を正確に 100 に設定したかのように動作します。

現在のタイトルの実績を更新する

現在のタイトルの実績を更新するには、次のように XblAchievementsUpdateAchievementAsync を呼び出します。

フラット C API

auto asyncBlock = std::make_unique<XAsyncBlock>();
asyncBlock->queue = queue;
asyncBlock->context = nullptr;
asyncBlock->callback = [](XAsyncBlock* asyncBlock)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ asyncBlock }; // Take over ownership of the XAsyncBlock*.
    auto result = XAsyncGetStatus(asyncBlock, false);
    if (SUCCEEDED(result))
    {
        // The achievement was updated.
    }
    else if (result == HTTP_E_STATUS_NOT_MODIFIED)
    {
        // The achievement wasn't updated.
    }
    else
    {
        // The achievement failed to update.
    }
};

HRESULT hr = XblAchievementsUpdateAchievementAsync(
    xboxLiveContext,
    xboxUserId,
    achievementId.c_str(),
    percentComplete,
    asyncBlock.get()
);
if (SUCCEEDED(hr))
{
    // The call succeeded, so release the std::unique_ptr ownership of XAsyncBlock* because the callback will take over ownership.
    // If the call fails, std::unique_ptr will keep ownership and delete XAsyncBlock*.
    asyncBlock.release();
}

詳細については、以下を参照してください。

異なるタイトルの実績を更新する

別の titleId の実績を更新するには、次のように XblAchievementsUpdateAchievementForTitleIdAsync を使用します。