Request a Demo Start Trial
These docs are for an old version of DeskMetrics!
Go to the latest docs
Windows Analytics
Download Windows Analytics SDK
version 6.2.0

NSIS Installers

Introduction

This document will walk you through creating an NSIS installer with DeskMetrics Analytics integrated. We’ll be working through the file examples/NSIS/setup_with_analytics.nsi, so open it up and follow along.

We’ll make use of the following files from the SDK zip:

Include the bindings

At the top of the document, include dma.nsh. This is the DeskMetrics Analytics NSIS script that binds to the functionality offered by dma.dll.

Next, define your app key and some of the recommended DeskMetrics properties described in the Data Modelling Guide.

; Include DeskMetrics Analytics
!include "..\..\sdk\dma.nsh"
!include "LogicLib.nsh"

; Your app key - this can be found on the applications page of your DeskMetrics dashboard.
!define APP_KEY "<YOUR_APP_KEY_HERE>"
!define TRACKING_ID "<YOUR_TRACKING_ID_HERE>"
!define SUB_ID "<YOUR_SUB_ID_HERE>"
!define CHANNEL "<YOUR_CHANNEL_HERE>"

Initialize the SDK

Define the .onInit function. This is where we populate the dynamic DeskMetrics properties and initialize the SDK.

Var installTime
Var entityId

Function .onInit
  ; The dll needs to be extracted to the plugins directory before initialization can happen
  InitPluginsDir
  File "/oname=$PLUGINSDIR\dma.dll" "..\..\sdk\dma.dll"  
  ; Collect cloud data entity id 
  ${dmaResolveEntityId} "${APP_KEY}" $entityId

  ; NTP time check that will block, waiting on a response for up to 5000ms (5 seconds).
  ; If a response is not received within that time, the local computer's UTC time will be used.
  ${dmaGetTimestamp} $installTime

  ; Load properties that may have been persisted to the registry by a previous version of the installer
  ; or a previous run of this installer.
  ${dmaLoadProperties} 'HKCU\SOFTWARE\HelloDeskMetrics\_dm' 0

  ; Set some properties that should appear on all events sent by the SDK.  We recommend passing
  ; false as the final parameter to these functions, indicating that the properties should *not* be
  ; overwritten if they were already present in the data loaded from the registry.  This non-overwrite
  ; policy will give us sensible behaviour if this installer is used to update an existing installation
  ; to a newer version.  That is, the analytics events will still maintain the install_time, tracking_id,
  ; sub_id, etc of the original installer.
  ${dmaSetPropertyString} 'tracking_id' ${TRACKING_ID} 0
  ${dmaSetPropertyString} 'sub_id' ${SUB_ID} 0
  ${dmaSetPropertyString} 'channel' ${CHANNEL} 0
  ${dmaSetPropertyString} 'dm.entity_id' $entityId 0
  ${dmaSetPropertyInt64} 'install_time' $installTime 0
  ${dmaSetPropertyString} 'cohort' '$${dm.cohort:install_time}' 0

  ; Save the properties to the registry so they will be available to the application and uninstaller.
  ${dmaSaveProperties} 'HKCU\SOFTWARE\HelloDeskMetrics\_dm' 0

  ; Initialize the analytics SDK and begin the session. This will trigger the automatic 'install_launch' event.
  ${dmaStartInstall} "${APP_KEY}"
FunctionEnd

If you have set up a custom domain for use with the analytics SDK then you can set the SDK to use it by using the ${dmaSetAnalyticsBaseUrl} macro before any of your calls to any of the ${dmaStart*} macros.

; We wanna use our own domain with the analytics sdk
${dmaSetAnalyticsBaseUrl} 'https://custom.mybusiness.com'

; Proceed to start the SDK as usual
${dmaStartInstall} "${APP_KEY}"

Remember that ${dmaSetAnalyticsBaseUrl} should only be called before ${dmaStart*}, otherwise your events wont be sent using your custom domain.

Deploy the files

Define a Section and add the logic to unpack the application files to disk. Unpack dma.dll to the application install directory so it can be used by the application and uninstaller.

