From Ninja Metrics Developer Hub

IntegrationExamples: Unity

Getting Started
The Unity integration example is based on the Photon Angry Bots demo game by Unity Technologies and Photon. To get started, you will need a working Unity development environment and the Unity project from our GIT repository.

Note:

Please make sure when implementing Unity that SSL support is added for the Ninja Metrics certs.

JSON Content Type - When sending JSON data to the Ninja Metrics API it is required to properly set the "Content Type" header to "application/json". A lot of packages do this automatically, but if you receive a 415 error then that is likely the cause.

  1. Download and install the Unity development environment, available at http://unity3d.com/unity/download. For this example, we will also be using the optionally included "MonoDevelop" environment.
  2. Pull the Unity project from our GIT repository at http://bitbucket.org/ninja_metrics/katana-unity-integration-example.
  3. Download the SimpleJSON library from http://wiki.unity3d.com/index.php/SimpleJSON.
  4. Create a free Photon Cloud account at https://www.exitgames.com/en/Account/SignUp and save a copy of your Application ID.
  5. Start the Unity development environment. Go to File→Open Project.
  6. Choose "Open Other" and point it to the directory that you downloaded the example project to.
  7. Once the import process finishes, you will see a popup for the Photon Unity Networking service. Click "Setup" and enter the Application ID you received after registration.
  8. Add the JSON library by selecting Assets→Import Package→Custom Package. Point it to the SimpleJSON.unitypackage file.

Now you're ready to begin adding scenes to your build settings.

  1. Go to File→Open Scene. In the "\Assets\Scenes" subdirectory, choose 0_Preloader.unity.
  2. Go to File→Build Settings. Leave the default options and click the "Add Current" button to add this scene.
  3. Repeat steps 1 and 2 for the other scenes: 1_BeginScene, 2_AngryBots_MP, 3_EndScene.

Next, compile the project in MonoDevelop. If you're using Windows and installed Unity to a non-default location, you will first need to update the various .csproj and .unityproj files to point to your Unity install directory. You will have to replace all occurrences of C:\Program Files (x86)\Unity with the correct path, as well as all occurrences of C:/Program Files (x86)/Unity with the correct path using forward slashes.

  1. Go to Assets→Sync MonoDevelop Project.
  2. Once MonoDevelop opens, choose Open a Solution. Select the katana-unity-integration-example.sln file.
  3. Compile the project under Build→Build All. Note there may be a compilation error on line 93 of AccountServices.cs, which can be fixed by removing the default parameter setting (“= null”) of the last parameter.
  4. If you're using OS X, you may need to add a reference to the Assembly-CSharp-firstpass project in order to build successfully. To do so, in the Solution pane expand Assembly-CSharp, control-click References, and choose Edit References. Click the Projects tab, check the box next to Assembly-CSharp-firstpass, and click OK. The solution should now build.

The project can now be run from within the Unity environment.

  1. Switch back to the Unity development environment.
  2. Go to File→Open Scene and select the 0_Preloader scene.
  3. Click the Play button or choose Edit→Play.
  4. Within the game window, you can create a new game room and join it.
  5. Click the Play button again to terminate the game.

Web Requests in Unity

To send requests to Ninja Metrics within a Unity game we are utilizing the WWW class provided by UnityEngine http://docs.unity3d.com/Documentation/ScriptReference/WWW.html. This provides a small utility module for making requests to a server asynchronously, without blocking the rest of the game. The process of initializing and sending a request begins as soon as the WWW object is instantiated. For making the HTTPS POST requests required by the JSON API, the WWW constructor takes a String for the url, byte[ ] for the POST data which will contain the JSON payload, and a Hashtable for request headers. Since the requests are made asynchronously, if the developer wishes to examine the response, the proper design pattern in Unity is to wait for the response inside a coroutine. A coroutine will execute in parallel and can be paused at any point using a yield statement. The coroutine will resume and then inspect the response by using the WWW request object as the yield return value. Note it is not necessary to implement a coroutine to make a successful request from Unity in the standard use case. It is only needed if the developer wishes to inspect the response for debugging or error handling purposes.

This example implements three different events: the Create Account event, the Login event, and the Logout event.

