Getting Started with Unity SDK

Detailed technical documentation on the RudderStack Unity SDK, including setup, initialization and upgrading.

Setup Requirements

To properly configure the Unity SDK, you will need the following:

  • A RudderStack account. Your source writeKey should appear in the dashboard once you have signed up.

  • Your Data-plane URL. The following screenshot shows the data plane URL for the managed hosting mode:

Adding Unity SDK to your project

  • Download rudder-unity-plugin.unitypackage here

  • Import the downloaded package to your project. From the Assets menu, go to Import Package -> Custom Package... as shown:

  • Select rudder-unity-plugin.unitypackage from the location you have downloaded and click on Open.

  • Click on Import in the import popup as shown:

Initializing RudderStack Client

Add the following code in the Awake method of your main GameObject

If you are building an iOS project, RudderClient.SerializeSqlite() is important to handle races with SQLite.

// Critical for iOS Applications where multiple components are using SQLite
// This has no effect for Android, but can be added as a safety check
RudderClient.SerializeSqlite();
// Build your config
RudderConfigBuilder configBuilder = new RudderConfigBuilder()
.WithEndPointUrl(YOUR_DATA_PLANE_URL);
// get instance for RudderClient
RudderClient rudderClient = RudderClient.GetInstance(
YOUR_WRITE_KEY,
configBuilder.Build()
);

Sending Events

The following code demonstrates a track event:

// create event properties
Dictionary<string, object> eventProperties = new Dictionary<string, object>();
eventProperties.Add("test_key_1", "test_value_1");
eventProperties.Add("test_key_2", "test_value_2");
// create user properties
Dictionary<string, object> userProperties = new Dictionary<string, object>();
userProperties.Add("test_u_key_1", "test_u_value_1");
userProperties.Add("test_u_key_2", "test_u_value_2");
// create message to track
RudderMessageBuilder builder = new RudderMessageBuilder();
builder.WithEventName("test_event_name");
builder.WithUserId("test_user_id");
builder.WithEventProperties(eventProperties);
builder.WithUserProperties(userProperties);
rudderClient.Track(builder.Build());
// create message to track
RudderMessageBuilder builder = new RudderMessageBuilder();
builder.WithEventName("test_event_name");
builder.WithUserId("test_user_id");
builder.WithEventProperty("foo", "bar");
builder.WithUserProperty("foo1", "bar1");
rudderClient.Track(builder.Build());

Upgrading the SDK

Remove all the files related to RudderStack SDK from the Plugins folder. Also remove RudderUnityPlugin folder completely before importing the newer version of the SDK.

The following is the list of files in Plugins folder for RudderStack SDK:

  • Plugins/Android/rudder-sdk-unity-plugin-android-release.aar

  • Plugins/iOS/RudderSDKUnity