Developer Zone

Quick-Start Guide

System Requirements

The Python SDK can run on any Microsoft Windows machine from XP onwards as long as a version of Python 2.5 or greater is available. This SDK makes use of a native Windows DLL to work. Both x64 and x86 builds of the Trackerbird DLL are provided. The DLLs are statically-linked in order to eliminate any further prerequisites. The correct DLL architecture is selected automatically based on the Python build being used.

Registering Your Product

Before you can use the Trackerbird Software Analytics service or integrate the Trackerbird SDK with your software, you must first register an account by visiting: http://register.trackerbird.com Once you register a username and create a new product account for tracking your application, you can get your Product ID and callhome URL from the Developer Zone (within the login area). From here you can also download the latest version of the SDK.

Importing the SDK Files

Upon downloading the Trackerbird Python SDK, you get a python source file - Trackerbird.py. This must be copied into your source directory, and in order to use it in your application, it must be imported. Apart from the source file, you also receive 2 pairs of the Trackerbird DLL - one for x86 and one for x64 builds. The DLL files must be placed in the bin directory where the Python code needs to be executed from.

In order to download the Trackerbird SDK, you may visit this page.

Basic Integration Steps

The most basic Trackerbird integration can be accomplished by following the steps below. It is however recommended to read the more advanced documentation as Trackerbird can do much more than the basic functionality that can be achieved by following these steps.

  1. Download the latest SDK and extract it to your preferred project location.

  2. Include the Trackerbird SDK into your application (see Importing the SDK Files).

  3. Initialize the SDK configuration similar to the below example. Your callhome URL and product ID can be retrieved from the Trackerbird Developer Zone (inside your login area). “Multiple Sessions Enabled” (multiSessionsEnabled parameter) is a boolean value where you specify whether your application can have multiple user sessions per runtime session. This is normally false for desktop applications. For further details, refer to Single vs. Multiple session modes. All other parameters are strings or unicode strings.

    Trackerbird.createConfig("<Callhome URL>", "<Product ID>",
    "<Your product's version>", "<Your product's build number>",
    <Multiple Sessions Enabled>)
    
  4. Call the function appStart(). You must call this function first, before making any other Trackerbird API calls. It is recommended that you place this call at the entry point of your application so the Trackerbird SDK knows exactly at what time your application runtime session was started. If using multi-session mode, you also need to call sessionStart() when a user session is started, and also provide a unique user session ID which you will then also use for closing the session or for Feature / Event Tracking.

  5. Call on appStop() when closing your application so the Trackerbird SDK knows when your application runtime session has been closed. If using multi-session mode, when user sessions are closed, you should call sessionStop() and send the ID of the session that is being closed as a parameter.

  6. All of the other functions in the Trackerbird API can be called at any point in your application as long as the Trackerbird SDK has been initialized by calling appStart().

The following is an example of the basic integration outlined below. This example uses single-session mode.

import Trackerbird

#Initialize the Trackerbird Configuration
purl = "http://INSERT-YOUR-URL"
pproduct_id = "INSERT-YOUR-PROD-ID"
pproduct_version= "1.2.3"
pproduct_build_number = "4567"
pmulti_session_enabled = False
Trackerbird.createConfig(purl, pproduct_id, pproduct_version, pproduct_build_number, pmulti_session_enabled)

#Inform Trackerbird that a new runtime session has been started.
Trackerbird.appStart()

#Your program logic...

#Program closing - inform Trackerbird that this runtime session is closing down.
Trackerbird.appStop()

#Your program logic...

Next Steps

In the above section, we covered the basic integration steps. While these steps would work for most software products, it is recommended to do some further reading in order to get the most of what Trackerbird has to offer. It is recommended to go into more detail by reading the pages SDK Configuration and Basic SDK Control. Once you are familiar with the SDK, you may look at the advanced features.

Advanced Features

By following the Basic Integration Steps above, the Trackerbird SDK will be able to collect information about how often users run your product, how long they are engaged with your software as well as which versions and builds they are running. The SDK also collects information on what platforms and architectures your software is being run (i.e. OS versions, language, screen resolution, etc.). Once you have implemented the basic features, you may choose to use Trackerbird for more advanced features which include: