Record and exclude sessions from matchmaking

Last updated on January 15, 2025

注記

This article covers handling session exclusions in an Unreal Engine game project. If you're using Unity, refer to the Integrate matchmaking (Unity) guide.

Overview

AccelByte Gaming Services (AGS) provides features to prevent players from being repeatedly matched into the same sessions. The AGS Matchmaking service allows for the exclusion of specific sessions from matchmaking results, while the AGS Unreal Engine OSS can be used to record player session histories. This combined functionality enables your game to prevent matching players in sessions they have previously participated in.

This article walks you through how to enable the following functions in your game:

• Enable players to record their session history
• Retrieve, modify, and reset player session history
• Enable players and party leaders to exclude sessions from matchmaking results

Record session history

To enable players in your game to record their session history (sessions since they launch the game), add the SetEnablePartyMemberPastSessionRecordSync function:

void ExampleLoginManagerClass::OnUserLoginSuccess()
{
    uint32 PastGameSessionIdRecordCount = 20; // The amount of past game session ID that will be recorded to memory, number is just an example.
    SessionInterface->SetEnablePartyMemberPastSessionRecordSync(true, PastGameSessionIdRecordCount);
}

When enabled, it automatically records the player's session history locally on their device from the moment the game is launched. The session records are cleared when the game is closed. Players can enable or disable this function at any time according to their preferences.

注記

• Call this function after the game is launched and the online subsystem (OSS) is loaded. The above sample code establishes this.
• This function operates at the individual player level. Players who disable this function and are members of a party will not have their session history synchronized with the party, even if other members have it enabled.
• The code above specifies that the player's last 20 sessions will be recorded. You can adjust the PastGameSessionIdRecordCount value to match the desired number of past sessions to record. Keep in mind that higher values will result in a larger payload.

Exclude sessions from matchmaking

You can provide players and party leaders the option to exclude past and specific sessions from matchmaking results. The Matchmaking service supports the following exclusion types, applicable at both individual player and party levels:

• Type 1: Exclude specific sessions

  FAccelByteModelsGameSessionExcludedSession::CreateExclusionList(TSet<FString> SetOfExcludedGameSessionId);
• Type 2: Exclude all past sessions

  FAccelByteModelsGameSessionExcludedSession::CreateExclusionEntireSessionMemberPastSession();
• Type 3: Exclude a specific number of most recent sessions

  FAccelByteModelsGameSessionExcludedSession::CreateExclusionCount(ExcludedPastSessionCount);
• Type 4: No Exclusion

  FAccelByteModelsGameSessionExcludedSession::CreateNoExclusion();

important

For the Type 2 and 3 exclusion methods, players must enable session history recording to exclude sessions. To learn how to enable the function, refer to the Record session history section.

For individual players

You can enable the following exclusion methods for individual players:

Exclude specific game sessions

To prevent players from joining specific game sessions, specify the IDs of the excluded sessions in this code:

TSet<FString> ListOfExcludedSession{};
ListOfExcludedSession.Add("GAMESESSION_ID_AAA"); // Example of avoided session
ListOfExcludedSession.Add("GAMESESSION_ID_BBB"); // Example of avoided session
ListOfExcludedSession.Add("GAMESESSION_ID_CCC"); // Example of avoided session
MatchmakingSearchHandle->GameSessionExclusion = FAccelByteModelsGameSessionExcludedSession::CreateExclusionList(ListOfExcludedSession);

SessionInterface->StartMatchmaking(USER_ID_TO_MATCHMAKING_USER_ARRAY(LocalPlayerId.ToSharedRef()), NAME_GameSession, FOnlineSessionSettings(), MatchmakingSearchHandle, OnStartMatchmakingCompleteDelegate);

Exclude all past sessions

important

This function applies only to players who have enabled session history recording, as it relies on session histories to determine which sessions to exclude. Ensure that the session history recording feature is integrated into your game. For more information, refer to the Record session history section.

To prevent players from joining any of their past sessions since launching the game, use this code:

// On User Login Success
SessionInterface->SetEnablePartyMemberPastSessionRecordSync(true, 20);
    ...

