Unity

Detailed technical documentation on the RudderStack Unity SDK to send event data from your game to various destinations.

What is the RudderStack Unity SDK?

The RudderStack Unity SDK is a wrapper for the RudderStack Android SDK and iOS SDK used for tracking game event data.

After integrating this SDK with your game, you will be able to track and send the game event data to any analytics destination of your choice.

Check the Unity SDK codebase on GitHub to get a more hands-on understanding of how it works.

Prerequisites

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

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

  • Your data plane URL to connect to the RudderStack backend for processing and routing your events.

To get the Data Plane URL:

  • If you're using the open-source version of RudderStack, you are required to set up your own data plane by installing and setting up RudderStack in your preferred dev environment.

  • If you're using the enterprise version of RudderStack, contact us for the data plane URL with the email ID used to sign up for RudderStack.

Adding Unity SDK to Your Project

  • Download rudder-sdk-unity.unitypackage from our GitHub repository.

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

Importing the downloaded package
  • Select rudder-sdk-unity.unitypackage from the location where you have downloaded it and click on Open:

  • Click on Import in the import popup as shown:

Initializing RudderStack Client

To initialize the RudderStack client, follow these steps:

  • Add the import to all the files where you wish to use RudderClient .

using RudderStack;
  • Then, add the following code in the Awake method of your main GameObject Script:

// 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()
.WithDataPlaneUrl(DATA_PLANE_URL);
// get instance for RudderClient
RudderClient rudderClient = RudderClient.GetInstance(
WRITE_KEY,
configBuilder.Build()
);

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

Track

You can record the users' in-game activity through the track method. Every action performed by the user is called an event.

An example of a track event is as shown:

// 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());

Identify

The Unity SDK captures the deviceId and uses that as the anonymousId for identifying the user. It lets you track the users across the application installation.

To attach more information to the user, you can use the identify method. Once you set the identify information to the user, it will be passed to the successive track calls. To reset the user identification, use the reset method.

An example identify event is as shown:

RudderMessage identifyMessage = new RudderMessageBuilder().Build();
RudderTraits traits = new RudderTraits().PutEmail("[email protected]");
rudderClient.Identify("some_user_id", traits, identifyMessage);

Reset

The reset method clears all the persisted traits of the previously identified user.

rudderClient.Reset();

Upgrading the SDK

To upgrade the SDK, remove all the files related to the SDK from the Plugins folder. Also, remove the Rudder folder completely before importing a newer version of the SDK.

You can find the following files in the Plugins folder for the SDK:

  • Plugins/Android/unity-plugin-release.aar

  • Plugins/iOS/RudderSDKUnity

Contact us

If you come across any issues while using the Unity SDK, you can contact us or start a conversation on our Slack channel. You can also open an issue on our GitHub.