Api use examples

Friends

A friend is a player that has a relationship with another player in a Unity experience. Players can send and receive friend requests, ignore friend requests, accept friend requests, remove friends, and get a list of their friends. If two players consent to a friend relationship, they create a friendship.

The following code examples demonstrate how to:

• Get a friend list
• Send a friend request
• Remove a friend
• Consent to a friend request
• Ignore a friend request

Get a friend list

Use the GetFriendsAsync method to retrieve the current player’s friends list. The following code snippet shows the GetFriendsAsync definition.

Parameter	Description
paginationOptions	The pagination options for the request. You can set a limit and an offset.

/// <summary>
/// Async Operation.
/// Retrieve the current player friends list.
/// </summary>
/// <param name="paginationOptions">Pagination options</param>
/// <returns>List of Player objects containing the player information.</returns>
/// <exception cref="System.ArgumentException">Represents an error that occur when an argument is incorrectly setup.</exception>
/// <exception cref="Unity.Services.Friends.Exceptions.FriendsServiceException">An exception containing the HttpClientResponse with headers, response code, and string of error.</exception>
Task<List<Player>> GetFriendsAsync(PaginationOptions paginationOptions);

The following code snippet shows how to get the friends of the current player.

/// <summary>
/// Making sure that the Unity services are initialized and that the current player is logged in and as a valid Unity Authentication Service identifier.
/// </summary>
async void Initialize()
{
    await UnityServices.InitializeAsync();
    await AuthenticationService.Instance.SignInAnonymouslyAsync();

    if (!AuthenticationService.Instance.IsSignedIn)
    {
        Debug.Log("The player was not signed in successfully.");
    }
}

/// <summary>
/// Dispose the friends SDK when we are not using it anymore.
/// </summary>
async void Teardown()
{
    await Friends.Instance.Dispose()
}

