1. Epic GamesDeveloper
  3. Presence インターフェース

Presence インターフェース

フレンドとフォロワーのプレゼンスと参加可否ステータスにアクセスします。

Presence インターフェース
Learn to use this Beta feature, but use caution when shipping with it.

オンライン サービスにログインすると、オンラインで会ったフレンドやその他のユーザーの情報を探すことがあります。たとえば、多くのオンライン サービスでは、他のユーザーがオンラインなのか、現在どのゲームをプレイしているのか、対戦に参加可能なのかといったことを確認できます。Online Services Presence インターフェース は、ユーザーのプレゼンスのクエリや更新、変更のリッスンなど、オンライン サービス全体のプラットフォームに固有のユーザーの状態に関連するすべての機能をカバーします。

このドキュメントでは、API の概要とコードのサンプル、および Online Subsystem Presence インターフェース からコードを変換するうえでのヒントを示します。

API の概要

関数

次の表は、Presence インターフェースに含まれる関数の概要です。

関数 説明
クエリ  
QueryPresence 指定された TargetAccountId を持つユーザーのプレゼンスをフェッチします。
BatchQueryPresence 指定された TargetAccountIds のリストに含まれるすべてのユーザーのプレゼンスをフェッチします。
取得  
GetCachedPresence インターフェースにキャッシュされている、指定された TargetAccountId を持つユーザーのプレゼンスを取得します。
更新  
UpdatePresence ユーザーのプレゼンスを更新します。
PartialUpdatePresence 指定されたプレゼンス設定のみでユーザーのプレゼンスを更新します。
イベントのリッスン  
OnPresenceUpdated ユーザーのプレゼンスを更新した結果としてイベントがトリガーされます。

列挙型クラス

Presence インターフェースは、ユーザーのステータス (EUserPresenceStatus)、参加可否 (EUserPresenceJoinability)、およびゲーム ステータス (EUserPresenceGameStatus)を表す 3 つの列挙型クラスを定義します。これらの列挙型クラスは、FUserPresence 構造体の 3 つのプライマリ メンバーを表します。詳細については、このページの「プライマリ構造体」セクションを参照してください。

EUserPresenceStatus

列挙子 説明
Offline ユーザーはオフラインです。
Online ユーザーはオンラインです。
Away ユーザーは離席中です。
ExtendedAway ユーザーは少なくとも 2 時間離席しています (プラットフォームによって異なる場合があります)。
DoNotDisturb ユーザーは邪魔されたくないと思っています。
Unknown デフォルトのユーザー プレゼンスのステータスです。

EUserPresenceJoinability

列挙子 説明
Public 誰でもこのセッションを探して参加できます。
FriendsOnly 参加しようとするユーザーは、必ずロビー メンバーのフレンドでなければなりません。
InviteOnly 参加しようとするユーザーは、最初に招待される必要があります。
Private 現時点でユーザーは招待に応じていません。
Unknown デフォルトのユーザー プレゼンスの参加可否ステータスです。

EUserPresenceGameStatus

列挙子 説明
PlayingThisGame ユーザーはあなたと同じゲームをプレイしています。
PlayingOtherGame ユーザーはあなたとは別のゲームをプレイしています。
Unknown デフォルトのユーザー プレゼンスのゲーム ステータスです。

プライマリ構造体

FUserPresence

FUserPresence 構造体は Presence インターフェースのプライマリ オブジェクトであり、ユーザーのプレゼンスに関するすべての必須情報で構成されています。

メンバー 型 説明
AccountId FAccountId このプレゼンスのユーザーです。
Status EUserPresenceStatus ユーザーのプレゼンスの状態です(デフォルト値は EUserPresenceStatus::Unknown です)。
Joinability EUserPresenceJoinability ユーザーのセッションの状態です(デフォルト値は EUserPresenceJoinability::Unknown です)。
GameStatus EUserPresenceGameStatus ユーザーのゲームの状態です(デフォルト値は EUserPresenceGameStatus::Unknown です)。
StatusString FString ユーザーのプレゼンスの状態の文字列表現です。
RichPresenceString FString ゲームで定義された現在のゲームの状態の表現です。
Properties FPresenceProperties セッション キーです。

