{"id":27627236,"url":"https://github.com/treasure-data/td-unity-sdk-package","last_synced_at":"2025-04-23T13:53:44.587Z","repository":{"id":19432177,"uuid":"22675708","full_name":"treasure-data/td-unity-sdk-package","owner":"treasure-data","description":"Unity SDK for TreasureData","archived":false,"fork":false,"pushed_at":"2023-09-13T23:24:22.000Z","size":64079,"stargazers_count":3,"open_issues_count":0,"forks_count":8,"subscribers_count":87,"default_branch":"master","last_synced_at":"2024-04-10T19:38:20.420Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://docs.treasuredata.com/articles/unity-sdk","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/treasure-data.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null}},"created_at":"2014-08-06T08:39:58.000Z","updated_at":"2022-05-23T17:15:28.000Z","dependencies_parsed_at":"2022-09-25T06:21:40.113Z","dependency_job_id":"c0a68bd1-ecc4-4733-98aa-582a0d47f76a","html_url":"https://github.com/treasure-data/td-unity-sdk-package","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/treasure-data%2Ftd-unity-sdk-package","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/treasure-data%2Ftd-unity-sdk-package/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/treasure-data%2Ftd-unity-sdk-package/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/treasure-data%2Ftd-unity-sdk-package/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/treasure-data","download_url":"https://codeload.github.com/treasure-data/td-unity-sdk-package/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250444247,"owners_count":21431614,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-23T13:53:43.777Z","updated_at":"2025-04-23T13:53:44.574Z","avatar_url":"https://github.com/treasure-data.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"Treasure Data Unity SDK\n===============\n\nUnity SDK for [Treasure Data](http://www.treasuredata.com/). With this SDK, you can import the events on your applications into Treasure Data easily.\n\n## Installation\n\nDownload this [Unity package](https://github.com/treasure-data/td-unity-sdk-package/raw/master/TD-Unity-SDK-0.1.10.unitypackage) and import it  into your Unity project using `Assets -\u003e Import Package -\u003e Custom Package`.\n\n### For iOS Application development\n\n* Add Treasure Data iOS SDK to your `Podfile` as following:\n\n```\nplatform :ios, '12.0'\n\ntarget 'Unity-iPhone' do\n  use_frameworks!\n  inherit! :search_paths\nend\n\n\ntarget 'UnityFramework' do\n  use_frameworks!\n\n  pod 'TreasureData-iOS-SDK', '= 1.0.1'\nend\n```\n\n\n## Usage\n\n### Instantiate TreasureData object with your API key\n\n```\npublic class MyTreasureDataPlugin : MonoBehaviour {\n#if UNITY_IPHONE || UNITY_ANDROID\n  [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]\n  static void OnRuntimeInitialization() {\n    TreasureData.InitializeApiEndpoint(\"https://us01.records.in.treasuredata.com\");\n    TreasureData.InitializeApiKey(\"YOUR_API_KEY\");\n  }\n#endif\n}\n```\n\nWe recommend to use a write-only API key for the SDK. To obtain one, please:\n\n1. Login into the Treasure Data Console at http://console.treasuredata.com;\n2. Visit your Profile page at http://console.treasuredata.com/users/current;\n3. Insert your password under the 'API Keys' panel;\n4. In the bottom part of the panel, under 'Write-Only API keys', either copy the API key or click on 'Generate New' and copy the new API key.\n\n\n### Add a event to local buffer\n\nTo add a event to local buffer, you can call `TreasureData`'s `AddEvent` API.\n\n\n```\nDictionary\u003cstring, object\u003e ev = new Dictionary\u003cstring, object\u003e();\nev[\"str\"] = \"strstr\";\nev[\"int\"] = 12345;\nev[\"long\"] = 12345678912345678;\nev[\"float\"] = 12.345;\nev[\"double\"] = 12.3459832987654;\nev[\"bool\"] = true;\nTreasureData.Instance.AddEvent(\"testdb\", \"unitytbl\", ev,\n    delegate() {\n        Debug.LogWarning (\"AddEvent Success!!!\");\n    },\n    delegate(string errorCode, string errorMsg) {\n        Debug.LogWarning (\"AddEvent Error!!! errorCode=\" + errorCode + \", errorMsg=\" + errorMsg);\n    }\n);\n\n// Or, simply...\n//   TreasureData.Instance.AddEvent(\"testdb\", \"unitytbl\", ev);\n```\n\nSpecify 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.\n\n### Upload Events to TreasureData\n\nTo upload events buffered events to Treasure Data, you can call `TreasureData`'s `UploadEvents` API.\n\n```\n// You can call this API to uplaod buffered events whenever you want.\nTreasureData.Instance.UploadEvents (\n    delegate() {\n        Debug.LogWarning (\"UploadEvents Success!!! \");\n    },\n    delegate(string errorCode, string errorMsg) {\n        Debug.LogWarning (\"UploadEvents Error!!! errorCode=\" + errorCode + \", errorMsg=\" + errorMsg);\n    }\n);\n\n// Or, simply...\n//    TreasureData.Instance.UploadEvents();\n```\n\nIt depends on the characteristic of your application when to upload and how often to upload buffered events. But we recommend the followings at least as good timings to upload.\n\n- When the current screen is closing or moving to background\n- When closing the application\n\nThe sent events is going to be buffered for a few minutes before they get imported into Treasure Data storage.\n\n### Retry uploading and deduplication\n\nThis SDK imports events in exactly once style with the combination of these features.\n\n- 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)\n- The server side remembers the unique keys of all events within the past 1 hours by default and prevents duplicated imports (at most once)\n\nAs for the deduplication window is 1 hour by default, so it's important not to keep buffered events more than 1 hour to avoid duplicated events.\n\n### Start/End session\n\nWhen 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 TreasureData. Also, you can get the session id with `GetGlobalSessionId`.\n\n```\nTreasureData.InitializeDefaultDatabase(\"testdb\");\ntd = new TreasureData(\"your_api_key\");\nprint(\"Session ID = \" + TreasureData.GetSessionId());   // \u003e\u003e\u003e (null)\n\nTreasureData.StartGlobalSession();\nprint(\"Session ID = \" + TreasureData.GetSessionId());   // \u003e\u003e\u003e cad88260-67b4-0242-1329-2650772a66b1\n\t:\nTreasureData.Instance.AddEvent(\"testdb\", \"unitytbl\", ev);\n\t:\nTreasureData.EndGlobalSession();\nprint(\"Session ID = \" + TreasureData.GetSessionId());   // \u003e\u003e\u003e (null)\n\t:\nTreasureData.Instance.AddEvent(\"testdb\", \"unitytbl\", ev);\n// Outputs =\u003e\u003e\n//   [{\"td_session_id\":\"cad88260-67b4-0242-1329-2650772a66b1\",\n//\t\t ..., \"time\":1418880000},\n//        :\n//    {..., \"time\":1418880123}\n//   ]\n```\n\nAs long as `StartGlobalSession` has been called but `EndGlobalSession` hasn't been called, the session is continued. Also, if `StartGlobalSession` is called again within 10 seconds of the last calling `EndGlobalSession`, then the session will be resumed, instead of a new session being created.\n\nIf you want to use instance level fine grained sessions, you can use `TreasureData#StartSession(tableName)` / `TreasureData#EndSession(tableName)` / `TreasureData#GetSessionId()`, which add an session event at calling `StartSession` / `EndSession` and don't have session resume feature.\n\n\n## Tracking Application Lifecycle Events\n\nThe 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`:\n\n```\n[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]\nstatic void OnRuntimeInitialization() {\n  // TreasureData client setup...\n  TreasureData.DefaultTable = \"app_lifecycles\";\n  TreasureData.Instance.EnableAppLifecycleEvent();\n}\n```\n\nThere are 3 kinds of event that are tracked automatically: Application Open, Install and Update. These events will be captured along with relevant metadata depends on the specific type of event:\n\n_Application Open_\n\n```\n{\n    \"td_unity_event\": \"TD_UNITY_APP_OPEN\",\n    \"td_app_ver\": \"1.0\",\n    ...\n}\n```\n\n_Application Install_\n\n```\n{\n    \"td_unity_event\": \"TD_UNITY_APP_INSTALL\",\n    \"td_app_ver\": \"1.0\",\n    ...\n}\n```\n\n_Application Update_\n\n```\n{\n    \"td_unity_event\": \"TD_UNITY_APP_UPDATE\",\n    \"td_app_ver\": \"1.1\",\n    \"td_app_previous_ver\": \"1.0\",\n    ...\n}\n```\n\n\n## Tracking In-App Purchase Events\n\nIf enabled, TreasureData SDK can automatically track IAP events without having to listen and call `addEvent` yourself. Enable this feature by:\n\n```\nTreasureData.sharedInstance.enableInAppPurchaseEvent();\n```\n\nAlthough always disabled by default (unlike the option app lifecycle and custom events, this choice is not persisted), you could explicitly disable this feature by:\n\n```\nTreasureData.sharedInstance.disableInAppPurchaseEvent();\n```\n\nDepends on the native platform in which the game is running on, the event's schema could be different:\n\nOn Android, the IAP event's columns consist of:\n\n- `td_android_event`\n- `td_iap_product_id`\n- `td_iap_order_id`\n- `td_iap_product_price`\n- `td_iap_quantity`\n- `td_iap_product_price_amount_micros`\n- `td_iap_product_currency`\n- `td_iap_purchase_time`\n- `td_iap_purchase_token`\n- `td_iap_purchase_state`\n- `td_iap_purchase_developer_payload`\n- `td_iap_product_type`\n- `td_iap_product_title`\n- `td_iap_product_description`\n- `td_iap_package_name`\n- `td_iap_subs_auto_renewing`\n- `td_iap_subs_status`\n- `td_iap_subs_period`\n- `td_iap_free_trial_period`\n- `td_iap_intro_price_period`\n- `td_iap_intro_price_cycless`\n- `td_iap_intro_price_amount_micros`\n\nWhile on iOS:\n\n- `td_ios_event`\n- `td_iap_transaction_identifier`\n- `td_iap_transaction_date`\n- `td_iap_quantity`\n- `td_iap_product_identifier`\n- `td_iap_product_price`\n- `td_iap_product_localized_title`\n- `td_iap_product_localized_description`\n- `td_iap_product_currency_code`.\n\nConsult [TreasureData Android SDK - IAP Tracking](https://github.com/treasure-data/td-android-sdk#track-in-app-purchase-events-automatically) and [TreasureData iOS SDK - IAP Tracking](https://github.com/treasure-data/td-ios-sdk#app-lifecycle-events) for the further details of these columns' value.\n\n## About error code\n\n`TreasureData#AddEvent()` and `UploadEvents()` call back `onError` delegate method with `errorCode` argument. This argument is useful to know the cause type of the error. There are the following error codes.\n\n- `init_error` :  The initialization failed.\n- `invalid_param` : The parameter passed to the API was invalid\n- `invalid_event` : The event was invalid\n- `data_conversion` : Failed to convert the data to/from JSON\n- `storage_error` : Failed to read/write data in the storage\n- `network_error` : Failed to communicate with the server due to network problem \n- `server_response` : The server returned an error response\n\n\n## GDPR Compliance\n\nThe SDK provide some convenient methods to easily opt-out of tracking the device entirely without having to resort to many cluttered if-else statements:\n\n```\n\u003ctreasure_data_instance\u003e.DisableCustomEvent()         // Opt-out of your own events\n\u003ctreasure_dataa_instance\u003e.DisableAppLifecycleEvent()  // Opt-out of TD generated events\n```\n\nThese can be opted back in by calling `EnableCustomEvent()` or `EnableAppLifecycleEvent()`. Note that these settings are saved persistently, so it survives across app launches. Generally these methods should be called when reflecting your user's choice, not on every time initializing the SDK. By default custom events are enabled and app lifecycles events are disabled. \n\n- 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\": \u003cold_uuid\u003e}` to the `DefaultTable`.\n\n## Additional Configuration\n\n### Endpoint\n\nThe API endpoint (default: https://us01.records.in.treasuredata.com) can be modified using the `InitializeApiEndpoint`:\n\n```\nTreasureData.InitializeApiEndpoint(\"https://us01.records.in.treasuredata.com\");\n```\n\n### Encryption key\n\nIf you've set an encryption key via `TreasureData.InitializeEncryptionKey()`, our SDK saves the event data as encrypted when called `AddEvent`.\n\n```\nTreasureData.InitializeEncryptionKey(\"hello world\");\n\t:\nTreasureData.Instance.AddEvent(\"testdb\", \"unitytbl\", ev);\n```\n\n\n### Default database\n\n```\nTreasureData.InitializeDefaultDatabase(\"testdb\");\n\t:\nTreasureData.Instance.AddEvent(\"unitytbl\", ev);\n```\t\n\n### Adding UUID of the device to each event automatically\n\nUUID of the device will be added to each event automatically if you call `EnableAutoAppendUniqId`. This value won't change until the application is uninstalled.\n\n```\nTreasureData.Instance.EnableAutoAppendUniqId();\n\t:\nTreasureData.Instance.AddEvent(\"unitytbl\", \"name\", \"foobar\");\n// Outputs =\u003e\u003e\n//   {\"td_uuid_id\":\"cad88260-67b4-0242-1329-2650772a66b1\", \"name\":\"foobar\", ... }\n```\n\nIt outputs the value as a column name `td_uuid`.\n\n### Adding an UUID to each event record automatically\n\nUUID will be added to each event record automatically if you call `EnableAutoAppendRecordUUID`. Each event has different UUID.\n\n```\nTreasureData.Instance.EnableAutoAppendRecordUUID();\n// If you want to customize the column name, pass it to the API\n// TreasureData.Instance.EnableAutoAppendRecordUUID(\"my_record_uuid\");\n\t:\nTreasureData.Instance.AddEvent(...);\n```\n\nIt outputs the value as a column name `record_uuid` by default.\n\n\n### Adding the device model information to each event automatically\n\nDevice model infromation will be added to each event automatically if you call `EnableAutoAppendModelInformation`.\n\n```\nTreasureData.Instance.EnableAutoAppendModelInformation();\n\t:\nTreasureData.Instance.AddEvent(\"unitytbl\", \"name\", \"foobar\");\n// Outputs =\u003e\u003e\n//   {\"td_device\":\"iPod touch\", \"name\":\"foobar\", ... }\n```\n\nIt outputs the following column names and values:\n\n- iOS\n\t- `td_device` : UIDevice.model\n\t - `td_model` : UIDevice.model\n\t - `td_os_ver` : UIDevice.model.systemVersion\n\t - `td_os_type` : \"iOS\"\n- Android\n\t- `td_board` : android.os.Build#BOARD\n\t- `td_brand` : android.os.Build#BRAND\n\t- `td_device` : android.os.Build#DEVICE\n\t- `td_display` : android.os.Build#DISPLAY\n\t- `td_model` : android.os.Build#MODEL\n\t- `td_os_ver` : android.os.Build.VERSION#SDK_INT\n\t- `td_os_type` : \"Android\"\n\n### Adding application package version information to each event automatically\n\nApplication package version infromation will be added to each event automatically if you call `EnableAutoAppendAppInformation`.\n\n```\nTreasureData.Instance.EnableAutoAppendAppInformation();\n\t:\nTreasureData.Instance.AddEvent(\"unitytbl\", \"name\", \"foobar\");\n// Outputs =\u003e\u003e\n//   {\"td_app_ver\":\"1.2.3\", \"name\":\"foobar\", ... }\n```\n\nIt outputs the following column names and values:\n\n- iOS\n\t- `td_app_ver` : Core Foundation key `CFBundleShortVersionString`\n\t- `td_app_ver_num` : Core Foundation key `CFBundleVersion`\n- Android\n\t- `td_app_ver` : android.content.pm.PackageInfo.versionName (from Context.getPackageManager().getPackageInfo())\n\t- `td_app_ver_num` : android.content.pm.PackageInfo.versionCode (from Context.getPackageManager().getPackageInfo())\n\n### Adding locale configuration information to each event automatically\n\nLocale configuration infromation will be added to each event automatically if you call `EnableAutoAppendLocaleInformation`.\n\n```\nTreasureData.Instance.EnableAutoAppendLocaleInformation();\n\t:\ntd.AddEvent(\"unitytbl\", \"name\", \"foobar\");\n// Outputs =\u003e\u003e\n//   {\"td_locale_lang\":\"en\", \"name\":\"foobar\", ... }\n```\n\nIt outputs the following column names and values:\n\n- iOS\n\t- `td_locale_country` : [[NSLocale currentLocale] objectForKey: NSLocaleCountryCode]\n\t- `td_locale_lang` : [[NSLocale currentLocale] objectForKey: NSLocaleLanguageCode]\n- Android\n\t- `td_locale_country` : java.util.Locale.getCountry() (from Context.getResources().getConfiguration().locale)\n\t- `td_locale_lang` : java.util.Locale.getLanguage() (from Context.getResources().getConfiguration().locale)\n\n\n### Enable/Disable debug log\n\n```\nTreasureData.EnableLogging();\n```\n\n```\nTreasureData.DisableLogging();\n```\n\n## Development mode to run application without real devices\n\nThis 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.\n\nIf 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 behaviour with a pure C# implementation.\n\n### How to use\n\n#### Configuration\n\n- On PC / iOS / Android / other platforms\n  - Add a symbol `TD_SDK_DEV_MODE` to \"Player Settings \u003e Scripting Define Symbols\"\n- On Unity Editor\n  - Always enabled. Nothing to do.\n\n#### Modify source code\n\n- Create `SimpleTDClient` instance by calling `SimpleTDClient.Create()` static method in `MonoBehaviour#Start` method\n- Attach the instance to `TreasureData` instance\n\n```\npublic class TreasureDataExampleScript : MonoBehaviour {\n    private static TreasureData td = null;\n    // private TreasureData tdOnlyInTheScene = null;\n\t\t\t:\n\tvoid Start () {\n\t\ttd = new TreasureData(\"YOUR_WRITE_APIKEY\");\n\t\t/* Optional configurations\n\t\t\tSimpleTDClient.SetDummyAppVersionNumber(\"77\");\n\t\t\tSimpleTDClient.SetDummyBoard(\"bravo\");\n\t\t\tSimpleTDClient.SetDummyBrand(\"htc_asia_wwe\");\n\t\t\tSimpleTDClient.SetDummyDevice(\"bravo\");\n\t\t\tSimpleTDClient.SetDummyDisplay(\"ERE27\");\n\t\t\tSimpleTDClient.SetDummyModel(\"HTC Desire\");\n\t\t\tSimpleTDClient.SetDummyOsVer(\"2.1\");\n\t\t\tSimpleTDClient.SetDummyOsType(\"android\");\n\t\t\tSimpleTDClient.SetDummyLocaleCountry(\"JP\");\n\t\t\tSimpleTDClient.SetDummyLocaleLang(\"ja\");\n\t\t*/\n\n        // If you want to use a TDClient over scenes, pass `true` to `SimpleTDClient.Create` to prevent it from being removed.\n\t\ttd.SetSimpleTDClient(SimpleTDClient.Create(true));\n\n        // 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.\n\t\t// tdOnlyInTheScene.SetSimpleTDClient(SimpleTDClient.Create());\n\t\t\t:\n```\n\n#### Different behaviours from normal mode\n\n- In development mode,\n  - buffered events are stored in memory not in persistent storages.\n  - when running into an upload failure, buffered events get lost.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftreasure-data%2Ftd-unity-sdk-package","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftreasure-data%2Ftd-unity-sdk-package","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftreasure-data%2Ftd-unity-sdk-package/lists"}