Treasure Data Unity SDK Quickstart

The Unity SDK for Treasure Data. With this SDK, you can import the events on your applications into Treasure Data easily.

Setup

Download this Unity package and import it into your Unity project using Assets -> Import Package -> Custom Package.

For iOS Application Development

On Xcode, the following steps are needed:

1. Add Treasure Data iOS SDK to your Podfile as following:

platform :ios, '12.0'

target 'Unity-iPhone' do
  use_frameworks!
  inherit! :search_paths
end


target 'UnityFramework' do
  use_frameworks!

  pod 'TreasureData-iOS-SDK', '= 1.0.1'
end

Basic Usage

Instantiate the TreasureData object with your API Key

public class MyTreasureDataPlugin : MonoBehaviour {
#if UNITY_IPHONE || UNITY_ANDROID
  [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]
  static void OnRuntimeInitialization() {
    TreasureData.InitializeApiEndpoint("https://us01.records.in.treasuredata.com");
    TreasureData.InitializeApiKey("YOUR_API_KEY");
  }
#endif
}

Add an Event to a Local Buffer

To add a event to a local buffer, use the AddEvent function.

TreasureData.Instance.AddEvent("testdb", "unitytbl", ev);

Dictionary<string, object> ev = new Dictionary<string, object>();
ev["str"] = "strstr";
ev["int"] = 12345;
ev["long"] = 12345678912345678;
ev["float"] = 12.345;
ev["double"] = 12.3459832987654;
ev["bool"] = true;
TreasureData.Instance.AddEvent("testdb", "unitytbl", ev,
    delegate() {
        Debug.LogWarning ("AddEvent Success!!!");
    },
    delegate(string errorCode, string errorMsg) {
        Debug.LogWarning ("AddEvent Error!!! errorCode=" + errorCode + ", errorMsg=" + errorMsg);
    }
);

Specify the database and table to which you want to import the events. The total length of database and table must be shorter than 129 chars.

Upload Events to Treasure Data

To upload buffered events to Treasure Data, use the UploadEvents function. You can call this API to upload buffered events whenever you want.

TreasureData.Instance.UploadEvents();

TreasureData.Instance.UploadEvents (
    delegate() {
        Debug.LogWarning ("UploadEvents Success!!! ");
    },
    delegate(string errorCode, string errorMsg) {
        Debug.LogWarning ("UploadEvents Error!!! errorCode=" + errorCode + ", errorMsg=" + errorMsg);
    }
);

The characteristics of your application will determine when and how often to upload buffered events. Treasure Data recommends that you upload at the following times:

• When the current screen is closing or moving to background
• When closing the application

UploadEvents buffers for a few minutes before the import into Treasure Data storage begins.

Retry uploading and deduplication

This SDK imports events in exactly once style with the combination of these features.

• This SDK keeps buffered events with adding unique keys and retries to upload them until confirming the events are uploaded and stored on server side (at least once)
• The server side remembers the unique keys of all events within the past hour by default and prevents duplicated imports (at most once)

Start/End session

When you call StartGlobalSession method, the SDK generates a session that's kept until EndGlobalSession is called. The session id will be output as a column name "td_session_id" in Treasure Data. Also, you can get the session id with GetGlobalSessionId.

TreasureData.InitializeDefaultDatabase("testdb");
td = new TreasureData("your_api_key");
print("Session ID = " + TreasureData.GetSessionId());   // >>> (null)

TreasureData.StartGlobalSession();
print("Session ID = " + TreasureData.GetSessionId());   // >>> cad88260-67b4-0242-1329-2650772a66b1
    :
TreasureData.Instance.AddEvent("testdb", "unitytbl", ev);
    :
TreasureData.EndGlobalSession();
print("Session ID = " + TreasureData.GetSessionId());   // >>> (null)
    :
TreasureData.Instance.AddEvent("testdb", "unitytbl", ev);

// Outputs =>>
//   [{"td_session_id":"cad88260-67b4-0242-1329-2650772a66b1",
//       ..., "time":1418880000},
//        :
//    {..., "time":1418880123}
//   ]

The session continues from when StartGlobalSession is called until EndGlobalSession is called. If StartGlobalSession is called within 10 seconds of an EndGlobalSession call, then the previous session resumes; a new session is not created.

If you want to use instance-level, fine-grained sessions, you can use TreasureData#StartSession(tableName) / TreasureData#EndSession(tableName) / TreasureData#GetSessionId(), which add a session event at calling StartSession / EndSession and don't have the session resume feature.

Advanced Usage

Tracking Application Lifecycle Events

