Call asynchronous methods

Using C#, call asynchronous methods from the Facebook Instant Games SDK.

The options for calling asynchronous methods provided by the Instant Games SDK are as follows:

Recommendations

For new projects, use async methods rather than coroutines because async methods make it simpler to retrieve result values and handle errors.

For all projects, the recommended approach is to have async methods return Awaitable/Awaitable<T0>, which are more fully featured and well integrated with the Unity Engine. However, these types can only be awaited once, whereas WebTask and WebTask<T> can be awaited multiple times.

Using WebTasks

To use WebTask and WebTask<T>, use the await keyword in an async method to suspend execution until the task completes:

using Meta.InstantGames;
using Meta.InstantGames.Runtime;

public class WebTaskExample
{
    // Without a return value
    public async WebTask ChooseContextAsync()
    {
        WebTask task = FBInstant.Context.ChooseAsync();
        await task;
    }

    // With a return value
    public async WebTask<ConnectedPlayer[]> GetConnectedPlayersAsync()
    {
        WebTask<ConnectedPlayer[]> task = FBInstant.Player.GetConnectedPlayersAsync();
        ConnectedPlayer[] result = await task;
        return result;
    }
}

Using WebTasks with Awaitable

If your code already uses async methods that return Awaitable or Awaitable<T0>, simply await a WebTask or WebTask<T> in your async methods to use the Instant Games SDK:

using UnityEngine;
using Meta.InstantGames;
using Meta.InstantGames.Runtime;

public class AwaitableExample
{
    public async Awaitable ChooseContextAsync()
    {
        WebTask task = FBInstant.Context.ChooseAsync();
        await task;
    }

    public async Awaitable<ConnectedPlayer[]> GetConnectedPlayersAsync()
    {
        WebTask<ConnectedPlayer[]> task = FBInstant.Player.GetConnectedPlayersAsync();
        ConnectedPlayer[] result = await task;
        return result;
    }
}

For more information about Unity's Awaitable class, refer to Introduction to asynchronous programming with Awaitable.

Using WebTasks with coroutines

To make your coroutine wait for completion of WebTask/WebTask<T>, use yield return WebTask.WaitForCompletion():

using System.Collections;
using Meta.InstantGames;
using Meta.InstantGames.Runtime;

public class CoroutineExample
{
    IEnumerator ChooseContextCoroutine()
    {
        WebTask task = FBInstant.Context.ChooseAsync();
        yield return task.WaitForCompletion();
    }
}

Coroutines don’t allow you to return a value directly. To get the result value from a WebTask<T>, try approaches such as setting a value external to the method or calling another method with the value as argument:

using System.Collections;
using Meta.InstantGames;
using Meta.InstantGames.Runtime;

class CoroutineWithResultExample
{
    public ConnectedPlayer[] players;

    // Option 1: Set a value external to the method
    IEnumerator GetPlayersAndSetValueCoroutine()
    {
        WebTask<ConnectedPlayer[]> task = FBInstant.Player.GetConnectedPlayersAsync();
        yield return task.WaitForCompletion();
        ConnectedPlayer[] result = task.Result;
        players = result;
    }

    // Option 2: Call another method with the value as argument
    IEnumerator GetPlayersAndCallMethodCoroutine()
    {
        WebTask<ConnectedPlayer[]> task = FBInstant.Player.GetConnectedPlayersAsync();
        yield return task.WaitForCompletion();
        ConnectedPlayer[] result = task.Result;
        UseConnectedPlayers(result);
    }

    void UseConnectedPlayers(ConnectedPlayer[] players)
    {
        // ...
    }
}

Additional resources