Develop

Colocation Discovery

Updated: Apr 14, 2026

Overview

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.

Currently the Colocation Discovery API requires devices to be connected to the internet.

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” must be enabled in the Meta XR Plugin settings of your Unreal project. To enable this setting: Edit > Project Settings > Meta XR > Mobile section > Colocation Sessions.

Implementation

Advertise a Colocation Session

Determine what metadata 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.

Session metadata is limited to 1024 bytes. Any metadata passed to the advertisement API must not exceed this size.

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.

The StartSessionAdvertisementAsync function 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>.

The StopSessionAdvertisementAsync function takes only 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 types are classes that wrap 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.

The following table describes all EColocationResult enum values. These values apply to both advertisement and discovery operations.

Value	Description
`Success`	Operation succeeded.
`Success_AlreadyAdvertising`	Already advertising. Not an error.
`Success_AlreadyDiscovering`	Already discovering. Not an error.
`Failure`	Generic failure.
`FailureInvalidParameter`	Invalid parameter provided.
`FailureDataIsInvalid`	Data validation failed.
`NetworkTimeout`	Network operation timed out.
`NetworkRequestFailed`	Network request failed.
`InsufficientPermissions`	Missing required permissions.
`CloudStorageDisabled`	Cloud storage is disabled.
`NoDiscoveryMethodAvailable`	No discovery method available on device.

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.

The DiscoverSessionsAsync function takes a completion delegate parameter as an argument which will be executed on success or failure. It also 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.

The StopDiscoverSessions function takes only 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.

Discover 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 != EColocationResult::Success)
  {
    switch(result)
    {
      // ... Do whatever you want based on the error code
    }
  }
}