Windows 8 Game Kit updated with Windows Store Share Contract

Windows Store Share Contract

I had some requests for an example of the Windows Store Contract in the Kit.  I created simple function that will allow the player to share out their score with other Windows apps at any time.  The purpose here is a quick and easy example you can add to your own games. 

What code was updated?

Inside default.js we add a new variable to handle the title of our message.

 //Share Text
 var SHARE_TITLE = "Check out my Space Cadet score!";

Next, we create a reference to the DataTransferManager  and listen for its datarequested event.  MSDN describes the DataTransferManager as follows:

The DataTransferManager class is a static class that you use to initiate sharing operations. To use the class, first call the GetForCurrentView method. This method returns the DataTransferManager object that is specific to the active window. Next, you need to add an event listener for the datarequested event to the object. This event is fired when a sharing operation starts—typically when the user taps the Share charm, although it is also fired if your app starts a share operation programmatically.

The DataTransferManager class includes a ShowShareUI method, which you can use to programmatically start a share operation. In general, we recommend against using this method. Users expect to initiate share operations by using the Share charm—when you launch the operation programmatically, you can create an inconsistent user experience. We include the method because there are a few scenarios in which the user might not recognize opportunities to share. A good example is when the user achieves a high score in a game.

We are going to follow the guidelines and only create a package for the DataTransferManager when the player using our game requests it.  The code to create an instance of the DataTransferManager and listen to the event looks like this:

 //Share Contract
 var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
 dataTransferManager.addEventListener("datarequested", shareScore);

 

Finally, we will implement the shareScore function that will handle the datarequested event.  It is important to point out that since we don’t actually create the package until we handle the event we can share out different types of data from our game depending on what screen we are in.  For demonstration purposes I am using just the one listener but you should feel free to create different ones in your different game pages.

We then fill out the properties of the request object to use text.  The text will be a combination of our player’s name, their current level and their current score.

 //Share Contract for High Score
 function shareScore(e) {
     var request = e.request;
     var playername = document.getElementById("txtPlayerName");
  
     request.data.properties.title = SHARE_TITLE;
     request.data.setText('"' + playername.innerHTML + '" has reached ' + txtLevel.innerHTML + ' with ' + txtScore.innerHTML + '!');
  
 }

 

Sharing out the score

When we run the game we simply hit Windows-H (share) or go over to the Charms (Windows-C) and select Share.  At this point the DataTransferManager will send our game the event, we will fill out a request package with text and then the DataTransferManager will list all of the Windows Store apps that have registered to handle a Share for Text.

If I select the Mail app on my own PC and you can see the title has been correctly filled out along with my player name, score and level.

 

My PC also has a Windows Store Twitter app, MetroTwit, that has registered to handle Sharing of text.  I am able to easily tweet out my score here as well.

That’s it!  With just a few lines of code your game is now the source of a Share Contract allowing players to share our their scores with the world (and making your game a lot more appealing in the process).

Where to download the code

The main Codeplex release has been updated with the changes.  You can grab the latest release Win8GameKit-Jan2013 or simply browse the Source Code for the changes.

 

The GitHub Win8GameKit repository has also been updated if you prefer to follow the project there.