Integrating the Tapstream Unity SDK

First, download the latest Unity SDK.

This document assumes you are using Unity to target both Android and iOS.

Integrating the SDK

Download and extract the Tapstream Unity SDK.
Copy the resulting Tapstream.cs file and Plugins directory, and paste them into the Assets directory of your Unity project.
If your project does not already contain Assets/Plugins/Android/AndroidManifest.xml, you'll need to create it.

To do this, use the default Unity manifest as a template. It can be found at:
- Windows: <Unity install dir>/Editor/Data/PlaybackEngines/androidplayer/AndroidManfiest.xml
- Mac: /Applications/Unity/Unity.app/Contents/PlaybackEngines/AndroidPlayer/AndroidManifest.xml
Request the necessary Android permissions by adding the following three elements as a child of the manifest element in Assets/Plugins/Android/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />

Importing and initializing the SDK

Initialize the SDK early in your game by calling Tapstream's Create method:

Tapstream.Config conf = new Tapstream.Config();
conf.Set("idfa", "<IDFA goes here>");
Tapstream.Create("TAPSTREAM_ACCOUNT_NAME", "TAPSTREAM_SDK_SECRET", conf);

We strongly recommend that you collect and provide the iOS Advertising Identifier (IDFA) value to the Tapstream SDK. Please see Apple's documentation on collecting the IDFA.

Firing extra events

By default, Tapstream fires an event whenever the SDK is initialized. You can define further events for recording key actions in your game by using the syntax below:

// Regular event:
Tapstream.Event e = new Tapstream.Event("test-event", false);
Tapstream.FireEvent(e);

// Regular event with custom parameters:
Tapstream.Event e = new Tapstream.Event("test-event", false);
e.AddPair("my-custom-param", 3);
Tapstream.FireEvent(e);

// One-time-only event:
Tapstream.Event e = new Tapstream.Event("test-event", true);
Tapstream.FireEvent(e);

// One-time-only event with custom parameters:
Tapstream.Event e = new Tapstream.Event("test-event", true);
e.AddPair("my-custom-param", "hello world");
Tapstream.FireEvent(e);

Note: Custom event parameters are not exposed in Tapstream's dashboard. The key/value pairs are exposed via Tapstream's postback system and Conversion API. Custom parameters are usually used for integration with a third-party ad network or your in-house dashboard or CRM.

Changing the default behavior of the Tapstream SDK

Note: Changing this behavior is not usually required.

To change the default Tapstream config, provide config overrides like this:

Tapstream.Config conf = new Tapstream.Config();
conf.Set("idfa", "<IDFA goes here>");
conf.Set("collectWifiMac", false);
conf.Set("collectDeviceId", true);
conf.Set("installEventName", "custom-install-event-name");
Tapstream.Create("TAPSTREAM_ACCOUNT_NAME", "TAPSTREAM_SDK_SECRET", conf);

Consult the platform-specific SDK documentation to see what config variables are available on each platform.

First-run app experience modification

The Tapstream SDK gives you a mechanism for receiving a callback that will contain everything Tapstream knows about the user's timeline, including any links the user clicked on or websites of yours they visited before running the app.

If you want to customize the behavior of your application based on the user's source campaign, click parameters, or other pre-install behavior, you'll need to asynchronously request this info from the SDK.

In most cases, a response is available to the SDK almost immediately, but in exceptional circumstances, it may take up to 10 seconds for the SDK to receive a response or return nil. So, this feature makes use of UnitySendMessage on both iOS and Android to implement an asynchronous callback.

Here's how it works:

Whenever you would like to request conversion data, you can make a call to Tapstream.GetConversionData, passing as arguments the name of the target GameObject and method name that will accept the callback. These will be used later to in the call to UnitySendMessage:

Tapstream.GetConversionData("GameObject1", "HandleGetConversion");

Then, on your MonoBehavior, create a method to handle the conversion

void HandleGetConversion(string jsonSerializedConversionData)
{
    if (jsonSerializedConversionData != null) {
        // Do something with the data
    }
}

Notice that the callback receives a JSON description of the data, in string form. You will need to deserialize this data with the JSON library of your choice to use it.

An example JSON response might look like this:

{
  "hits": [
    // This is an array of all hits (e.g. campaign clicks and website visits) associated with this user.
    {
      "custom_parameters": { // All custom query string parameters
        "__deeplink": "trending://stocks/", // If available, the deeplink destination you defined for this platform
        "campaign-name": "TESTING"
      },
      "created": 1383695050683,
      "ip": "199.21.86.54",
      "app": "tapfoliotrending",
      "session_id": "2b3d397e-4674-11e3-a2a0-525400f1a7ad",
      "tracker": "example-campaign", // The slug of the campaign link
      "dest_url_platform": "ANY",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 7_0_3 like Mac OS X) AppleWebKit/537.51.1 (KHTML, like Gecko) Version/7.0 Mobile/11B511 Safari/9537.53",
      "referrer": "",
      "device_specific_hardware_ids": {
        "ios_idfa": "141E8456-3D20-46D1-92F8-8EE0728BE7BF"
      },
      "id": "2b3d608f-4674-11e3-a2a0-525400f1a7ad",
      "dest_url": "http://itunes.apple.com/us/app/stocks-trending-stocks-at-a-glance/id512068016?ls=1&mt=8"
    }
  ],
  "events": [
    // This is an array of all in-app events associated with this user.
    {
      "profile_model": "iPhone5,1",
      "profile_gmtoffset": 4294938496,
      "profile_resolution": "640x1136",
      "created": 1383695183000,
      "ip": "199.21.86.54",
      "app": "tapfoliotrending",
      "profile_sdkversion": "2.4",
      "session_id": "df9b7f5d-ca9c-4ef3-a0b9-1e66795eef5e",
      "package_name": "com.paperlabs.TapfolioTrending",
      "tracker": "ios-trending-open", // The slug of the event
      "profile_os": "iPhone OS 7.0.3",
      "profile_vendor": "Apple",
      "device_specific_hardware_ids": {
        "ios_idfa": "142D8456-4E70-46D1-92F8-8EE0728BE7BF",
        "ios_secure_udid": "EAAD91D5-EAEA-40BC-A244-13A3D7748F95"
      },
      "app_name": "Trending",
      "id": "7a1f50ce-4674-11e3-a312-525400d091e2",
      "profile_locale": "en_US",
      "profile_platform": "iOS"
    },
  ]
}

If you wish to simulate conversions to test this functionality, please refer to the documentation on simulating Tapstream conversions.

Setting up campaigns

Running reports

APIs