Create Account Event (#9) from MainMenu.cs line 43: 

    // Build the Ninja Metrics API Endpoint with the following parameters:
    // client_id: the id of the client on the dashboard
    // app_id: the id for this game/app on the dashboard
    // app_pwd: the password or access token for this app on the dashboard
    // api_client: JSON since this is a direct request to the Ninja JSON API
    string ninjaApiEndpoint = "https://api.ninjametrics.com/event?client_id=1086&app_id=5056&app_pwd=baa50601ad3bc3a2c2177d83b75fd826&api_client=JSON";
    // Build json payload.
    JSONClass payload = new JSONClass();
    // UTC ISO-8601 timestamp.
    string timestamp = DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ss.fffZ");
    payload.Add("timestamp", new JSONData(timestamp));
    JSONClass data = new JSONClass();
    data.Add("type", new JSONData(9)); // Create Account event type
    data.Add("account_id", new JSONData("ninja@example.com"));
    data.Add("account_sub_type", new JSONData("Free"));
    data.Add("account_lang", new JSONData("en-US"));
    data.Add("account_country", new JSONData("US"));
    data.Add("account_gender", new JSONData("N"));
    data.Add("account_dob", new JSONData(new DateTime(1985, 7, 12).ToString("o"))); // "o" is a UTC ISO-8601 format
    data.Add("account_currency_balance", new JSONData(0));
    data.Add("platform", new JSONData("Unity-" + Application.platform)); // Deployed platform
    payload.Add("data", data);
    // Convert json to byte data for WWW object POST data.
    byte[] postData = Encoding.ASCII.GetBytes(payload.ToString().ToCharArray());
    // Build request headers.
    Hashtable headers = new Hashtable();
    headers.Add ("Content-Type", "application/json");
    // Create a WWW object that will send a request and receive its response.
    WWW request = new WWW(ninjaApiEndpoint, postData, headers);
    // Start a coroutine to wait for the response in parallel.
    // This is only required if you wish to inspect the response
    // for error handling or debugging purposes.
    StartCoroutine(WaitForRequest(request));

Login Event (#1) from MainMenu.cs line 133: 

    // Build the Ninja Metrics API Endpoint with the following parameters:
    // client_id: the id of the client on the dashboard
    // app_id: the id for this game/app on the dashboard
    // app_pwd: the password or access token for this app on the dashboard
    // api_client: JSON since this is a direct request to the Ninja JSON API
    string ninjaApiEndpoint = "https://api.ninjametrics.com/event?client_id=1086&app_id=5056&app_pwd=baa50601ad3bc3a2c2177d83b75fd826&api_client=JSON";
    // Build json payload.
    JSONClass payload = new JSONClass();
    // UTC ISO-8601 timestamp.
    string timestamp = DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ss.fffZ");
    payload.Add("timestamp", new JSONData(timestamp));
    JSONClass data = new JSONClass();
    data.Add("type", new JSONData(1)); // Login event type
    data.Add("account_id", new JSONData("ninja@example.com"));
    data.Add("character_id", new JSONData("ninja"));
    data.Add("shard_id", new JSONData(0));
    data.Add("platform", new JSONData("Unity-" + Application.platform)); // Deployed platform
    data.Add("area_id", new JSONData(0));
    payload.Add("data", data);
    // Convert json to byte data for WWW object POST data.
    byte[] postData = Encoding.ASCII.GetBytes(payload.ToString().ToCharArray());
    // Build request headers.
    Hashtable headers = new Hashtable();
    headers.Add ("Content-Type", "application/json");
    // Create a WWW object that will send a request and receive its response.
    WWW request = new WWW(ninjaApiEndpoint, postData, headers);
    // Start a coroutine to wait for the response in parallel. For this 
    // implementation, this is required because a call to 
    // Application.LoadLevel was made directly below and the request object 
    // could be destroyed before it's completed. To guarantee the request is 
    // made we moved the loading of the level to this coroutine.
    StartCoroutine(WaitForRequestAndLoadNextLevel(request));
    // Moved to inside the above coroutine to ensure the request is sent.
    //Application.LoadLevel(Application.loadedLevel + 1);

Logout Event (#2) from GameManager.cs line 119 

    // Send successful Logout event to Ninja Metrics.
    // For the purpose of this demo we consider leaving a room a Logout event.
    // Build the Ninja Metrics API Endpoint with the following parameters:
    // client_id: the id of the client on the dashboard
    // app_id: the id for this game/app on the dashboard
    // app_pwd: the password or access token for this app on the dashboard
    // api_client: JSON since this is a direct request to the Ninja JSON API
    string ninjaApiEndpoint = "https://api.ninjametrics.com/event?client_id=1086&app_id=5056&app_pwd=baa50601ad3bc3a2c2177d83b75fd826&api_client=JSON";
    // Build json payload.
    JSONClass payload = new JSONClass();
    // UTC ISO-8601 timestamp.
    string timestamp = DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ss.fffZ");
    payload.Add("timestamp", new JSONData(timestamp));
    JSONClass data = new JSONClass();
    data.Add("type", new JSONData(2)); // Logout event type
    data.Add("account_id", new JSONData("ninja@example.com"));
    data.Add("character_id", new JSONData("ninja"));
    data.Add("shard_id", new JSONData(0));
    data.Add("platform", new JSONData("Unity-" + Application.platform)); // Deployed platform
    data.Add("area_id", new JSONData(0));
    payload.Add("data", data);
    // Convert json to byte data for WWW object POST data.
    byte[] postData = Encoding.ASCII.GetBytes(payload.ToString().ToCharArray());
    // Build request headers.
    Hashtable headers = new Hashtable();
    headers.Add ("Content-Type", "application/json");
    // Create a WWW object that will send a request and receive its response.
    WWW request = new WWW(ninjaApiEndpoint, postData, headers);
    // Start a coroutine to wait for the response in parallel. For this 
    // implementation, this is required because a call to 
    // Application.LoadLevel was made directly below and the request object 
    // could be destroyed before it's completed. To guarantee the request is 
    // made we moved the loading of the level to this coroutine.
    StartCoroutine(WaitForRequestAndLoadNextLevel(request));
    // Moved to inside the above coroutine to ensure the request is sent.
    //Application.LoadLevel(Application.loadedLevel + 1);

Common coroutine functions used by events: 

/**
   * A Coroutine that waits for the request to return a response, so it can be   
   * inspected.
   * 
   * @param a WWW object to inspect
   **/
IEnumerator WaitForRequest(WWW request)
{
  // Wait for the response from Ninja Metrics.
  yield return request;
  // Inspect the response.
  if (request.error != null)
  {
    // An error occurred.
    Debug.Log("Error: " + request.error);
  }
  else
  {
    // Response was received.
    Debug.Log("Response: " + request.text);
  }
}

Debugging the Unity Application
If you wish to step through the various calls, within MonoDevelop choose Run→Attach to Process. Select the Unity Editor process and click Attach. After setting desired breakpoints, run the game from within the Unity environment. When a breakpoint is hit, the MonoDevelop taskbar item will flash, and you may switch to that window and start debugging.

Retrieved from https://developer.ninjametrics.com/IntegrationExamples/Unity
Page last modified on August 22, 2014, at 10:36 PM