Meta Developers

Colocation Sessions are a way for apps to connect "colocated" users (meaning users in real-world physical proximity), enabling these users to share/load OVRSpatialAnchors to/from the session's Uuid, rather than with e.g.

individual OVRSpaceUsers, which requires manual communication of Platform user IDs.

This feature utilizes onboard bluetooth and a shared wifi network to get colocated users connected with each other. Thus, users should be advised to have these device services enabled, and to remain connected to the same wifi network, otherwise colocation session advertisements will not be receivable. Lastly, you the app developer should ensure your AndroidManifest.xml contains the following permission:

\<uses-permission android:name="com.oculus.permission.USE_COLOCATION_DISCOVERY_API"/\>

which is automatically added when "Colocation Sessions" is enabled in your OculusProjectConfig asset and you run the menu bar utility "Meta > Tools > Update AndroidManifest.xml".

Member Enumerations

Enumeration Result

An enum that represents the possible results from calling a public async function in OVRColocationSession.

Success	The API call succeeded.
AlreadyAdvertising	A Colocation Session already is advertising, a no-op occurs.
AlreadyDiscovering	Colocation Sessions are already being discovered, a no-op occurs.
Failure	The API call failed with no additional details.
Unsupported	Colocation Session is not supported.
OperationFailed	The API call operation failed.
InvalidData	The result received does not represent the API call.
NetworkFailed	The user is not connected to a network.
NoDiscoveryMethodAvailable	The user does not have discovery methods such as bluetooth enabled.

Events

static Action< Data > ColocationSessionDiscovered

An event that is invoked when a new nearby session has been discovered.

Only invokes while in a state of "active discovery", begun by successful calls to StartDiscoveryAsync and ended by successful calls to StopDiscoveryAsync. NOTICE: StopDiscoveryAsync does NOT unregister listeners from this event. Leaving non-static listeners indefinitely attached is a potential dangling reference (GC memory leak), and/or may introduce undefined behaviors (including unhandled exceptions). You should only need to sub/unsub a listener once, but ultimately listener lifetimes and validity are yours to consider and manage.

Static Member Functions

static OVRTask< OVRResult< Guid, Result > > StartAdvertisementAsync

( ReadOnlySpan< byte > colocationSessionData )

Starts advertising a new colocation session with associated custom data.

Example:

async void TryStartSession()
{
byte[] data = null; // your custom data here
    var result = await OVRColocationSession.StartAdvertisementAsync(data);
if (!result.TryGetValue(out var sessionUuid))
    {
        Debug.LogError($"Unable to start colocation session! status={result.Status}");
return;
    }
    await ShareCurrentAnchorsWith(sessionUuid); // your impl.
}

This method is asynchronous; use the returned OVRTask<T> wrapper to be notified of completion. If a session advertisement is already successfully started and running, then the returned OVRResult<Result>.Status will be Result.AlreadyAdvertising, which is a special "success" status. In this case, colocationSessionData is ignored even if it is new/updated data; in order to update your custom data, you must await StopAdvertisementAsync before starting a new session advertisement. The new session would need to be re-discovered by peers, and any anchors shared to the previous session would need to be re-shared with the new UUID.

Parameters

colocationSessionData

A span of bytes (or null) representing user-defined data to associate with the new Colocation Session. It must be no longer than Data.MaxMetadataSize bytes. This custom data is immutable per advertisement, and will be receivable by discoverers of the advertisement (via Data.Metadata; see event parameter for ColocationSessionDiscovered).

Returns

Returns an OVRResult<System.Guid,Result> indicating the success or failure of starting a new colocated session advertisement. The Guid portion of the result (from OVRResult<Guid,Result>.Value or OVRResult<Guid,Result>.TryGetValue) is the colocation session's UUID, which is useful as a "groupUuid" for various OVRSpatialAnchor sharing and loading APIs (listed below).

See Also:

Data.AdvertisementUuid, OVRSpatialAnchor.ShareAsync(IEnumerable<OVRSpatialAnchor>,Guid), OVRSpatialAnchor.ShareAsync(IEnumerable<OVRSpatialAnchor>,IEnumerable<Guid>), OVRSpatialAnchor.LoadUnboundSharedAnchorsAsync(Guid,List<OVRSpatialAnchor.UnboundAnchor>)

Exceptions

System.ArgumentException

is thrown if colocationSessionData refers to more than Data.MaxMetadataSize bytes of data.

static OVRTask< OVRResult< Result > > StopAdvertisementAsync ( )

Stops the current colocation session advertisement started by StartAdvertisementAsync.

This method is asynchronous; use the returned OVRTask<T> wrapper to be notified of completion.

Returns

Returns an OVRResult<Result> indicating the success or failure of this request to stop advertising.

static OVRTask< OVRResult< Result > > StartDiscoveryAsync ( )

Starts discovering nearby advertised colocated sessions.

Example:

void OnDiscoveredSession(OVRColocationSession.Data data)
{
if (!RegisterNewSession(data.AdvertisementUuid)) // your impl.
return;
    Debug.Log($"Discovered new colocated session: {data.AdvertisementUuid}");
// e.g.:
    LoadMetadata(data.Metadata); // your impl.
    LoadSharedAnchorsFrom(data.AdvertisementUuid); // your impl.
}
async void StartDiscoveringSessions()
{
    OVRColocationSession.ColocationSessionDiscovered -= OnDiscoveredSession; // prevents duplicate listeners
    OVRColocationSession.ColocationSessionDiscovered += OnDiscoveredSession;
    var result = await OVRColocationSession.StartDiscoveryAsync();
if (result.Success)
return;
    Debug.LogError($"Unable to start discovering colocation sessions! status={result.Status}");
    OVRColocationSession.ColocationSessionDiscovered -= OnDiscoveredSession;
}

Before you call this method, you need to register a listener to ColocationSessionDiscovered in order to actually receive discovered sessions. This method is asynchronous; use the returned OVRTask<T> wrapper to be notified of completion. If this method has already been invoked with a successful return status, then the returned OVRResult<Result>.Status of subsequent calls will be Result.AlreadyDiscovering, which is a special "success" status indicating no-op.

Returns

Returns an OVRResult<Result> indicating the success or failure of starting colocated advertisement discovery.

See Also:

StopDiscoveryAsync

static OVRTask< OVRResult< Result > > StopDiscoveryAsync ( )

Stops the discovery of nearby colocation session advertisements.

This method is asynchronous; use the returned OVRTask<T> wrapper to be notified of completion. NOTICE: Calling this method does not affect any listeners still attached to ColocationSessionDiscovered. Leaving non-static listeners indefinitely attached is a potential dangling reference (GC memory leak), and/or may introduce undefined behaviors (including unhandled exceptions).

Returns

Returns an OVRResult<Result> indicating the success or failure of this request to stop discovering.

See Also:

StartDiscoveryAsync