Interface IRelayService#

The Relay Allocations Service enables clients to connect to relay servers. Once connected, they are able to communicate with each other, via the relay servers, using the bespoke relay binary protocol.

Namespace: Unity.Services.Relay#

Syntax#

public interface IRelayService

Methods#

CreateAllocationAsync(Int32, String)#

Creates an allocation on an available relay server. If region is provided, the allocation service will look for a relay server in that region, otherwise, it will use the default region. The allocations service will determine the best available relay server, based upon available capacity and server health for the resolved region. In the event that a relay server could not be found during the lifetime of this request, the caller should retry. This endpoint returns a unique ID for the allocation (which can be used to generate a join code), details of the relay server which was chosen for the allocation, encrypted connection data for the caller and a key required for building the BIND message HMAC.

Declaration#

Task<Allocation> CreateAllocationAsync(int maxConnections, string region = null)

Parameters#

Returns#

Remarks#

The player who creates this allocation, acts as a host. Once the allocation has been created, the host calls GetJoinCode to get a join code which they can then share with other players out of band.

GetJoinCodeAsync(Guid)#

Returns a "join code" for the given allocation ID. A "join code" can be thought of as a short-hand lookup for a clients connection data. The connection data will be retrieved from the clients allocation via a mapping between the allocation ID and the join code. Join codes are intended to be used for players to coordinate themselves into a logical room or session. The player who created the initial allocation, acts as a host. The host calls this method to get a join code which they can then share with other players out of band. The join code can then be used by other players by having them call JoinAllocation in order to connect to a relay server with which they can communicate with the host. The host is not required to make a BIND call to the relay server before generating a join code to share.

Declaration#

Task<string> GetJoinCodeAsync(Guid allocationId)

Parameters#

Returns#

JoinAllocationAsync(String)#

Allows players to join a relay server using a join code. A join code is a shorthand code used to lookup the connection data of the player who created it, referred to as the "host". By performing this lookup, the IP and port of the relay the original player connected to can be determined. The player calling can then be allocated to the same relay. This endpoint returns the details of this allocation and also the connection details of the host player. This can then be used to establish communication with the host.

Declaration#

Task<JoinAllocation> JoinAllocationAsync(string joinCode)

Parameters#

Returns#

ListRegionsAsync()#

Lists all available regions with relay servers. This list is more stable than actual relay server availability, that is, it is not guarantied that there will be a relay server ready to handle allocations in every region listed.

Declaration#

Task<List<Region>> ListRegionsAsync()

Returns#