Gainsight PX C# SDK

Initialize 

Create an instance of the Gainsight.Client with your API key and Configuration to start sending events. You can also change some of the default settings for the improved performance of the Gainsight client.

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");
          Config config = new Config.Builder()
          {
Enabled = true,
          //This is optional. Use only for debugging.
          LogLevel = Logger.Level.DEBUG,
          //durable tracking
          DurableQueueDirectoryName = "C:\\Cache_Folder_Name",
          QueueLimit = 1000,
          //session emulation
          SessionTimeout = new System.TimeSpan(0, 30, 0)
          }.Build();
          String _gainsightPxProductKey = "AP-CHANGE-ME-PLEASE-4";
          Gainsight.Initialize(_gainsightPxProductKey, config);
     
          //Avoid exit demo app until messages have a chance to send to PX
          Thread.Sleep(3000);
    }
  }
}

Configuration

This section describes some of the variables, for which you can modify the configurations during the initialization stage. Configuration properties are explained in the Configuration Tables section of this article.

The following are a few attributes used for caching in the Config object used for initialization:

• QueueLimit: Limits the number of events that are stored in the queue. This attribute is applicable to both the queue options (memory and disk).

• DurableQueueDirectoryName: The file system location for disk queue.
  There are two types of queuing:

  • Memory Queue: This is the default configuration. It stores the events only in the memory, without accessing the disk. As this type of queue is not persistent, all the events that are not sent to the server are erased when the application is closed.

  • Disk Queue: This queue saves the events to the disk so the events are not erased in case the application is closed. To use the Disk queue, the developer must provide a path to the folder where the events are saved. This option is enabled when DurableQueueDirectoryName is set.

• DurableQueueEncryption - IStorageEncryption implementation. For the Disk cache, the developer can also implement the IStorageEncryption interface to apply encryption on the stored data. The encryption input and output are strings, and the output should not contain newline characters or any special characters.

Example:

In this example, the SDK will write to the C:\GPX folder. Gainsight recommends that you set QueueLimit and encryption strategy.

Config config = new Config.Builder() {
  DurableQueueDirectoryName = "C:\\GPX",
  DurableQueueEncryption = null, // add your own IStorageEncryption implementation if needed
  QueueLimit = 1000
}.Build();

Gainsight.Client.Enabled = true; // or false
Is the same as
Gainsight.Client.Config.Enabled = true; // or false
And
Gainsight.Client.EngagementsEnabled = true; // or false
Is the same as
Gainsight.Client.Config.EngagementsEnabled = true; // or false

Config config = new Config(){
...
};

Config config = new Config.Builder(){
...
}.Build();

Tracking Pre-identified User operations

You can send events to the server even before the user is identified, and those events are shown as the user events after the identify operation. In order to achieve that, GainsightPX allocates a local ID (PXVisitorId) that is sent with all events. The identifier is generated every time when Gainsight PX is being initiated so you can cache this value and provide it back to the configuration on the following runs.

Example:

string cachedId = "GET_ID_FROM_DURABLE_CACHE";
Config.Builder configBuilder = new Config.Builder() {
      …
};
configBuilder.PXVisitorId = cachedId;
var config = configBuilder.Build();SAVE_TO_DURABLE_CACHE(config.PXVisitorId);

Logging

There are several logging options you can use to get some insight on how well the SDK is working.

           Logger.Handlers += (level, message, args) =>
          {
              Console.WriteLine($"{level}: {message}");
          };

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}");
          };

Identify

By identifying the user who is using the app, you can generate more accurate information about their application usage.

Note:

The user id field is the only mandatory field. The custom attributes can be configured by navigating to Administration > Attributes.

/*PLEASE CHANGE TO REAL UUIDs*/
string userid = "UNIQUE_USER_ID";
string accountid = "COMPANY_ID";

/* EXAMPLE */

Gainsight.Client.Identify(
  new User(userid) {
      /* optional user attributes */
      /* will be set by PX or you can override: */
      SignUpDate = new DateTime(2002, 7, 7, 9, 30, 50),
     
      /* See the list of default optional attribute in PX admin UI */
      Email = "user@email.com",
      RegionName = "NorthAmerica",
      CountryName = "Canada",
      Role = "Consultant",
       CustomAttributes = new Dict()
          .Add("objective", "analytics")          .Add("isAdmin", true)
  },
  /*optional*/
  new Account(accountid) {
      Name = "Gainsight",
      WebSite = "www.gainsight.com"
});

IMPORTANT: Starting from version 1.3.0, developers can use any IDictionary<string, object> instead of Dict.

The minimum requirement for this call is the user id. Each user should be uniquely identified in the system, so they can be identified throughout all devices. You can also identify the user from User and Account objects. While creating one of these objects, you must use user ID (Account ID is not the same as User ID). You can add more attributes as additional information about the user. The CustomAttributes in User and Account is of Dict<string, object> type. The value of Dict should be built-in types. The key strings used in CustomAttributes are case-sensitive.

Custom Events