The SDK can be optionally enabled to automatically captures app lifecycle events (disabled by default). You must explicitly enable this option. You can set the target table through DefaultTable:

[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]
static void OnRuntimeInitialization() {
  // TreasureData client setup...
  TreasureData.DefaultTable = "app_lifecycles";
  TreasureData.Instance.EnableAppLifecycleEvent();
}

There are three kinds of events that are tracked automatically:

• Application Open
• Install
• Update

{
    "td_unity_event": "TD_UNITY_APP_OPEN",
    "td_app_ver": "1.0",
    ...
}

{
    "td_unity_event": "TD_UNITY_APP_INSTALL",
    "td_app_ver": "1.0",
    ...
}

{
    "td_unity_event": "TD_UNITY_APP_UPDATE",
    "td_app_ver": "1.1",
    "td_app_previous_ver": "1.0",
    ...
}

Tracking In-App Purchase Events

If enabled, the Treasure Data SDK can automatically tracks IAP events without having to listen and call addEvent yourself. Enable or disable this feature using the following:

TreasureData.sharedInstance.enableInAppPurchaseEvent();

TreasureData.sharedInstance.disableInAppPurchaseEvent();

Depending on the native platform your application is running on, the event's schema might be different:

For the more details of these columns' value please see the Android / iOS SDK documentation.

• Android SDK - IAP Tracking
• iOS SDK - IAP Tracking

Additional Configuration

Endpoint