型 FPresenceProperties は TMap<FString, FPresenceVariant> の typedef であり、FPresenceVariant は FString です。

例

ここで、UpdatePresence、QueryPresence、および GetPresence の例を示します。UserA がデフォルトのプラットフォーム サービスでプレゼンスを更新し、更新後に UserB が UserA のプレゼンスをクエリします。そしてクエリが正常に返されると、UserB が UserA のプレゼンスを取得します。

コード

UserAPresence.cpp

	UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices();
	UE::Online::IPresencePtr PresenceInterface = OnlineServices->GetPresenceInterface();

	TSharedRef<UE::Online::FUserPresence> Presence = MakeShared<UE::Online::FUserPresence>();
	Presence->AccountId = UserA;
	Presence->Status = UE::Online::EUserPresenceStatus::Online;
	Presence->Joinability = UE::Online::EUserPresenceJoinability::Public;
	Presence->RichPresenceString = TEXT("Exploring the Great Citadel");
	Presence->Properties.Add(TEXT("advanced_class"), TEXT("advanced_class_assassin"));

	UE::Online::FUpdatePresence::Params Params;
	Params.LocalAccountId = AccountId;
	Params.Presence = Presence;

	PresenceInterface->UpdatePresence(MoveTemp(Params))
	.OnComplete([](const UE::Online::TOnlineResult<UE::Online::FUpdatePresence> Result)
	{
		if(Result.IsOk())
		{
		// 成功しました - UserBはクエリに対してクリアになりました
		}
		else
		{
		// 失敗しました - Result.GetErrorValue()でエラー状態を確認します;
	}
});

UserBPresence.cpp

	UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices();
	UE::Online::IPresencePtr PresenceInterface = OnlineServices->GetPresenceInterface();

	PresenceInterface->QueryPresence({UserA})
	.OnComplete([](const UE::Online::TOnlineResult<UE::Online::FQueryPresence> Result)
	{
		if(Result.IsOk())
		{
			// 成功しました - 次は GetPresence を使って実際にプレゼンスオブジェクトを表示します

		UE::Online::TOnlineResult<UE::Online::FGetPresence> GetPresenceResult = PresenceInterface->GetPresence({UserB});
		if(GetPresenceResult.IsOk())
		{
			TSharedRef<const UE::Online::FUserPresence> Presence = GetPresenceResult.GetOkValue().Presence;

			// Presence->RichPresenceStringは "Exploring the Great Citadel "になりました。
			// Presence->Properties に {advanced_class: advanced_class_assassin} が含まれるようになりました
			// など
		}
		else
		{
			// 失敗しました - GetPresenceResult.GetErrorValue() でエラー状態を確認してください;
		}

	}
	else
	{
		// 失敗しました -  Result.GetErrorValue() でエラー状態を確認してください;
	}
});

