The Colocation Discovery feature allows users who are located in the same physical space to advertise and discover Colocation Sessions. A user can host one session at a time, and the session may contain metadata which can help identify the session during discovery. This is helpful for colocated apps by removing the requirement for a local area network or internet based discovery method.

After reading this page, you should be able to:

Describe the functionality of Colocation Discovery.

Configure an app for supporting Colocation Discovery.

Understand and use the Colocation Discovery API.

Prerequisites

Your application must be registered on your developer dashboard.

Meta Quest 3, 3S, Pro, and 2 support Colocation Discovery with version v71 or greater.

Quest 1 devices do not support Colocation Discovery.

“Colocation Sessions Enabled” must be true in the Meta XR Plugin settings of your Unreal project.

Implementation

Advertise a Colocation Session

Determine what meta data you want to broadcast in your advertisement.

Start advertisement with StartSessionAdvertisementAsync

Wait as long as you would like before completing advertisement.

Complete advertisement with StopSessionAdvertisementAsync

Advertise Colocation Session Blueprint API

StartSessionAdvertisementAsync reference image:

StartSessionAdvertisementAsync Blueprint reference image

StopSessionAdvertisementAsync reference image:

StopSessionAdvertisementAsync Blueprint reference image

Advertise Colocation Session C++ API

The StartSessionAdvertisementAsync and StopSessionAdvertisementAsync C++ API is accessed through the OculusXRColocation interface.

For starting advertisement the API takes an array of bytes that acts as metadata as well as a delegate parameter as an argument which will be executed on success or failure. The return type of the API call is TSharedPtr<FStartSessionAdvertisementRequest>.

For stopping advertisement the API only takes the delegate parameter as an argument that will be executed on success or failure. The return type of the API call is TSharedPtr<FStopSessionAdvertisementRequest>.

The FStartSessionAdvertisementRequest and FStopSessionAdvertisementRequest type are classes that wraps an underlying AsyncRequest type and the function call will configure and execute the AsyncRequest for you. Completion, both failure and success, will occur on the game thread. Either immediately as the request is executed or after some number of frames.

The following describes the completion delegates and their parameters.

Delegate	Parameters
`FStartSessionAdvertisementRequest::FCompleteDelegate`	`FStartSessionAdvertisementRequest::FResultType Result`
`FStopSessionAdvertisementRequest::FCompleteDelegate`	`FStopSessionAdvertisementRequest::FResultType Result`

The following describes the result structure type for both start and stop requests.

Name	Type	Description
`TResultType`	`EColocationResult`	The result enum value.
`TValueType`	`FOculusXRColocationSession`	Structure containing the session UUID and Metadata.

Advertise Colocation Session C++ example

You are not required to use a lambda as your delegate functor, that is only used to simplify this example.

void StartAdvertising(const TArray<uint8>& Metadata)
{
  OculusXRColocation::FColocation::StartSessionAdvertisementAsync(
    Metadata,
    FStartSessionAdvertisementRequest::FCompleteDelegate::CreateLambda([](
      const FStartSessionAdvertisementRequest::FResultType& Result)
    {
      if (Result.IsSuccess())
      {
        FOculusXRColocationSession session = Result.GetValue();
      }
      else
      {
        auto status = Result.GetStatus()
        // Do something with the status code on error
      }
    })
  );
}

void StopAdvertising()
{
  OculusXRColocation::FColocation::StopSessionAdvertisementAsync(
    FStopSessionAdvertisementRequest::FCompleteDelegate::CreateLambda([](
      const FStopSessionAdvertisementRequest::FResultType& Result)
    {
      if (Result.IsSuccess())
      {
        // Stopped successfully
      }
      else
      {
        auto status = Result.GetStatus()
        // Do something with the status code on error
      }
    })
  );
}

Discover a Colocation Session

Start discovery with DiscoverSessionsAsync

Wait as long as you would like before completing discovery.

Complete discovery with StopDiscoverSessions

Discover Colocation Session Blueprint API

DiscoverSessionsAsync reference image: DiscoverSessionsAsync Blueprint reference image

StopDiscoverSessions reference image: StopDiscoverSessions Blueprint reference image

Discover Colocation Session C++ API

The DiscoverSessionsAsync and StopDiscoverSessions C++ API is accessed through the OculusXRColocation interface.

For starting discovery the API takes a completion delegate parameter as an argument which will be executed on success or failure. And, it takes an OnSessionFound parameter which will be executed every time a Colocation Session is found. The return type of the API call is TSharedPtr<FDiscoverSessionsRequest>. The FDiscoverSessionsRequest type is a class that wraps an underlying AsyncRequest type and the function call will configure and execute the AsyncRequest for you. Completion, both failure and success, will occur on the game thread. Either immediately as the request is executed or after some number of frames.

For stopping discovery the API only takes a reference to the FDiscoverSessionsRequest. The return type of the API call is EColocationResult.

The following describes the completion delegate and session found delegates.

Delegate	Parameters
`FDiscoverSessionsRequest::FCompleteDelegate`	`FDiscoverSessionsRequest::FResultType Result`
`FOculusXRColocationSessionFoundDelegate`	`const FOculusXRColocationSession& Session`

The following describes the result structure type for starting discovery.

Name	Type	Description
`TResultType`	`EColocationResult`	The result enum value.
`TValueType`	`TArray<FOculusXRColocationSession>`	Array of found colocation sessions.

Advertise Colocation Session C++ example

You are not required to use a lambda as your delegate functor, that is only used to simplify this example.

TSharedPtr<FDiscoverSessionsRequest> StartDiscovery()
{
  auto request = OculusXRColocation::FColocation::DiscoverSessionsAsync(
    FDiscoverSessionsRequest::FCompleteDelegate::CreateLambda([](
        const FDiscoverSessionsRequest::FResultType& Result)
    {
      if (Result.IsSuccess())
      {
        TArray<FOculusXRColocationSession> sessions = Result.GetValue();
      }
      else
      {
        auto status = Result.GetStatus()
        // Do something with the status code on error
      }
    }),
    FOculusXRColocationSessionFoundDelegate::CreateLambda([](
      const FOculusXRColocationSession& Session)
    {
      // Do something when a session is found
    })
  );

  return request;
}

void StopDiscovery(TSharedPtr<FDiscoverSessionsRequest> Request)
{
  auto result = OculusXRColocation::FColocation::StopDiscoverSessions(Request);
  if(result != Success)
  {
    switch(result)
    {
      // ... Do whatever you want based on the error code
    }
  }
}