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".

Events

ColocationSessionDiscovered : Action< Data >

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.

Signature

Action<Data> ColocationSessionDiscovered

Static Methods

StartAdvertisementAsync ( 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. Signature static OVRTask< OVRResult< Guid, Result > > StartAdvertisementAsync(ReadOnlySpan< byte > colocationSessionData) Parameters `colocationSessionData: ReadOnlySpan< byte >` 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 `OVRTask< OVRResult< Guid, Result > >` 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). Throws `System.ArgumentException` is thrown if colocationSessionData refers to more than Data.MaxMetadataSize bytes of data.
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. Signature static OVRTask< OVRResult< Result > > StartDiscoveryAsync() Returns `OVRTask< OVRResult< Result > >` Returns an OVRResult<Result> indicating the success or failure of starting colocated advertisement discovery.
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. Signature static OVRTask< OVRResult< Result > > StopAdvertisementAsync() Returns `OVRTask< OVRResult< Result > >` Returns an OVRResult<Result> indicating the success or failure of this request to stop advertising.
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). Signature static OVRTask< OVRResult< Result > > StopDiscoveryAsync() Returns `OVRTask< OVRResult< Result > >` Returns an OVRResult<Result> indicating the success or failure of this request to stop discovering.

Inner Struct

Data Struct

Data that is passed to ColocationSessionDiscovered when a nearby session has been discovered.

Static Fields

MaxMetadataSize : const int

The maximum number of bytes allowed for the custom Metadata section of advertisements.

Signature

const int MaxMetadataSize

Properties

AdvertisementUuid : Guid [Get]	A unique ID representing the colocated session, advertised by another user's call to StartAdvertisementAsync. This value is identical to the Guid returned to the advertiser after they awaited StartAdvertisementAsync. This UUID is useful as a "groupUuid", for various OVRSpatialAnchor sharing and loading APIs (see below). Signature Guid AdvertisementUuid
Metadata : byte[] [Get]	The user-defined data block that the advertiser passed to StartAdvertisementAsync. Signature byte [] Metadata

Inner Enum

Result Enum

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

Enumeration Constants

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