Integrating the Tapstream Windows 8 SDK

First, get the latest Windows 8 SDK.

Adding the SDK to your project

Extract TapstreamMetrics.winmd from the SDK zip file.
Open your project in Visual Studio.
Right click on your project in the Solution Explorer, and select "Add", then "Reference...".
Click the "Browse" button and select TapstreamMetrics.winmd from the location you extracted it to.

Importing and initializing the SDK

In your project's main activity file, import the Tapstream SDK:

using TapstreamMetrics.Sdk;

Then, in the constructor of your main application class, create the Tapstream singleton with your account name and SDK secret:

Config config = new Config();
Tapstream.Create("TAPSTREAM_ACCOUNT_NAME", "TAPSTREAM_SDK_SECRET", config);

Tracking in-app purchase events

If you charge money in your app, you may wish to send a purchase event so that the value can be tracked in your Tapstream dashboard.

To send a purchase event, use one of the alternate Event constructors:

// Arguments are: transactionId, productId, quantity, priceInCents, currencyCode
Event e = new Event("3da541559918a", "com.myapp.coinpack100", 1, 299, "USD");
Tapstream.Instance.FireEvent(e);

If you don't know or cannot provide the price and currency of the transaction in your app, you can omit these details. The value of the purchase event will then be determined by the value that you set in your Tapstream dashboard. Eg:

// Arguments are: transactionId, productId, quantity
Event e = new Event("3da541559918a", "com.myapp.coinpack100", 1);
Tapstream.Instance.FireEvent(e);

Collecting hardware identifiers

Tapstream collects the App-Specific Hardware ID (ASHWID) automatically.

Firing SDK events

The SDK will fire two types of events automatically:

An install event, the first time the app runs
An open event, every time the app runs.

The install event is called [platform]-[appname]-install, and the open event is called [platform]-[appname]-open, where [platform] is the device's platform (iOS, Android, etc.) and [appname] is your app's shortname.

Additional SDK events

You may fire additional events from anywhere in your code. This is useful for tracking engagement events, user progress, and other LTV metrics.

Firing an event is simple and can be done like this:

Event e = new Event("created-account", false);
Tapstream.Instance.FireEvent(e);

This example fires an event called created-account, but you may call your events anything you like. Event names are case insensitive.

The Tapstream SDK is threadsafe, so you may fire events from any thread you wish.

Firing events with custom parameters

Tapstream also allows you to attach key/value pairs to your events. The keys and values must be no more than 255 characters each (once in string form).

Custom event parameters and values are available via the Tapstream postback system, the Reporting tab of the Tapstream dashboard, and the Tapstream API suites.

In the following example, an event called level-complete with custom parameters for score and skill is fired.

Tapstream tracker = Tapstream.Instance;

Event e = new Event("level-complete", false);
e.AddPair("score", 15000);
e.AddPair("skill", "easy")
tracker.FireEvent(e);

Global custom event parameters

You may find that you have some data that needs to be attached to every single event sent by the Tapstream SDK. Instead of writing the code to attach this data in each place that you send an event, add these data values to the global event parameters member of the config object. The parameters in this dictionary will automatically be attached to every event, including the automatic events fired by the SDK.

For example:

Config config = new Config();
config.GlobalEventParams["user_id"] = "92429d82a41e";

Verifying your SDK integration

Once you've completed the integration, you can log in to your Tapstream dashboard and verify that your integration is delivering events to Tapstream. Run your app and visit the Events section of the dashboard. You should now see at least one event, like platform-myapp-install.

The SDK status light in the header of the dashboard will now be green to indicate that Tapstream has received an event from your integration.

Controlling logging

The log output of Tapstream can be redirected (or quelled) by providing a handler to receive the messages.

Make sure to define the logging behavior before you initialize the SDK.

Here's how you might redirect Tapstream messages to a custom logging system:

class ConsoleLogger : Logger
{
    public void Log(LogLevel level, string msg)
    {
        MyCustomLoggingSystem(msg);
    }
}

...

Logging.SetLogger(new ConsoleLogger());

Changing hardware ID collection

You can suppress the automatic collection of the ASHWID by adding the following line to your Tapstream config:

// This hardware identifier will be automatically collected and sent
// unless you opt-out by setting it to false, as shown here.
config.CollectAppSpecificHardwareId = false;

If you need to collect deprecated hardware IDs, you can add them to your config as shown here:

// This hardware identifier will not be collected automatically.
// If you wish to send it, you must opt-in by providing a value, as shown here:
config.Odin1 = "<ODIN-1 value goes here>";

Changing the default events

Automatic install and open events can be renamed, and automatic install, open, and iOS purchase events may suppressed entirely by modifying the config object that you used to instantiate the SDK. For example, if you wanted to rename the install and open events, you would set the config object like this:

config.InstallEventName = "my-install-event";
config.OpenEventName = "my-open-event";

If you wanted to suppress the automatic install, open, and iOS purchase events, you would set the config object like this:

config.FireAutomaticInstallEvent = false;
config.FireAutomaticOpenEvent = false;

Setting up campaigns

Running reports

APIs

Advanced

Tapstream SDKs