The API endpoint (default: [ https://us01.records.in.treasuredata.com ]) is modified using the InitializeApiEndpoint:

TreasureData.InitializeApiEndpoint("https://us01.records.in.treasuredata.com");

Encryption Key

If you've set an encryption key via TreasureData.InitializeEncryptionKey(), the SDK saves the event data as encrypted when it calls AddEvent.

TreasureData.InitializeEncryptionKey("hello world");
    :
TreasureData.Instance.AddEvent("testdb", "unitytbl", ev);

Default Database

TreasureData.InitializeDefaultDatabase("testdb");
    :
TreasureData.Instance.AddEvent("unitytbl", ev);

Adding the UUID of the Device Automatically to Each Event

The UUID of the device is added to each event automatically if you call EnableAutoAppendUniqId. This value won't change until the application is uninstalled.

TreasureData.Instance.EnableAutoAppendUniqId();
    :
TreasureData.Instance.AddEvent("unitytbl", "name", "foobar");
// Outputs =>>
//   {"td_uuid_id":"cad88260-67b4-0242-1329-2650772a66b1", "name":"foobar", ... }

It outputs the value as a column name td_uuid.

Adding an UUID to Each Event Record Automatically

The UUID will be added to each event record automatically if you call EnableAutoAppendRecordUUID. Each event has different UUID.

TreasureData.Instance.EnableAutoAppendRecordUUID();
// If you want to customize the column name, pass it to the API
// TreasureData.Instance.EnableAutoAppendRecordUUID("my_record_uuid");
    :
TreasureData.Instance.AddEvent(...);

It outputs the value as a column name record_uuid by default.

Adding the Device Model Information to Each Event Automatically

Device model information is added to each event automatically if you call EnableAutoAppendModelInformation.

TreasureData.Instance.EnableAutoAppendModelInformation();
    :
TreasureData.Instance.AddEvent("unitytbl", "name", "foobar");
// Outputs =>>
//   {"td_device":"iPod touch", "name":"foobar", ... }

It outputs the following column names and values:

• iOS
  • td_device : UIDevice.model
  • td_model : UIDevice.model
  • td_os_ver : UIDevice.model.systemVersion
  • td_os_type : "iOS"
• Android
  • td_board : android.os.Build#BOARD
  • td_brand : android.os.Build#BRAND
  • td_device : android.os.Build#DEVICE
  • td_display : android.os.Build#DISPLAY
  • td_model : android.os.Build#MODEL
  • td_os_ver : android.os.Build.VERSION#SDK_INT
  • td_os_type : "Android"

Adding Application Package Version Information to Each Event Automatically

Application package version information is added to each event automatically if you call EnableAutoAppendAppInformation.

TreasureData.Instance.EnableAutoAppendAppInformation();
    :
TreasureData.Instance.AddEvent("unitytbl", "name", "foobar");
// Outputs =>>
//   {"td_app_ver":"1.2.3", "name":"foobar", ... }

It outputs the following column names and values:

• iOS
  • td_app_ver : Core Foundation key CFBundleShortVersionString
  • td_app_ver_num : Core Foundation key CFBundleVersion
• Android
  • td_app_ver : android.content.pm.PackageInfo.versionName (from Context.getPackageManager().getPackageInfo())
  • td_app_ver_num : android.content.pm.PackageInfo.versionCode (from Context.getPackageManager().getPackageInfo())

Adding Locale Configuration Information to Each Event Automatically

Locale configuration information will be added to each event automatically if you call EnableAutoAppendLocaleInformation.

TreasureData.Instance.EnableAutoAppendLocaleInformation();
    :
td.AddEvent("unitytbl", "name", "foobar");
// Outputs =>>
//   {"td_locale_lang":"en", "name":"foobar", ... }

It outputs the following column names and values:

• iOS
  • td_locale_country : [ [NSLocale currentLocale] objectForKey: NSLocaleCountryCode]
  • td_locale_lang : [ [NSLocale currentLocale] objectForKey: NSLocaleLanguageCode]
• Android
  • td_locale_country : java.util.Locale.getCountry() (from Context.getResources().getConfiguration().locale)
  • td_locale_lang : java.util.Locale.getLanguage() (from Context.getResources().getConfiguration().locale)

Enable/Disable Debug Log

TreasureData.EnableLogging();

TreasureData.DisableLogging();

Error codes

The TreasureData.Instance.AddEvent and TreasureData.Instance.UploadEvents call the onError delegate method with an errorCode argument. This argument is useful for determining the cause or type of the error. Here are the error code arguments:

• init_error : The initialization failed.
• invalid_param : The parameter passed to the API was invalid
• invalid_event : The event was invalid
• data_conversion : Failed to convert the data to/from JSON
• storage_error : Failed to read/write data in the storage
• network_error : Failed to communicate with the server due to network problem
• server_response : The server returned an error response

GDPR Compliance

The SDK provide some convenient methods to easily opt-out of tracking the device entirely without having to resort to many cluttered if-else statements:

<treasure_data_instance>.DisableCustomEvent()         // Opt-out of your own events
<treasure_dataa_instance>.DisableAppLifecycleEvent()  // Opt-out of TD generated events

These can be opted back in by calling EnableCustomEvent() or EnableAppLifecycleEvent(). Note that these settings persist across application restarts. Generally these methods should be called when reflecting your user's choice, not every time the SDK is initialized. By default custom events are enabled and app lifecycles events are disabled.

• Use ResetUniqId() to reset the identification of device on subsequent events. td_uuid will be randomized to another value and an extra event is captured with {"td_unity_event": "forget_device_id", "td_uuid": <old_uuid>} to the DefaultTable .

Development mode to run application without real devices

This SDK works as an Unity Native Plugin. So you need to run your application with the SDK on a real device especially when you want to run it on iOS platform.

If you want to run your application with the SDK without real devices, you can do that with a special mode for development that emulates the behavior with a pure C# implementation.

Configuration

• On PC / iOS / Android / other platforms
  • Add a symbol TD_SDK_DEV_MODE to Player Settings > Scripting Define Symbols
• On Unity Editor
  • Always enabled. No action required.

Modify source code

• Create SimpleTDClient instance by calling SimpleTDClient.Create() static method in MonoBehaviour#Start method
• Attach the instance to TreasureData instance

public class TreasureDataExampleScript : MonoBehaviour {
    private static TreasureData td = null;
    // private TreasureData tdOnlyInTheScene = null;
            :
    void Start () {
        td = new TreasureData("YOUR_WRITE_APIKEY");
        /* Optional configurations
            SimpleTDClient.SetDummyAppVersionNumber("77");
            SimpleTDClient.SetDummyBoard("bravo");
            SimpleTDClient.SetDummyBrand("htc_asia_wwe");
            SimpleTDClient.SetDummyDevice("bravo");
            SimpleTDClient.SetDummyDisplay("ERE27");
            SimpleTDClient.SetDummyModel("HTC Desire");
            SimpleTDClient.SetDummyOsVer("2.1");
            SimpleTDClient.SetDummyOsType("android");
            SimpleTDClient.SetDummyLocaleCountry("JP");
            SimpleTDClient.SetDummyLocaleLang("ja");
        */

        // If you want to use a TDClient over scenes, pass `true` to `SimpleTDClient.Create` to prevent it from being removed.
        td.SetSimpleTDClient(SimpleTDClient.Create(true));

        // If you want to use a TDClient only within a scene, don't pass `true` to `SimpleTDClient.Create` so that you can prevent object leaks.
        // tdOnlyInTheScene.SetSimpleTDClient(SimpleTDClient.Create());
            :

Further Reading

• Unity SDK API Reference