Protocol activation

Games can register a custom URI protocol that can be used launch their game if it isn't running and will bring the game to the foreground if the game is already running.

Registering the protocol

In order to register a custom protocol, the game must first modify their MicrosoftGame.Config. Games can register multiple protocol by adding them to the <ProtocolList> as shown in the example below.

<Game configVersion="1">
   <Identity Name="ExampleGame" Publisher="CN=NoPub" Version="1.6.0.0"/>
   <ProtocolList>
      <Protocol Name="awesome-custom-debug-protocol"
                Executable="SubDirectory\Test\MyExecutable_profile.exe"/>
      <Protocol Name="awesome-custom-protocol2"
                Executable="MyExecutable.exe"/>

   </ProtocolList>
   <!-- Lots of stuff excluded -->
</Game>

This example above registers two custom protocols. Games can then be launched using a URI such as the following:

awesome-custom-debug-protocol://Parameter1=xyz&Parameter2=abc

Games can then register for a XGameProtocolActivationCallback callback that would be invoked when they are protocol activated using XGameProtocolRegisterForActivation. Games can then parse the URI to read any additional parameters passed to the game.

Note

While it is true that games could use GetCommandLine to get the same parameters, this would only work for the initial launch of the game. If the game was already running, the commandline arguments passed to the game will not get updated. All games wanting to leverage custom protocol activation should register a callback using XGameProtocolRegisterForActivation and rely on that callback to respond to the activation.

Note

All games with a title ID will always have a default protocol registered of the form ms-xbl-XXXXXXXX:// where XXXXXXXX is the hexadecimal form of the title ID without the leading "0x". This protocol is reserved for game invites. Games activated using this protocol will trigger the XGameInviteEventCallback but not the XGameProtocolActivationCallback.

See also

XGameProtocolRegisterForActivation XGameProtocolUnregisterForEvent XGameProtocolActivationCallback