オンライン サービスにログインすると、オンラインで会ったフレンドやその他のユーザーの情報を探すことがあります。たとえば、多くのオンライン サービスでは、他のユーザーがオンラインなのか、現在どのゲームをプレイしているのか、対戦に参加可能なのかといったことを確認できます。Online Services Presence インターフェース は、ユーザーのプレゼンスのクエリや更新、変更のリッスンなど、オンライン サービス全体のプラットフォームに固有のユーザーの状態に関連するすべての機能をカバーします。
このドキュメントでは、API の概要とコードのサンプル、および Online Subsystem Presence インターフェース からコードを変換するうえでのヒントを示します。
API の概要
関数
次の表は、Presence インターフェースに含まれる関数の概要です。
| 関数 | 説明 |
|---|---|
| クエリ | |
QueryPresence |
指定された TargetAccountId を持つユーザーのプレゼンスをフェッチします。 |
BatchQueryPresence |
指定された TargetAccountIds のリストに含まれるすべてのユーザーのプレゼンスをフェッチします。 |
| 取得 | |
GetCachedPresence |
インターフェースにキャッシュされている、指定された TargetAccountId を持つユーザーのプレゼンスを取得します。 |
| 更新 | |
UpdatePresence |
ユーザーのプレゼンスを更新します。 |
PartialUpdatePresence |
指定されたプレゼンス設定のみでユーザーのプレゼンスを更新します。 |
| イベントのリッスン | |
OnPresenceUpdated |
ユーザーのプレゼンスを更新した結果としてイベントがトリガーされます。 |
列挙型クラス
Presence インターフェースは、ユーザーのステータス、参加可否、およびゲーム ステータスを表す 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() でエラー状態を確認してください;
}
});
ウォークスルー
-
どちらのユーザーも、次のようにパラメータを指定することなく
GetServicesを呼び出してデフォルトのオンライン サービスを取得し、Presence インターフェースにアクセスします。UserAPresence.cpp and UserBPresence.cpp
UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices(); UE::Online::IPresencePtr PresenceInterface = OnlineServices->GetPresenceInterface(); -
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")); -
UserAが、UpdatePresenceに渡されるパラメータでParamsという名前のFUpdatePresence::Params構造体を初期化します。UserAPresence.cpp
UE::Online::FUpdatePresence::Params Params; Params.LocalAccountId = AccountId; Params.Presence = Presence; -
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()でエラー状態を確認してください; } }); -
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()) { // we succeeded - now use GetPresence to actually view the presence object 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」は、次のディレクトリにあります。
UNREAL_ENGINE_ROOT\Engine\Plugins\Online\OnlineServices\Source\OnlineServicesInterface\Public\Online
UE のソース コードの入手方法については、「Unreal Engine のソース コードをダウンロードする」のドキュメントを参照してください。
関数パラメータおよび戻り型
関数パラメータおよび戻り型 (パラメータの渡し方、関数が戻す結果の処理など) については、「Online Services の概要」ページの「関数」セクションを参照してください。