ウォークスルー

  1. どちらのユーザーも、次のようにパラメータを指定することなく GetServices を呼び出してデフォルトのオンライン サービスを取得し、Presence インターフェースにアクセスします。

    UserAPresence.cpp and UserBPresence.cpp

         UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices();
     UE::Online::IPresencePtr PresenceInterface = OnlineServices->GetPresenceInterface();

  2. UserA が、Presence という名前の FUserPresence 構造体を初期化します。ここでは、Presence インターフェースで提供される、前述の列挙型 EUserPresenceStatus と EUserPresenceJoinability の 2 つを使用しているということに注意してください。

    UserAPresence.cpp

         TSharedRef<UE::Online::FUserPresence> Presence = MakeShared<UE::Online::FUserPresence>();
     Presence->AccountId = UserA;
     Presence->Status = UE::Online::EUserPresenceStatus::Online;
     Presence->Joinability = UE::Online::EUserPresenceJoinability::Public;
     Presence->RichPresenceString = TEXT("Exploring the Great Citadel");
     Presence->Properties.Add(TEXT("advanced_class"), TEXT("advanced_class_assassin"));

  3. UserA が、UpdatePresence に渡されるパラメータで Params という名前の FUpdatePresence::Params 構造体を初期化します。

    UserAPresence.cpp

     UE::Online::FUpdatePresence::Params Params;
 Params.LocalAccountId = AccountId;
 Params.Presence = Presence;

  4. UserA が UpdatePresence を呼び出し、OnComplete のコールバックで結果を処理します。

    UserAPresence.cpp

     PresenceInterface->UpdatePresence(MoveTemp(Params))
 .OnComplete([](const UE::Online::TOnlineResult<UE::Online::FUpdatePresence> Result)
 {
     if(Result.IsOk())
     {
         // 成功しました - UserBはクエリに対してクリアになりました
     }
     else
     {
         // 失敗しました - Result.GetErrorValue()でエラー状態を確認してください;
     }
 });

  5. UserB が UserA のプレゼンスをクエリます。クエリの OnComplete のコールバック内では、UserB はまず、QueryPresence によって「Ok」のステータスが返されたかどうかをチェックします。返されている場合、UserB は UserA のプレゼンスを取得し、GetPresence の結果かエラーを適切に処理できます。

    UserBPresence.cpp

     PresenceInterface->QueryPresence({UserA})
 .OnComplete([](const UE::Online::TOnlineResult<UE::Online::FQueryPresence> Result)
 {
     if(Result.IsOk())
     {
             // 成功しました - GetPresence を使用して実際にプレゼンス オブジェクトを表示します。

         UE::Online::TOnlineResult<UE::Online::FGetPresence> GetPresenceResult = PresenceInterface->GetPresence({UserB});
         if(GetPresenceResult.IsOk())
         {
             // 成功しました！
         }
         else
         {
             //  失敗しました - GetPresenceResult.GetErrorValue()でエラー状態を確認してください;
         }

     }
     else
     {
         // 失敗しました - Result.GetErrorValue()でエラー状態を確認してください;
         }
     });

すべての関数がエラーなく戻り値を呼び出すと、UserB には、このステータスに基づいて UserA と UserB の更新されたステータスで判断を下せるということが示されます。たとえば UserB は、GetPresenceResult にアクセスして UserA がオンラインであることと参加可否ステータスが public であることを確認することが可能です。このステータスを設定すると、UserB は UserA を参加させて一緒に「Great Citadel を探索する」ことを決定できます。

Online Subsystem からコードを変換する

Online Services プラグインは Online Subsystem プラグインの最新バージョンであり、近い将来に並行して使用されるようになる予定です。Online Services Presence インターフェースの API 機能は、Online Subsystem Presence インターフェースの API 機能とほぼ 1 対 1 でマッピングされますが、次のような注意事項があります。

  • 関数の非同時性をより的確に表すために、SetPresence は UpdatePresence に名称変更されました。
  • UpdatePresence と QueryPresence はオーバーロードされなくなりました。
  • 代わりに名称変更された関数 PartialUpdatePresence と BatchQueryPresence を使用することをお勧めします。
    • UpdatePresence と QueryPresence のオーバーロードはそれぞれ、PartialUpdatePresence と BatchQueryPresence に名称変更されました。
  • QueryPresence に bListenToChanges パラメータが指定されました。
    • これにより、特定のユーザーが OnPresenceUpdated イベントに追加されます。
    • このパラメータは、デフォルトで true に設定されています。

詳細情報

ヘッダ ファイル

必要に応じて、Presence.h ヘッダ ファイルで直接詳細を確認してください。Presence インターフェースのヘッダ ファイル「Presence.h」は、次のディレクトリにあります。

Engine\Plugins\Online\OnlineServices\Source\OnlineServicesInterface\Public\Online

UE のソース コードの入手方法については、「Unreal Engine のソース コードをダウンロードする」のドキュメントを参照してください。

関数パラメータおよび戻り型

関数パラメータおよび戻り型 (パラメータの渡し方、関数が戻す結果の処理など) については、「Online Services の概要」ページの「関数」セクションを参照してください。

Ask questions and help your peers Developer Forums

Write your own tutorials or read those from others Learning Library

On this page
Related documents