This is a brief guide on how to integrate your Xamarin or Visual Studio app with Kumulos. For more details on interacting with the Kumulos SDK please refer to the Windows 101 Cookbook.

Requirements

An IDE environment such as Visual Studio or Xamarin Studio.

Dependencies

You will require a reference to the NuGet package Json.NET from Newtonsoft, along with a reference to the Kumulos_Windows_1.0.1.dll available from your Kumulos console.

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Newtonsoft.Json;
using Kumulos;
using Kumulos.NET;

The dependency list from our sample app.

Initialization

In your application code where you would like to interact with the Kumulos API, initialize an HttpClient like so:

KumulosHttp apiClient = new KumulosHttp (apiKey, secretKey);

Your API key and secret key can be found in the app dashboard in the Kumulos control panel.

You don't need to initialise a KumulosHttp client every time you wish to make an API call. You can create a singleton and use dependency injection to make it available where required.

Calling your API

To talk to Kumulos you will need:

  • your method title (in lowerCamelCase)
  • an optional method parameters map (field names are also in lowerCamelCase)

Parameter maps

Parameters can be constructed as a standard IDictionary.

var params = new Dictionary<string, string>
{
    { "param1", "value1" },
    { "param2", "value2" }
};

And you're done! You can now make calls to Kumulos API methods from your C# application.

Task<Kumulos.Payload> apiCall = apiClient.CallAsync("getOptionTypesWithOptions", params);

Now, read on for more details on how to read results from the response.

Handling Results

The objects returned in a Kumulos Payload response are generic, but they do implement IEnumerable and can be iterated through to map them to a model object via a factory constructor in your model.

foreach (KumulosObject obj in apiCall.Result) {
  OptionTypeWithOptions.CreateOptionTypeWithOptionsFromKumulosObject(obj);
}

You can create a local model object by using a static constructor for your model which accepts a KumulosObject which it can then read values from using the helpers.

  class Option {
        public static Option CreateOptionFromKumulosObject(KumulosObject obj) {
            DateTime? timeUpdated = null;
            if (obj.GetString ("timeUpdated") != "0000-00-00 00:00:00") {
                timeUpdated = DateTime.Parse (obj.GetString ("timeUpdated"));
            }

            return new Option (
                obj.GetInt("optionID"),
                obj.GetString("title"),
                obj.GetDouble("pricePerUnit"),
                obj.GetInt("isVegetarian") == 1 ? true : false,
                obj.GetInt("type"),
                DateTime.Parse(obj.GetString("timeCreated")),
                timeUpdated
            );
        }

        public Option(int optionId, string title, double pricePerUnit, bool isVegetarian, int type, DateTime timeCreated, DateTime? timeUpdated) {
            this.optionId = optionId;

            this.title = title;
            this.pricePerUnit = pricePerUnit;
            this.isVegetarian = isVegetarian;
            this.type = type;

            this.timeCreated = timeCreated;
            this.timeUpdated = timeUpdated;
        }

        private int optionId;

        private string title;
        private double pricePerUnit;
        private bool isVegetarian;
        private int type;

        private DateTime timeCreated;
        private DateTime? timeUpdated;

        public string GetTitle()
        {
            return title;
        }

        public int GetId() {
            return optionId;
        }
    }