Custom events allow you to track specific events of your choice that you want to see on your dashboard.

Notes:

• You need to use constant custom event names.
• The actual runtime entity name should be passed via the payload. For example, fileName.

To see the full list of Custom events that are created, navigate to Administration > Events.

//This method will be named Track

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

IMPORTANT: Starting from version 1.3.0, developers can use any IDictionary<string, object> instead of Dict.

Properties can be added to elaborate on the event that happened as shown in the above example.

//This method will be named Track

Gainsight.Client.Track("DesktopError", new Dict {
  { "errorMessage", "Failed to upload file" },
  { "errorCode", "ERR-403" }
});

Global Context

After creating all the required events, set events with a global context. 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 terminates, all the key-value pairs are erased.

Note: Global context fields are automatically generated in PX Dashboard on creating global context from SDK.

Use the following code snippet to set globalContext:

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

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

Example:

Gainsight.Client.SetContext("dateTime", DateTime.UtcNow)
              .SetContext("double", 2.0)
              .SetContext("int", 9)
              .SetContext("string", "book")
              .SetContext("bool", true);
             
Example
Gainsight.Client.SetContext("LifeCycleStage", "Release") /* beta/release */
              /* version */
              .SetContext("VersionFull", "2022.1.673")
              .SetContext("VersionMajorMinor", "2022.1")
              .SetContext("VersionBuild", "673")
              /* beta */
              .SetContext("IsSandbox", false)
              /* localization */
              .SetContext("Language", "en-CA")
             
              /* Device */
              .SetContext("Memory", 40707)
              .SetContext("Architecture", "x64")
              .SetContext("OperatingSystem", "Microsoft Windows NT 10.0.19044.0")
             
              /* Graphics*/
              .SetContext("Graphics.Graphics.ResolutionWidth", 1920)
              .SetContext("Graphics.Graphics.ResolutionHeight", 1080)
              .SetContext("Graphics.OpenGL", "NVIDIA Corporation")
              .SetContext("Graphics.Configuration", "NVIDIA Quadro P520")
              .SetContext("Graphics.ConfigurationDriver", "30.0.14.7291 (2021-12-12)");

Along with SetContext, use the following methods to get context for a key, remove context for a key and to get 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();

void Flush();

HasPendingEvents

var hasPendingEvents = Gainsight.Client.HasPendingEvents();

var key = Gainsight.Client.WriteKey;

var config = Gainsight.Client.Config;

Setting Reference Control

Starting from version 1.3.1, developers have the ability to set the Form or Control (on WinForm) / Window or FrameworkElement(WPF) that they want the engagement to be shown in.

Gainsight.Client.SetEngagementReference(<#Your control#>);

Surveys

Surveys help you gain insights into customer opinions and enhance your product or services. Surveys are useful to assess product usage patterns, derive insights, and identify risks. Using surveys, you can measure customer satisfaction at a granular level.

Survey Engagements are a great means to drive communication between you and your customers. Using Survey Engagements, you can launch in-app surveys on desktop applications.

Gainsight PX offers five types of Survey Engagements to suit your business requirements:

• NPS® (Net Promoter Score)
• CES  (Customer Effort Score)
• Rating
• Boolean
• Multi Question

Create Survey Engagement 

To create Survey Engagement from your Gainsight desktop SDK:

1. From the left pane, click Engagements. 
2. Click Create.
3. Enter a name for your engagement.
4. Select the type of target application: Desktop.

5. Select the type of survey you need to create. The NPS® option is selected by default.
6. Enter a description.
7. Click Create. 
8. In the Audience step of the smart wizard on the left, select the target audience based on user, account and/or behavioral rules. 
9. Choose a template in the Templates step.
10. Customize the look and feel by using the Editor tab and optionally display the ‘Thank you’ step.

11. On the Settings tab, check the style, content placement, title and so on. 
12. (Optional) Set the View Type (Dialogue or Bar) and Position of the Survey engagement to be displayed on the screen.
13. Click Save.
14. Set the date range and intervals you would like to collect survey results from users. For more information about scheduling, refer to the Engagement Scheduler article from the Additional Resources section.
    1. Select the Time zone and the Recurring option in the Scheduler section.
    2. Select the Intervals checkbox to show the Survey Engagement multiple times with recurring intervals during a specific time period.
15. On the launch step, review the configurations and click Launch.

Survey Analytics 

Gainsight PX allows you to measure feature adoption or engaged users based on their responses using Engagement Analytics. To learn more about how you can follow up with the users who did not take the survey, refer to the articles from the Additional Resources section.

To learn about all frequently asked questions, refer to the Surveys FAQs article from the Additional Resources section.

Best Practices

Gainsight recommends the following best practices for creating survey engagements:

• Coordinate survey requirements across departments to create a comprehensive strategy and avoid survey burn-out.
• Solicit NPS® feedback quarterly for fresh data every three months, but choose criteria to rotate your distribution list.
• Connect PX to your Slack channel to get real-time feedback. For more information, refer to the Gainsight PX Slack Integration article from the Additional Resources section.