Skip to main content
Gainsight Inc.

Gainsight PX C# SDK

This article explains how to install Gainsight PX .NET SDK for your desktop applications.

Overview 

Gainsight PX introduces Desktop SDK for .NET for desktop applications. The SDK supports the ability to create, read, update, or delete User and Account records.

Key Features

Developer friendly Gainsight PX SDK has the following features:

  • Tracking back-end data and services
  • Operationalize engagement lifecycle 
  • Fetch/update usage data and metadata

Enabling The Desktop Channel

Desktop channel in PX is behind a feature flag, please contact your client outcome manager or account executive to enable desktop tracking.

Install .NET SDK

Download the SDK from the product section

clipboard_ef66cca0a3fc732b6f6f131c7578e7577.png

Add it as a reference to your project. Ensure that you also have Newtonsoft.Json as Nuget dependency in your project. (Additional dependencies if required are listed below)

Initialize

Create an instance of the Gainsight.Client with your API key and Configuration to start sending events data.

using System;
using System.Threading;
using GainsightPX;
using GainsightPX.Model;


namespace PXDesktop
{
    class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Gainsight PX SDK - Hello world");
            Logger.Handlers += (level, message, args) =>
            {
                Console.WriteLine($"{level}: {message}");
            };
            
            Config config = new Config.Builder() {
                //durable tracking
                DurableQueueDirectoryName = "C:\\Cache_Folder_Name",
                //Max number of events
                QueueLimit = 1000,
                
                //Setting EU data-center (default is US)
                //DataCenter = Config.PXHost.EU,
                
                //session emulation : 30min
                SessionTimeout = new System.TimeSpan(0, 30, 0)
            }.Build();
            
         // PLEASE USE YOUR PRODUCT KEY HERE:   
         String _gainsightPxProductKey = "AP-CHANGE-ME-PLEASE-4";
         Gainsight.Initialize(_gainsightPxProductKey, config);
         
         //Avoid exit demo app
         Thread.Sleep(3000);
     }
   }
}

Configuration

This section describes variables, whose configurations can be modified by you during the initialization stage.

Property Type Default Description
Host string Null All data requests are sent to the given host.
Proxy string Null The proxy string for IWebProxy.
Timeout TimeSpan

5sec

The timeout for HTTP request.
PXUserId string UUID Unique identifier for a user, will be overridden with server given ID after Identify call
LogLevel Level .NONE Which log level should logs should be passed on to Logger Handlers.
SessionTimeout TimeSpan 30min Timeout for session

QueueLimit

int

100 The limitation for memory/disk cache.
DurableQueueDirectoryName string Null The name of directory for disk cache option.
DurableQueueEncryption IStorageEncryption Null Encryption used to store data on disk.

On the Config object used for initialization there are several attributes that can be used for caching:

  • QueueLimit -  numeric. Limiting the number of events we store in the queue.
  • DurableQueueDirectoryName -  string (file system location).
  1. Memory storage: (default) storing events in-memory.
  2. Disk storage: persisting events to a durable queue to support offline scenarios. This option is enabled when DurableQueueDirectoryName is set.
  • DurableQueueEncryption -  implementation of the IStorageEncryption interface for encrypting queued events on disk.
  • Note: this is not referring to network encryption which is enabled by default.  

Identify

Pass the user information on log-in.

// IDENTIFY
Gainsight.Client.Identify(
  //user id
  new User("some-user-uuid")
  {
    //optional
    Email = "user@email.com",
    FirstName = "Elon",
    LastName = "Musk",
   },
   new Account("some-account-uuid")
   {
      Name = "Gainsight",
      WebSite = "www.gainsight.com"
 });

Event Tracking

Send custom events with information about the events on your app.

//TRACK
Gainsight.Client.Track("FileUpload", new Dict { 
    { "title", "Software" }, 
    { "name", "PX" }, 
    { "size", 9000 }, 
    { "uploaded", new DateTime(2002, 7, 7, 9, 30, 50) } 
 }); 

Global Context

Once you create all the required events, you can set events with a global context. You can set a global context with key-value pairs and send it with the payload. Global context can be set on Date, String, Double, Int and Boolean data types. Global Context data is stored at the memory level and not disk-level. The key-value pairs are sent with the payloads. If the application is terminated, all the key-value pairs are erased. 

Use the following code snippet to set globalContext:

Gainsight.Client.SetContext(<#string#>, <#Double#>)

The SetContext method in turn returns a Client object. Below provided is a sample of globalContext usage.

Example:

//GLOBAL CONTEXT - Tracking releases and user entitlement
Gainsight.Client.SetContext("dateTime", DateTime.UtcNow)
                .SetContext("double", 2.0)
                .SetContext("int", 9)
                .SetContext("string", "book")
                .SetContext("bool", true);

Along with SetContext, below mentioned are other methods to get context for a key, remove context for a key and for getting all keys of a context.

object GetContextForKey(string Key);
bool RemoveContextForKey(string Key);
ICollection<string> GetContextKeys();

Example:

var value = Gainsight.Client.GetContextForKey(<#string#>);
var isRemoved = Gainsight.Client.RemoveContextForKey(#string#);
var keys = Gainsight.Client.GetContextKeys();

Flush

Calling flush directly will send all events in the queue to the server without waiting for the next automatic flush. Usually, you don't need to call it directly, but there are some cases(when using memory cache and wanting to flush all events before close of application) where you might want to make sure that the events are flushed.

Below mentioned are the methods that can be used to flush the events: 

void Flush();
Task FlushAsync();

Success/Failed Handlers

On registering to Succeeded and Failed handlers, one will be notified of any exceptions that occurred while creating track events and in case of failing the API request or succeeding the API request on sending the events to the server.

Succeeded will provide BaseAction object and Failed will provide Error along with BaseAction object. BaseAction object will have information regarding the event.

Example:     

Gainsight.Client.Succeeded += (action) =>
            {
                Console.WriteLine($"Event Sent: {action.Type} - {action.MessageId}");
            };
            Gainsight.Client.Failed += (action, error) =>
            {
                Console.WriteLine($"Event failed to sent: {action.Type} - {action.MessageId}: {error.Message}");
            };       

Other

Checking the queue status 

HasPendingEvents method will return a boolean value of whether there are pending events in cache that need to be routed to the server.

Example:

var hasPendingEvents = Gainsight.Client.HasPendingEvents();

Config

Config property returns Config object used to initialize the Gainsight.

Example:

var config = Gainsight.Client.Config;

Dependencies


For all versions:

  • Newtonsoft.Json - 12.0.3v

  1. For netstandard1.3:

    • System.Threading.Thread - 4.3.0v

    • System.Text.RegularExpressions - 4.3.1v

  2. For net35:

    • AsyncBridge.Net35 - 0.2.0v

    • jnm2.ReferenceAssemblies.net35 - 1.0.0v

  3. For net45:

    • System.Net.Http - 4.3.4v

    • Microsoft.NETFramework.ReferenceAssemblies - 1.0.0v

  4. For net461:

    • System.Net.Http - 4.3.4v

    • Microsoft.NETFramework.ReferenceAssemblies - 1.0.0v

  • Was this article helpful?