MatchmakingSearchHandle->GameSessionExclusion = FAccelByteModelsGameSessionExcludedSession::CreateExclusionEntireSessionMemberPastSession();

SessionInterface->StartMatchmaking(USER_ID_TO_MATCHMAKING_USER_ARRAY(LocalPlayerId.ToSharedRef()), NAME_GameSession, FOnlineSessionSettings(), MatchmakingSearchHandle, OnStartMatchmakingCompleteDelegate);

Exclude specific number of most recent sessions

important

This function applies only to players who have enabled session history recording, as it relies on session histories to determine which sessions to exclude. Ensure that the session history recording feature is integrated into your game. For more information, refer to the Record session history section.

To prevent players from joining a specific number of their most recent sessions, use the code snippet below. Specify the number of sessions to exclude using the ExcludedPastSessionCount parameter. For example, the following code excludes the player's last five sessions from matchmaking results.

// On User Login Success
SessionInterface->SetEnablePartyMemberPastSessionRecordSync(true, 20);
...

const uint32 ExcludedPastSessionCount = 5;
MatchmakingSearchHandle->GameSessionExclusion = FAccelByteModelsGameSessionExcludedSession::CreateExclusionCount(ExcludedPastSessionCount);

SessionInterface->StartMatchmaking(USER_ID_TO_MATCHMAKING_USER_ARRAY(LocalPlayerId.ToSharedRef()), NAME_GameSession, FOnlineSessionSettings(), MatchmakingSearchHandle, OnStartMatchmakingCompleteDelegate);

For party leaders

important

Any exclusion applied by the party leader will be based on the records of members who have enabled session history recording, as the exclusion methods rely on these histories to determine which sessions to exclude. Ensure that the session history recording feature is integrated into your game. For more information, refer to the Record session history section.

You can enable the following exclusion methods for party leaders:

Exclude specific game sessions

To prevent members from joining specific game sessions, specify the IDs of the excluded sessions in this code:

TSet<FString> ListOfExcludedSession{};
ListOfExcludedSession.Add("GAMESESSION_ID_AAA"); // Example of avoided session
ListOfExcludedSession.Add("GAMESESSION_ID_BBB"); // Example of avoided session
ListOfExcludedSession.Add("GAMESESSION_ID_CCC"); // Example of avoided session
MatchmakingSearchHandle->GameSessionExclusion = FAccelByteModelsGameSessionExcludedSession::CreateExclusionList(ListOfExcludedSession);

SessionInterface->StartMatchmaking(USER_ID_TO_MATCHMAKING_USER_ARRAY(LocalPlayerId.ToSharedRef()), NAME_GameSession, FOnlineSessionSettings(), MatchmakingSearchHandle, OnStartMatchmakingCompleteDelegate);

Exclude all members' past sessions

To enable party leaders to exclude all of their members' past sessions from the matchmaking results, add this function:

// On successful player login
/*Leader game client*/SessionInterface->SetEnablePartyMemberPastSessionRecordSync(true, PastSessionCount);
/*Member1 game client*/SessionInterface->SetEnablePartyMemberPastSessionRecordSync(true, PastSessionCount);
/*Member2 game client*/SessionInterface->SetEnablePartyMemberPastSessionRecordSync(true, PastSessionCount);
...

// The main toggle for the party leader to enable this feature
// Example if the leader wants to only exclude the five MOST RECENT SESSION from each party member's record
const uint32 ExcludedPastSessionCount = 5;
MatchmakingSearchHandle->GameSessionExclusion = FAccelByteModelsGameSessionExcludedSession::CreateExclusionCount(ExcludedPastSessionCount);

SessionInterface->StartMatchmaking(USER_ID_TO_MATCHMAKING_USER_ARRAY(LocalPlayerId.ToSharedRef()), NAME_GameSession, FOnlineSessionSettings(), MatchmakingSearchHandle, OnStartMatchmakingCompleteDelegate);

Exclude specific number of the members' most recent sessions

To enable party leaders to exclude a specific number of their members' most recent sessions, add this function:

