Collecting data with Trackers and Webhooks

  1. Home
  2. Docs
  3. Collecting data with Trackers and Webhooks
  4. Trackers – collecting data from your own applications
  5. C++ tracker
  6. Initialisation

Initialisation

Import the library

Import the C++ Tracker library like so:

#include "tracker.hpp"

That’s it – you are now ready to initialize a tracker instance.

Creating a tracker

You will first need to create an Emitter to which events will be sent:

#include "tracker.hpp" Emitter emitter("com.acme.collector", Emitter::Method::POST, Emitter::Protocol::HTTP, 500, 52000, 52000, "events.db"); Tracker *t = Tracker::init(emitter, NULL, NULL, NULL, NULL, NULL, NULL);

The Tracker can now be used. It is created as a static singleton object so as to avoid conflicts between multiple Trackers reading and writing to a single database. You can access a pointer to the Tracker by either the Tracker::init(...) function or by the Tracker::instance() function. To ensure the Tracker is cleaned up properly you will need to run Tracker::close() in your main destructor.

NOTE: If you attempt to access the instance without having first run init an exception will be thrown.

The optional tracker arguments:

Argument NameDescriptionRequired?Default
emitterThe emitter to which events are sentYesNULL
subjectThe user being trackedNoNULL
client_sessionClient session recordingNoNULL
platformThe platform the Tracker is running onNosrv
app_idThe application IDNo
name_spaceThe name of the tracker instanceNo
use_base64Whether to enable base 64 encodingNotrue
desktop_contextWhether to add a desktop_context to eventsNotrue

A more complete example:

Emitter emitter("com.acme.collector", Emitter::Method::GET, Emitter::Protocol::HTTPS, 500, 52000, 52000, "sp.db"); Subject subject; subject.set_user_id("a-user-id"); subject.set_screen_resolution(1920, 1080); subject.set_viewport(1080, 1080); subject.set_color_depth(32); subject.set_timezone("GMT"); subject.set_language("EN"); ClientSession client_session("sp.db", 5000, 5000, 2500); string platform = "pc"; string app_id = "openage"; string name_space = "sp-pc"; bool base64 = false; bool desktop_context = true; Tracker *t = Tracker::init(emitter, &subject, &client_session, &platform, &app_id, &name_space, &base64, &desktop_context);

NOTE: To ensure all of your events are sent before closing your application you can call the tracker flush function which is a blocking call that will send everything in the database and then will join the daemon thread to the calling thread.

emitter

Accepts an argument of an Emitter instance pointer; if the object is NULL will throw an exception. See Emitters for more on emitter configuration.

subject

The user which the Tracker will track. Accepts an argument of a Subject instance pointer.

You don’t need to set this during Tracker construction; you can use the tracker.set_subject(...) method afterwards. In fact, you don’t need to create a subject at all. If you don’t, though, your events won’t contain user-specific data such as timezone and language.

client_session

The client sessions which the Tracker will attach to each event. Accepts an argument of a ClientSession instance pointer.

Adds the ability to attach a ClientSession context to each event that leaves the Tracker. This object operates on a daemon thread and will persistently store information about the sessions that have occurred for the life of the application – unless the database is destroyed.

platform

By default we assume the Tracker will be running in a server environment. To override this provide your own platform string.

app_id

The app_id argument lets you set the application ID to any string.

name_space

If provided, the name_space argument will be attached to every event fired by the new tracker. This allows you to later identify which tracker fired which event if you have multiple trackers running.

use_base64

By default, unstructured events and custom contexts are encoded using Base64 to ensure that no data is lost or corrupted.

desktop_context

The desktop_context gathers extra information about the device it is running on and sends it along with every event that is made by the Tracker.

An example of the data in this context:

{ "deviceManufacturer": "Apple Inc.", "deviceModel": "MacPro3,1", "deviceProcessorCount": 8, "osIs64Bit": true, "osServicePack": "", "osType": "macOS", "osVersion": "10.11.2" }

For more information the raw JsonSchema can be found here.