リージョンのマッチメイキングを設定する

Last updated on August 29, 2025

Overview

AccelByte Gaming Services (AGS) Matchmaking gives you the ability to allow players to be matched based on geographic region. This article shows you how to implement region-based matchmaking into your game.

Prerequisites

To complete all the steps in this article, you will need:

• A familiarity with AGS Lobby, Matchmaking and Session.
• To have configured a session template, match ruleset, and match pool.
• To have integrated the AGS Game SDK into your game client.

Configure matchmaking request with all available regions

During a matchmaking request, the game client can provide a region list in the latencies field as the preference region for the matchmaking result. The following is an example payload for requesting matchmaking:

POST /match2/v1/namespaces/{namespace}/match-tickets

{
  "attributes": {},
  "latencies": {
    "us-west-2":44,
    "eu-west-2":187,
    "ap-northeast-1":600
  },
  "matchPool": "matchpool_test",
  "sessionID": ""
}

You can get the list of available regions from Quality of Service (QoS) using the following API endpoint:

GET /qosm/public/qos

OSS

// Using the StartMatchmaking() method, 
// the OSS will automatically fill matchmaking tickets with all available QoS regions

// Matchmaking to all regions
TSharedRef<FOnlineSessionSearch> NewSearchHandle = MakeShared<FOnlineSessionSearch>();
NewSearchHandle->QuerySettings.Set(SETTING_SESSION_MATCHPOOL, "5v5bf", EOnlineComparisonOp::Equals);

if (!SessionInterface->StartMatchmaking(TArray<FSessionMatchmakingUser>{{LocalUserId1}}, NAME_GameSession, FOnlineSessionSettings(), NewSearchHandle, OnStartMatchmakingCompleteDelegate))
{
	// Matchmaking failed to start
	return false;
}

Unreal Engine

TArray<TPair<FString, float>> Latencies = AccelByteApiClient->Qos.GetCachedLatencies();

FAccelByteModelsV2MatchTicketOptionalParams Optionals;
Optionals.Latencies = Latencies;

AccelByteApiClient->MatchmakingV2.CreateMatchTicket(MatchPoolName,
		CreateTicketSuccessHandler,
		CreateTicketErrorHandler,
		Optionals);

Unity

var qos = AccelByteSDK.GetClientRegistry().GetApi().GetQos();
var matchmaking = AccelByteSDK.GetClientRegistry().GetApi().GetMatchmakingV2();

string matchPoolName = "match-pool";

// Get latencies
qos.GetAllActiveServerLatencies(result => 
{
    if (result.IsError)
    {
        // Do something if GetAllActiveServerLatencies fails
        Debug.Log($"Error GetAllActiveServerLatencies, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }

    var optionals = new MatchmakingV2CreateTicketRequestOptionalParams()
    {
        latencies = result.Value
    };

    matchmaking.CreateMatchmakingTicket(matchPoolName, optionals, result => 
    {
        if (result.IsError)
        {
            // Do something if CreateMatchmakingTicket fails
            Debug.Log($"Error CreateMatchmakingTicket, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            return;
        }

        // Do something if CreateMatchmakingTicket succeeds
    });
});

Configure matchmaking requests for a specific region

To get a specific region during matchmaking results, the game client can only send one region (latency) when creating a match ticket.

If you're using AccelByte Multiplayer Servers (AMS), ensure that you add the region that you want to use or choose the deployment config regions, which will be used by the session template.

Make sure the region that will be chosen is active in the region setting. To do this, follow these steps:

1. In the AGS Admin Portal, go to AccelByte Multiplayer Servers > QoS Regions.

2. On the QoS Regions page, switch on the Active toggle button of the country you want to set to active.

The following is an example for a game client to always request for matchmaking in the region "us-west-2":

POST /match2/v1/namespaces/{namespace}/match-tickets

{
  "attributes": {},
  "latencies": {
    "us-west-2":44
  },
  "matchPool": "matchpool_test",
  "sessionID": ""
}

OSS

// Region names can be provided by setting the SearchSetting with `SETTING_GAMESESSION_REQUESTEDREGIONS` key

TSharedRef<FOnlineSessionSearch> NewSearchHandle = MakeShared<FOnlineSessionSearch>();
NewSearchHandle->QuerySettings.Set(SETTING_SESSION_MATCHPOOL, "5v5bf", EOnlineComparisonOp::Equals);
// Insert the region you want to lock to here
NewSearchHandle->QuerySettings.Set(SETTING_GAMESESSION_REQUESTEDREGIONS, "us-west-2", EOnlineComparisonOp::Equals);

if (!SessionInterface->StartMatchmaking(TArray<FSessionMatchmakingUser>{{LocalUserId1}}, NAME_GameSession, FOnlineSessionSettings(), NewSearchHandle, OnStartMatchmakingCompleteDelegate))
{
	// Matchmaking failed to start
	return false;
}

Unreal Engine

TArray<TPair<FString, float>> Latencies = AccelByteApiClient->Qos.GetCachedLatencies();
		
FAccelByteModelsV2MatchTicketOptionalParams Optionals;
// Filter the latencies list to only send region us-west-2
Optionals.Latencies = Latencies.FilterByPredicate([](const TTuple<FString, float>& Latency)
{
	return Latency.Key == "us-west-2";
});

AccelByteApiClient->MatchmakingV2.CreateMatchTicket(MatchPoolName,
		CreateTicketSuccessHandler,
		CreateTicketErrorHandler,
		Optionals);

Unity

var qos = AccelByteSDK.GetClientRegistry().GetApi().GetQos();
var matchmaking = AccelByteSDK.GetClientRegistry().GetApi().GetMatchmakingV2();

string matchPoolName = "match-pool";  

// Get latencies
qos.GetAllActiveServerLatencies(result => 
{
    if (result.IsError)
    {
        // Do something if GetAllActiveServerLatencies fails
        Debug.Log($"Error GetAllActiveServerLatencies, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        return;
    }

    // Only select latencies where the key is us-west-2
    Dictionary<string, int> selectedLatencies = (Dictionary<string, int>)result.Value.Where(pair => pair.Key == "us-west-2");

    var optionals = new MatchmakingV2CreateTicketRequestOptionalParams()
    {
        latencies = selectedLatencies
    };

    matchmaking.CreateMatchmakingTicket(matchPoolName, optionals, result => 
    {
        if (result.IsError)
        {
            // Do something if CreateMatchmakingTicket fails
            Debug.Log($"Error CreateMatchmakingTicket, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            return;
        }

        // Do something if CreateMatchmakingTicket succeeds
    });
});

注記

If the preferred region does not have servers ready a server will be claimed from the next best region.