// On User Login Success
/*Leader game client*/SessionInterface->SetEnablePartyMemberPastSessionRecordSync(true, PastSessionCount);
/*Member1 game client*/SessionInterface->SetEnablePartyMemberPastSessionRecordSync(true, PastSessionCount);
/*Member2 game client*/SessionInterface->SetEnablePartyMemberPastSessionRecordSync(true, PastSessionCount);
...

// The main toggle for the party leader to enable this feature
// Example if the leader wants to only include the five MOST RECENT SESSION from each party member's record
const uint32 ExcludedPastSessionCount = 5;
MatchmakingSearchHandle->GameSessionExclusion = FAccelByteModelsGameSessionExcludedSession::CreateExclusionCount(ExcludedPastSessionCount);

SessionInterface->StartMatchmaking(USER_ID_TO_MATCHMAKING_USER_ARRAY(LocalPlayerId.ToSharedRef()), NAME_GameSession, FOnlineSessionSettings(), MatchmakingSearchHandle, OnStartMatchmakingCompleteDelegate);

Enable party leaders to retrieve and modify member session history

The AGS Matchmaking service can be configured to allow party leaders to override the general exclusion of past sessions. Party leaders can review their members' session histories and specifically whitelist certain sessions by removing them from their records.

To enable this, implement the following code

// Obtain the storage, asynchronously
    SessionInterface->GetPartySessionStorage(AccelByteUserUniqueNetId,
        FOnGetPartySessionStorageComplete::CreateLambda([&]
        (const FAccelByteModelsV2PartySessionStorage& Result, bool bWasSuccessful) {
            bGetSessionStorageDone = true;
            bGetSessionStorageSuccess = bWasSuccessful;
            PartySessionStorageResult = Result;
        }));

// Wait for response
WaitUntil(bGetSessionStorageDone);

// Check the content, iterate as we wish.
Map<FString /*UserID*/, FAccelByteModelsV2PartySessionStorageReservedData> MapOfPartyMemberStorage = PartySessionStorageResult.Reserved;

Retrieve, modify, and reset player session history

As session histories are stored locally on a player's device, they cannot be modified directly. However, you can use the class responsible for managing session histories to insert, retrieve, or reset a player's local records. Once updated, you can synchronize these changes as needed.

Use the following function:

// INSERT MANUALLY
SessionInterface->PartySessionStorageLocalUserManager.PastSessionManager.InsertPastSessionID(UniqueNetIdRefs, "DummySession1");

// RESET ENTIRE ENTRY
SessionInterface->PartySessionStorageLocalUserManager.PastSessionManager.ResetCachedPastSessionIDs(UniqueNetIdRefs);

// GET CURRENT PLAYER's ENTRY
SessionInterface->PartySessionStorageLocalUserManager.PastSessionManager.GetPastSessionIDs(UniqueNetIdRefs);

To apply your changes to a player's record and synchronize them with the player's party (if applicable), use the following function:

// Result listener
ForceUpdateHandle = SessionInterface->AddOnUpdatePlayerReservedPartySessionStorageCompleteDelegate_Handle(
    FOnUpdatePlayerReservedPartySessionStorageCompleteDelegate::CreateLambda([&](const FAccelByteModelsV2PartySessionStorageReservedData& Result, bool bWasSuccessful, const FOnlineError& ErrorInfo)
            {
                bForceUpdateDone = true;
                SessionInterface->ClearOnUpdatePlayerReservedPartySessionStorageCompleteDelegate_Handle(ForceUpdateHandle);
                bForceUpdateSuccess = bWasSuccessful;
                ForceUpdateResult = Result;
            }));
....

// Do the modification similar to the example INSERT/RESET/GET
SessionInterface->PartySessionStorageLocalUserManager.PastSessionManager.......

// Send the update to the party
bool bRequestOkToUpdatePartyStorage = SessionInterface->UpdatePartySessionStorageWithPastSessionInfo(
    FUniqueNetIdAccelByteUser::Create(UniqueNetIdRefs.Get()));

...
// Wait until (bForceUpdateDone == true)