C++ web analytics for Snowplow

Snowplow is a scalable open-source platform for rich, high quality, low-latency data collection. It is designed to collect high quality, complete behavioral data for enterprise business.

To find out more, please check out the Snowplow website and our documentation.

Snowplow C++ Tracker Overview

Snowplow C++ tracker enables you to add analytics to your C++ applications, servers and games when using a Snowplow pipeline.

Quick Start

The tracker currently supports macOS and Windows.

Installation

Download the most recent release from the releases section. Everything in both the src and include folders will need to be included in your application. It is important to keep the same folder structure as references to the included headers have been done like so: ../include/json.hpp.

Using the tracker

Import and initialize the tracker with your Snowplow collector endpoint and tracker configuration:

#include "tracker.hpp"

using namespace snowplow;

// Emitter is responsible for sending events to a Snowplow Collector
Emitter emitter("com.acme.collector", Emitter::Method::POST, Emitter::Protocol::HTTP, 500, 52000, 52000, "sp.db");
// Subject defines additional information about your application's environment and user
Subject subject;
subject.set_user_id("a-user-id");
// Client session keeps track of user sessions
ClientSession client_session("sp.db", 5000, 5000);

string platform = "pc"; // platform the tracker is running on
string app_id = "openage"; // application ID
string name_space = "sp-pc"; // the name of the tracker instance
bool base64 = false; // whether to enable base 64 encoding
bool desktop_context = true; // add a context entity to events with information about the device

Tracker *tracker = Tracker::init(emitter, &subject, &client_session, &platform, &app_id, &name_space, &base64, &desktop_context);

Track custom events (see the documentation for the full list of supported event types):

// structured event
Tracker::StructuredEvent se("category", "action");
tracker->track_struct_event(se);

// screen view event
Tracker::ScreenViewEvent sve;
string name = "Screen ID - 5asd56";
sve.name = &name;
tracker->track_screen_view(sve);

Check the tracked events in a Snowplow Micro or Snowplow Mini instance.

Developer Quick Start

Building on macOS

 host> git clone https://github.com/snowplow/snowplow-cpp-tracker
 host> cd snowplow-cpp-tracker
 host> make

This will create two executables - the first is the test-suite which can be executed with make unit-tests.

The other is an example program which will send one of every type of event to an endpoint of your choosing like so:

 host> cd build
 host> ./tracker_example {{ your collector uri }}

If you make changes only to a header file there is a chance it won't be picked up by make in which case you will need to:

 host> make clean
 host> make

To run the test suite:

 host> make unit-tests

If you wish to generate a local code coverage report you will first need to install lcov on your host machine. The easiest way to do this is using brew:

 host> brew install lcov 

Then run the following:

 host> make lcov-genhtml

The above runs the test suite and then generates a full code coverage report which can be accessed by opening the index.html in the build directory.

Performance testing

The project also provides performance tests to measure changes in performance of the tracker. The tests measure performance under a few scenarios in which they vary the emitter and session.

To run performance tests on your machine:

 host> ./build/performance/tracker_performance

To compare with historical performance measurements (logged in the performance/logs.txt file), run the following Python script that will output a table with the performance comparison:

 host> ./performance/stats.py                                       

 Metric                                | Max     | Min     | Mean    | Last    |
--------------------------------------------------------------------------------
 mocked emitter and mocked session     | 5.27s   | 5.08s   | 5.18s   | 5.27s   |
 mocked emitter and real session       | 5.08s   | 5.04s   | 5.06s   | 5.07s   |
 mute emitter and mocked session       | 18.77s  | 17.29s  | 18.08s  | 18.77s  |
 mute emitter and real session         | 28.02s  | 22.61s  | 25.06s  | 22.61s  |

Building on Windows

git clone https://github.com/snowplow/snowplow-cpp-tracker

In the cloned directory two Visual Studio 2015 project files are available:

• snowplow-cpp-tracker.sln This is required to compile the tracker and run the tests (you'll need this one to edit the tracker itself)
• snowplow-cpp-tracker-example.sln This is a demo project showing use of this tracker

To run the tests under windows, you need to open the snowplow-cpp-tracker.sln solution, build it for your target platform and run the resulting executable.

Find out more

Technical Docs	Setup Guide	Roadmap	Contributing
Technical Docs	Setup Guide	Roadmap	Contributing

Copyright and license

The Snowplow C++ Tracker is copyright 2022 Snowplow Analytics Ltd.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this software except in compliance with the License.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.