async void GetFriends(int limit, int offset)
{
    try
    {
        List<Player> friends = await Friends.Instance.GetFriendsAsync(new PaginationOptions {
        {
            Limit = limit,
            Offset = offset
        });

        Debug.Log("nFriends: " + friends.Count);
        for (int i = 0; i < friends.Count; i++)
        {
            Debug.Log("Player ID: " + friends[i].Player.Id);
        }
    }
    catch (ArgumentException e)
    {
        Debug.Log("An argument exception occurred with message: " + e.Message);
    }
    catch (FriendsServiceException e)
    {
        Debug.Log("An error occurred while performing the action. Code: " + e.Reason + ", Message: " + e.Message);
    }
}

Get a friend list with presence

Use the GetFriendsAsync method to retrieve the current player’s friends list. The following code snippet shows the GetFriendsAsync definition.

Parameter	Description
paginationOptions	The pagination options for the request. You can set a limit and an offset.

/// <summary>
/// Async Operation.
/// Retrieve the current player friends list with presence information.
/// </summary>
/// <param name="paginationOptions">Pagination options</param>
/// <returns>List of PlayerPresence objects containing the player and the presence information (availability & custom activity)</returns>
/// <exception cref="System.ArgumentException">Represents an error that occur when an argument is incorrectly setup.</exception>
/// <exception cref="Unity.Services.Friends.Exceptions.FriendsServiceException">An exception containing the HttpClientResponse with headers, response code, and string of error.</exception>
Task<List<PlayerPresence<T>>> GetFriendsAsync<T>(PaginationOptions paginationOptions) where T : new();

The following code snippet shows how to get the friends of the current player.

/// <summary>
/// Making sure that the Unity services are initialized and that the current player is logged in and as a valid Unity Authentication Service identifier.
/// </summary>
async void Initialize()
{
    await UnityServices.InitializeAsync();
    await AuthenticationService.Instance.SignInAnonymouslyAsync();

    if (!AuthenticationService.Instance.IsSignedIn)
    {
        Debug.Log("The player was not signed in successfully.");
    }
}

/// <summary>
/// Dispose the friends SDK when we are not using it anymore.
/// </summary>
async void Teardown()
{
    await Friends.Instance.Dispose()
}

/// <summary>
/// MyCustomActivity represents the activity containing the location and the status of a player.
///
/// Note: The developer can specify other properties than the ones used inside this example.
/// </summary>
[Preserve]
[DataContract]
class MyCustomActivity
{
    /// <summary>
    /// Location of the player.
    /// </summary>
    [Preserve]
    [DataMember(Name = "location", IsRequired = true, EmitDefaultValue = true)]
    public string Location { get; set; }

    /// <summary>
    /// Status of the player.
    /// </summary>
    [Preserve]
    [DataMember(Name = "status", IsRequired = true, EmitDefaultValue = true)]
    public string Status { get; set; }
}

async void GetFriends(int limit, int offset)
{
    try
    {
        List<PlayerPresence<MyCustomActivity>> friends = await Friends.Instance.GetFriendsAsync<MyCustomActivity>(new PaginationOptions
        {
            Limit = limit,
            Offset = offset
        });

        Debug.Log("nFriends: " + friends.Count);
        for (int i = 0; i < friends.Count; i++)
        {
            Debug.Log("Player ID: " + friends[i].Player.Id + ", " +
                      "Availability: " + friends[i].Presence.GetAvailability() + ", " + 
                      "Activity - location: " + friends[i].Presence.GetActivity().Location + ", " +
                      "Activity - status: "+ friends[i].Presence.GetActivity().Status);
        }
    }
    catch (ArgumentException e)
    {
        Debug.Log("An argument exception occurred with message: " + e.Message);
    }
    catch (FriendsServiceException e)
    {
        Debug.Log("An error occurred while performing the action. Code: " + e.Reason + ", Message: " + e.Message);
    }
}

Send a friend request

Use the AddFriendAsync method to create a request to add a player to the current player’s friends list. It returns an awaitable task or an error.

Note: A friend request expires after 30 days.

Parameter	Description
playerId	The unique identifier of the target player receiving the friend request.
eventSource	Source where the event occurred (for example, the source might be "chat"). The default value is null.

The following code snippet shows the AddFriendAsync definition.

/// <summary>
/// Async Operation.
/// Creates a request to add a player to the current player friends list. This request will expire after 30 days.
/// </summary>
/// <param name="playerId">Identifier of the player</param>
/// <param name="eventSource">Source where the event occurred (e.g "chat"). Default is null.</param>
/// <returns>Awaitable task</returns>
/// <exception cref="System.ArgumentException">Represents an error that occur when an argument is incorrectly setup.</exception>
/// <exception cref="Unity.Services.Friends.Exceptions.FriendsServiceException">An exception containing the HttpClientResponse with headers, response code, and string of error.</exception>
Task AddFriendAsync(string playerId, string eventSource = null);

The following code snippet shows how the current player can send a friend request to a target player.

/// <summary>
/// Making sure that the Unity services are initialized and that the current player is logged in and as a valid Unity Authentication Service identifier.
/// </summary>
async void Initialize()
{
    await UnityServices.InitializeAsync();
    await AuthenticationService.Instance.SignInAnonymouslyAsync();

    if (!AuthenticationService.Instance.IsSignedIn)
    {
        Debug.Log("The player was not signed in successfully.");
    }
}

/// <summary>
/// Dispose the friends SDK when we are not using it anymore.
/// </summary>
async void Teardown()
{
    await Friends.Instance.Dispose()
}

async void AddFriend(string playerId, string eventSource = null)
{
    try
    {
        await Friends.Instance.AddFriendAsync(playerId, eventSource);
    }
    catch (ArgumentException e)
    {
        Debug.Log("An argument exception occurred with message: " + e.Message);
    }
    catch (FriendsServiceException e)
    {
        Debug.Log("An error occurred while performing the action. Code: " + e.Reason + ", Message: " + e.Message);
    }
}

Remove a friend

Use the RemoveFriendAsync method to remove a player from the current player’s friends list.

Parameter	Description
playerId	The unique identifier of the player who sent the original friend request.

/// <summary>
/// Async Operation.
/// Remove a target player from the current player friend list.
/// </summary>
/// <param name="playerId">Identifier of the player</param>
/// <returns>Awaitable task</returns>
/// <exception cref="System.ArgumentException">Represents an error that occur when an argument is incorrectly setup.</exception>
/// <exception cref="Unity.Services.Friends.Exceptions.FriendsServiceException">An exception containing the HttpClientResponse with headers, response code, and string of error.</exception>
Task RemoveFriendAsync(string playerId);

The following code snippet shows how the current player can remove a target player from the friend list.

/// <summary>
/// Making sure that the Unity services are initialized and that the current player is logged in and as a valid Unity Authentication Service identifier.
/// </summary>
async void Initialize()
{
    await UnityServices.InitializeAsync();
    await AuthenticationService.Instance.SignInAnonymouslyAsync();

    if (!AuthenticationService.Instance.IsSignedIn)
    {
        Debug.Log("The player was not signed in successfully.");
    }
}

/// <summary>
/// Dispose the friends SDK when we are not using it anymore.
/// </summary>
async void Teardown()
{
    await Friends.Instance.Dispose()
}

async void RemoveFriend(string playerId)
{
    try
    {
        await Friends.Instance.RemoveFriendAsync(playerId);
    }
    catch (ArgumentException e)
    {
        Debug.Log("An argument exception occurred with message: " + e.Message);
    }
    catch (FriendsServiceException e)
    {
        Debug.Log("An error occurred while performing the action. Code: " + e.Reason + ", Message: " + e.Message);
    }
}

Consent friendship request

Use the ConsentFriendRequestAsync method to consent to (or accept) a friend request from another player.

Parameter	Description
playerId	The unique identifier of the player who sent the original friend request.

The following code snippet shows the ConsentFriendRequestAsync definition.

/// <summary>
/// Async Operation.
/// Consent the friend request from a player.
/// </summary>
/// <param name="playerId">Identifier of the player</param>
/// <returns>Awaitable task</returns>
/// <exception cref="System.ArgumentException">Represents an error that occur when an argument is incorrectly setup.</exception>
/// <exception cref="Unity.Services.Friends.Exceptions.FriendsServiceException">An exception containing the HttpClientResponse with headers, response code, and string of error.</exception>
Task ConsentFriendRequestAsync(string playerId);

The following code snippet shows how the current player can accept a friend request from another player.

/// <summary>
/// Making sure that the Unity services are initialized and that the current player is logged in and as a valid Unity Authentication Service identifier.
/// </summary>
async void Initialize()
{
    await UnityServices.InitializeAsync();
    await AuthenticationService.Instance.SignInAnonymouslyAsync();

    if (!AuthenticationService.Instance.IsSignedIn)
    {
        Debug.Log("The player was not signed in successfully.");
    }
}

/// <summary>
/// Dispose the friends SDK when we are not using it anymore.
/// </summary>
async void Teardown()
{
    await Friends.Instance.Dispose()
}

async void ConsentFriendRequest(string playerId)
{
    try
    {
        await Friends.Instance.ConsentFriendRequestAsync(playerId);
    }
    catch (ArgumentException e)
    {
        Debug.Log("An argument exception occurred with message: " + e.Message);
    }
    catch (FriendsServiceException e)
    {
        Debug.Log("An error occurred while performing the action. Code: " + e.Reason + ", Message: " + e.Message);
    }
}

Ignore friendship request

Use the IgnoreFriendRequestAsync method to ignore a friend request from another player.

Parameter	Description
playerId	The unique identifier of the target player who sent the original friend request.

The following code snippet shows the IgnoreFriendRequestAsync definition.

/// <summary>
/// Async Operation.
/// Ignore a friend request from another player.
/// </summary>
/// <param name="playerId">Identifier of the player</param>
/// <returns>Awaitable task</returns>
/// <exception cref="System.ArgumentException">Represents an error that occur when an argument is incorrectly setup.</exception>
/// <exception cref="Unity.Services.Friends.Exceptions.FriendsServiceException">An exception containing the HttpClientResponse with headers, response code, and string of error.</exception>
Task IgnoreFriendRequestAsync(string playerId);

The following code snippet shows how the current player can ignore a friend request from another player.

/// <summary>
/// Making sure that the Unity services are initialized and that the current player is logged in and as a valid Unity Authentication Service identifier.
/// </summary>
async void Initialize()
{
    await UnityServices.InitializeAsync();
    await AuthenticationService.Instance.SignInAnonymouslyAsync();

    if (!AuthenticationService.Instance.IsSignedIn)
    {
        Debug.Log("The player was not signed in successfully.");
    }
}

/// <summary>
/// Dispose the friends SDK when we are not using it anymore.
/// </summary>
async void Teardown()
{
    await Friends.Instance.Dispose()
}

async void IgnoreFriendRequest(string playerId)
{
    try
    {
        await Friends.Instance.IgnoreFriendRequestAsync(playerId);
    }
    catch (ArgumentException e)
    {
        Debug.Log("An argument exception occurred with message: " + e.Message);
    }
    catch (FriendsServiceException e)
    {
        Debug.Log("An error occurred while performing the action. Code: " + e.Reason + ", Message: " + e.Message);
    }
}

Blocks

Players can block and unblock other players from sending them friend requests. Once a player blocks another player, the blocked player has no access to the blocking player. The Friends service prevents all communication between the two players until the blocking player unblocks the blocked player.

The blocked player cannot:

• See the blocking player in their friends list.
• Block the blocking player.
• Send friend requests to the blocking player.
• Receive (or see) friend requests from the blocking player.

The blocking player cannot:

• See the blocked player in their friends list.
• Send friend requests to the blocked player.
• Receive (or see) friend requests from the blocked player.

However, the blocking player can see the blocked player in their blocked list and choose to unblock them. If a player unblocks another player that was previously in their friends list, the unblocked player reappears in their friends list. Once unblocked, the previously blocked player can perform any actions they could before they were blocked. The following code examples demonstrate how to:

• Get a block list
• Block a player
• Unblock a player

Get a block list

Use the GetBlocksAsync method to retrieve the list of blocked players from the current player. The following code snippet shows how to retrieve the first 50 players the current player blocked.

Parameter	Description
paginationOptions	The pagination options for the request. You can set a limit and an offset.

/// <summary>
/// Async Operation.
/// Retrieve the current player block list.
/// </summary>
/// <param name="paginationOptions">Pagination options</param>
/// <returns>List of players objects</returns>
/// <exception cref="System.ArgumentException">Represents an error that occur when an argument is incorrectly setup.</exception>
/// <exception cref="Unity.Services.Friends.Exceptions.FriendsServiceException">An exception containing the HttpClientResponse with headers, response code, and string of error.</exception>
Task<List<Player>> GetBlocksAsync(PaginationOptions paginationOptions);

The following code snippet shows how to retrieve the blocks of the current player.

/// <summary>
/// Making sure that the Unity services are initialized and that the current player is logged in and as a valid Unity Authentication Service identifier.
/// </summary>
async void Initialize()
{
    await UnityServices.InitializeAsync();
    await AuthenticationService.Instance.SignInAnonymouslyAsync();

    if (!AuthenticationService.Instance.IsSignedIn)
    {
        Debug.Log("The player was not signed in successfully.");
    }
}

/// <summary>
/// Dispose the friends SDK when we are not using it anymore.
/// </summary>
async void Teardown()
{
    await Friends.Instance.Dispose()
}

async void GetBlocks(int limit, int offset)
{    
    try
    {
        var blocks = await Friends.Instance.GetBlocksAsync(new PaginationOptions {Limit = limit, Offset = offset});

        blocks.ForEach(player =>
        {
            Debug.Log("Player ID: " + player.Id);
        });
    }
    catch (ArgumentException e)
    {
        Debug.Log("An argument exception occurred with message: " + e.Message);
    }
    catch (FriendsServiceException e)
    {
        Debug.Log("An error occurred while performing the action. Code: " + e.Reason + ", Message: " + e.Message);
    }
}

Block a player

Use the BlockAsync method to block a player from sending friend requests to the current player.

Parameter	Description
playerId	The unique identifier of the target player that the current player is blocking.
eventSource	Source where the event occurred (for example, the source might be "chat"). The default value is null.

The following code snippet shows the BlockAsync definition.

/// <summary>
/// Async Operation.
/// Add a target player to current player block list.
/// </summary>
/// <param name="playerId">Identifier of the player</param>
/// <param name="eventSource">Source where the event occurred (e.g "chat"). Default is null.</param>
/// <returns>Awaitable task</returns>
/// <exception cref="System.ArgumentException">Represents an error that occur when an argument is incorrectly setup.</exception>
/// <exception cref="Unity.Services.Friends.Exceptions.FriendsServiceException">An exception containing the HttpClientResponse with headers, response code, and string of error.</exception>
Task BlockAsync(string playerId, string eventSource = null);

The following code snippet shows how the current player can block another player.

/// <summary>
/// Making sure that the Unity services are initialized and that the current player is logged in and as a valid Unity Authentication Service identifier.
/// </summary>
async void Initialize()
{
    await UnityServices.InitializeAsync();
    await AuthenticationService.Instance.SignInAnonymouslyAsync();

    if (!AuthenticationService.Instance.IsSignedIn)
    {
        Debug.Log("The player was not signed in successfully.");
    }
}

/// <summary>
/// Dispose the friends SDK when we are not using it anymore.
/// </summary>
async void Teardown()
{
    await Friends.Instance.Dispose()
}

async void Block(string playerId, string eventSource = null)
{
    try
    {
        await Friends.Instance.BlockAsync(playerId, eventSource);
    }
    catch (ArgumentException e)
    {
        Debug.Log("An argument exception occurred with message: " + e.Message);
    }
    catch (FriendsServiceException e)
    {
        Debug.Log("An error occurred while performing the action. Code: " + e.Reason + ", Message: " + e.Message);
    }
}

Unblock a player

Use the UnblockAsync method to remove a player from the current player’s block list.

Parameter	Description
playerId	The unique identifier of the target player that the current player is unblocking.

The following code snippet shows the UnblockAsync definition.

/// <summary>
/// Async Operation.
/// Remove a target player from the current player block list.
/// </summary>
/// <param name="playerId">Identifier of the player</param>
/// <returns>Awaitable task</returns>
/// <exception cref="System.ArgumentException">Represents an error that occur when an argument is incorrectly setup.</exception>
/// <exception cref="Unity.Services.Friends.Exceptions.FriendsServiceException">An exception containing the HttpClientResponse with headers, response code, and string of error.</exception>
Task UnblockAsync(string playerId);

The following code snippet shows how the current player can unblock another player.

/// <summary>
/// Making sure that the Unity services are initialized and that the current player is logged in and as a valid Unity Authentication Service identifier.
/// </summary>
async void Initialize()
{
    await UnityServices.InitializeAsync();
    await AuthenticationService.Instance.SignInAnonymouslyAsync();

    if (!AuthenticationService.Instance.IsSignedIn)
    {
        Debug.Log("The player was not signed in successfully.");
    }
}

/// <summary>
/// Dispose the friends SDK when we are not using it anymore.
/// </summary>
async void Teardown()
{
    await Friends.Instance.Dispose()
}

async void Unblock(string playerId)
{
    try
    {
        await Friends.Instance.UnblockAsync(playerId);
    }
    catch (ArgumentException e)
    {
        Debug.Log("An argument exception occurred with message: " + e.Message);
    }
    catch (FriendsServiceException e)
    {
        Debug.Log("An error occurred while performing the action. Code: " + e.Reason + ", Message: " + e.Message);
    }
}

Inbox

An inbox is a representation of all the friend requests to the current player.

Get friend requests

Use the GetInboxAsync method to retrieve the inbox of the current player.

Parameter	Description
paginationOptions	The pagination options for the request. You can set a limit and an offset.

/// <summary>
/// Async Operation.
/// Retrieve the current player friend requests.
/// </summary>
/// <param name="paginationOptions">Pagination options</param>
/// <returns>List of players objects</returns>
/// <exception cref="System.ArgumentException">Represents an error that occur when an argument is incorrectly setup.</exception>
/// <exception cref="Unity.Services.Friends.Exceptions.FriendsServiceException">An exception containing the HttpClientResponse with headers, response code, and string of error.</exception>
Task<List<Player>> GetInboxAsync(PaginationOptions paginationOptions);

The following code snippet shows how to retrieve the current player inbox.

/// <summary>
/// Making sure that the Unity services are initialized and that the current player is logged in and as a valid Unity Authentication Service identifier.
/// </summary>
async void Initialize()
{
    await UnityServices.InitializeAsync();
    await AuthenticationService.Instance.SignInAnonymouslyAsync();

    if (!AuthenticationService.Instance.IsSignedIn)
    {
        Debug.Log("The player was not signed in successfully.");
    }
}

/// <summary>
/// Dispose the friends SDK when we are not using it anymore.
/// </summary>
async void Teardown()
{
    await Friends.Instance.Dispose()
}

async void GetInbox(int offset, int limit)
{
    await UnityServices.InitializeAsync();
    await AuthenticationService.Instance.SignInAnonymouslyAsync();

    if (!AuthenticationService.Instance.IsSignedIn)
    {
        Debug.Log("The player was not signed in successfully.");
        return;
    }

    try
    {
        var inbox = await Friends.Instance.GetInboxAsync(new PaginationOptions {Limit = offset, Offset = limit});

        inbox.ForEach(player =>
        {
            Debug.Log("Player ID: " + player.Id);
        });
    }
    catch (ArgumentException e)
    {
        Debug.Log("An argument exception occurred with message: " + e.Message);
    }
    catch (FriendsServiceException e)
    {
        Debug.Log("An error occurred while performing the action. Code: " + e.Reason + ", Message: " + e.Message);
    }
}

Presence

Presence is the availability status of a friend within a player’s friend list.

Set presence

Use the SetPresenceAsync method to set the presence of the currently logged in player. With this method, you can set the availability of the player and a custom activity.

The presence availability information can be one of the following values:

• ONLINE
• BUSY
• AWAY
• INVISIBLE
• OFFLINE
• UNKOWN

The presence activity must be a structure that can be marshalled into a JSON format (key, value pair) of any format.

Note: Players can only see the presence status of other players on their friend list.

The following code sample shows the SetPresenceAsync definition.

/// <summary>
/// Async Operation.
/// Setter for the presence of the current player.
/// </summary>
/// <param name="presence">Presence of the player where T represents the Availability structure to save.</param>
/// <exception cref="System.ArgumentException">Represents an error that occur when an argument is incorrectly setup.</exception>
/// <exception cref="Unity.Services.Friends.Exceptions.FriendsServiceException">An exception containing the HttpClientResponse with headers, response code, and string of error.</exception>
Task SetPresenceAsync<T>(Presence<T> presence) where T : new();

/// <summary>
/// Making sure that the Unity services are initialized and that the current player is logged in and as a valid Unity Authentication Service identifier.
/// </summary>
async void Initialize()
{
    await UnityServices.InitializeAsync();
    await AuthenticationService.Instance.SignInAnonymouslyAsync();

    if (!AuthenticationService.Instance.IsSignedIn)
    {
        Debug.Log("The player was not signed in successfully.");
    }
}

/// <summary>
/// Dispose the friends SDK when we are not using it anymore.
/// </summary>
async void Teardown()
{
    await Friends.Instance.Dispose()
}

/// <summary>
/// MyCustomActivity represents the activity containing the location and the status of a player.
///
/// Note: The developer can specify other properties than the ones used inside this example.
/// </summary>
[Preserve]
[DataContract]
class MyCustomActivity
{
    /// <summary>
    /// Location of the player.
    /// </summary>
    [Preserve]
    [DataMember(Name = "location", IsRequired = true, EmitDefaultValue = true)]
    public string Location { get; set; }

    /// <summary>
    /// Status of the player.
    /// </summary>
    [Preserve]
    [DataMember(Name = "status", IsRequired = true, EmitDefaultValue = true)]
    public string Status { get; set; }
}

async void SetPresence()
{
    try
    {
        await Friends.Instance.SetPresenceAsync(new Presence<MyCustomActivity>(PresenceAvailabilityOptions.BUSY,
            new MyCustomActivity
            {
                Location = "In Lobby",
                Status = "Walking"
            }));
    }
    catch (ArgumentException e)
    {
        Debug.Log("An argument exception occurred with message: " + e.Message);
    }
    catch (FriendsServiceException e)
    {
        Debug.Log("An error occurred while performing the action. Code: " + e.Reason + ", Message: " + e.Message);
    }
}