Section "Example" SecCopyUI
   SetOutPath "$INSTDIR"

  ; Copy the DeskMetrics DLL to the application install directory
  File "..\..\sdk\dma.dll"
    ; .NET applications will typically need the 64 bit version of the dll as well
  File "..\..\sdk\dma_x64.dll"

  ; The C++ example files
  File "..\HelloDeskMetricsCpp\Release\HelloDeskMetricsCpp.exe"

  ; The .NET example files
  File "..\HelloDeskMetrics.NET\bin\Release\HelloDeskMetrics.NET.exe"
  File "..\HelloDeskMetrics.NET\bin\Release\HelloDeskMetrics.NET.exe.config"
  File "..\HelloDeskMetrics.NET\bin\Release\HelloDeskMetrics.NET.vshost.exe.manifest"
  File "..\HelloDeskMetrics.NET\bin\Release\Newtonsoft.Json.dll"

  ; Deploy an uninstaller to the application install directory
  WriteUninstaller "$INSTDIR\uninst.exe"
SectionEnd

Add a few code hooks

Define the .onInstSuccess, .onUserAbort, and .onInstFailed functions. Each of these functions must stop the DeskMetrics SDK using the appropriate dmaStop* function.

Function .onInstSuccess  
  ; This will trigger the automatic "install" event and then block until all pending events have finished sending.
  ${dmaStopSuccess}
FunctionEnd

Function .onUserAbort
  ; This will trigger the automatic "install" event and then block until all pending events have finished sending.
  ${dmaStopCancel}
FunctionEnd

Function .onInstFailed
  ; This will trigger the automatic "install" event and then block until all pending events have finished sending.
  ${dmaStopFailure}
FunctionEnd

Uninstaller

Define the un.onInit function, load the DeskMetrics properties from the registry, and start the SDK.

Function un.onInit
  ; The dll needs to be extracted to the plugins directory before DeskMetrics can be used
  InitPluginsDir
  CopyFiles "$INSTDIR\dma.dll" "$PLUGINSDIR"

  ; Load properties that were persisted to the registry by the installer.
  ${dmaLoadProperties} 'HKCU\SOFTWARE\HelloDeskMetrics\_dm' 0

  ; Initialize the analytics SDK and begin the session
  ${dmaStartUninstall} ${APP_KEY}
FunctionEnd

Define the un.onInstSuccess, un.onUserAbort, and un.onInstFailed functions. Each of these functions must stop the DeskMetrics SDK using the appropriate dmaStop* function.

Function un.onUninstSuccess
  ; Deinitialize the analytics SDK.
  ; This will trigger the automatic "uninstall" event and then block until all pending events have finished sending.
  ${dmaStopSuccess}
FunctionEnd

Function un.onUserAbort
  ; Deinitialize the analytics SDK.
  ; This will trigger the automatic "uninstall" event and then block until all pending events have finished sending.
  ${dmaStopCancel}
FunctionEnd

Function un.onUninstFailed
  ; Deinitialize the analytics SDK.
  ; This will trigger the automatic "uninstall" event and then block until all pending events have finished sending.
  ${dmaStopFailure}
FunctionEnd

Add your usual uninstall logic. Remember to clean up the DeskMetrics values that were stored in the registry.

Section Uninstall
  ; Clean up files
  RMDir /r "$INSTDIR"
  ; Clean up the registry
  DeleteRegKey HKCU "SOFTWARE\HelloDeskMetrics"
SectionEnd

Custom events

The integration that we’ve done so far will immediately give you powerful analytics about your installs and uninstalls. But what if you want more? Here’s how we might go about firing a completely custom analytics event from within the installer.

Insert the following at the top of your installation section:

; Not required!
; Just for fun, lets send a custom analytics event when the installer starts copying files.
${dmaJsonObjectNew} $R9
${dmaJsonObjectPushString} $R9 "greeting" "Hello DeskMetrics!"
${dmaJsonObjectPushInt64} $R9 "star_rating" 5
${dmaJsonObjectPushBool} $R9 "positive_sentiment" 1
${dmaSendObject} "copying_files" $R9
${dmaJsonObjectFree} $R9