The RudderStack Unity SDK is a wrapper for the RudderStack Android SDK and iOS SDK and is used for tracking game event data. After integrating this SDK with your game, you will be able to track your game event data and send it to your specified destinations via RudderStack.
Check the GitHub codebase to get a more hands-on understanding of the SDK.
To set up the RudderStack Unity SDK, the following prerequisites must be met:
- You need to set up a RudderStack account.
- Once signed up, set up a Unity source in the dashboard. You should be able to see a Write Key for this source, as shown below:
- You will also need a data plane URL. Refer to the Glossary for more information on the data plane URL and where to find it.
- Finally, download and install the Unity development kit.
Follow these steps to integrate the RudderStack Unity SDK with your project:
rudder-sdk-unity.unitypackagefrom our GitHub repository.
- Import the downloaded package to your project. From the Assets menu, go to Import Package - Custom Package... as shown:
rudder-sdk-unity.unitypackagefrom the downloaded location and click on Open, as shown:
- Click on
Importin the import popup as shown:
To initialize the RudderStack client, follow these steps:
- Add the
importto all the files where you wish to use
- Then, add the following code in the
Awakemethod of your main
// Critical for iOS Applications where multiple components are using SQLite// This has no effect for Android, but can be added as a safety checkRudderClient.SerializeSqlite();// Build your configRudderConfigBuilder configBuilder = new RudderConfigBuilder().WithDataPlaneUrl(DATA_PLANE_URL);.WithLogLevel(RudderLogLevel.VERBOSE)// get instance for RudderClientRudderClient rudderClient = RudderClient.GetInstance(WRITE_KEY,configBuilder.Build());
If you are building an iOS project,
RudderClient.SerializeSqlite() is important to handle races with SQLite.
You can configure your client based on the following parameters using
|Integer||Controls how much of the log you want to see from the SDK.|
|String||Your data plane URL.|
|Integer||Number of events in a batch request to the RudderStack server.|
|Integer||Number of events to be saved in the |
|Integer||Minimum waiting time to flush the events to the RudderStack server. The minimum value can be set to |
|Integer||The SDK will fetch the config from |
|Boolean||Determines if the SDK will automatically capture the application lifecycle events.|
|Boolean||Determines if the SDK will automatically capture the screen view events.|
|Boolean||Determines if the SDK will collect the advertisement ID.|
|String||Change this parameter only if you are self-hosting the control plane. Check the Self-hosted control plane section below for more information. The SDK will add ||https://api.rudderlabs.com|
If you are using a device mode destination like Adjust, Firebase, etc., the Unity SDK needs to fetch the required configuration from the control plane. If you are using the Control Plane Lite utility to host your own Control Plane, then specify
controlPlaneUrl in your
RudderConfigBuilder that points to your hosted source configuration file.
controlPlaneUrlparameter during the SDK initialization if you are using the RudderStack Cloud dashboard. This parameter is supported only if you are using the open source Control Plane Lite utility to self-host your control plane.
The Unity SDK captures the
deviceId and uses that as the
anonymousId for identifying the user. This helps in tracking the users across the application installation. To attach more information to the user, you can use the
identify method. Once the SDK identifies the user, it persists and passes the user information to the subsequent calls.
To reset the user identification, you can use the
RudderStack provides some pre-defined APIs for building the
RudderTraits object like
PutAge(), etc. These APIs can be used to set the values of the standard traits by directly passing them as parameters.
For the custom traits which do not have any pre-defined API, you can use the
Put() method and pass a key-value pair of the trait, as shown in the sample
identify event below:
RudderMessage identifyMessage = new RudderMessageBuilder().Build();RudderTraits traits = new RudderTraits();//pre-defined API's for inserting standard traitstraits.PutEmail("firstname.lastname@example.org");traits.PutAge("40");//Put API to insert custom traitstraits.Put("location", "New Orleans");traits.Put("gender", "Male");traits.Put("consent", "Granted");rudderClient.Identify("some_user_id", traits, identifyMessage);
You can explicitly set the
anonymousId for all the future events using the
setAnonymousId() method, as shown:
You can record the users' in-game activity through the
track method. Every user action is called an event.
track event is as shown:
// create event propertiesDictionary<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 propertiesDictionary<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 trackRudderMessageBuilder 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 trackRudderMessageBuilder 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());
screen call lets you record the user activities on their mobile screen with any additional relevant information about the viewed screen.
screen event is as shown:
// create screen propertiesDictionary < string, object > screenProperties = new Dictionary < string, object > ();screenProperties.Add("key_1", "value_1");screenProperties.Add("key_2", "value_2");RudderMessageBuilder screenBuilder = new RudderMessageBuilder();screenBuilder.WithEventName("Home Screen");screenBuilder.WithEventProperties(screenProperties);rudderClient.Screen(screenBuilder.Build());
reset method clears all the persisted traits of the previously identified user.
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:
RudderStack collects the advertisement ID only if
withAutoCollectAdvertId is explicitly set to
true during the SDK initialization, as shown:
RudderConfigBuilder configBuilder = new RudderConfigBuilder().WithDataPlaneUrl(DATA_PLANE_URL);.WithLogLevel(RudderLogLevel.VERBOSE).withAutoCollectAdvertId(true);
The Unity SDK automatically tracks the Application Lifecycle Events to get insights into the app metrics like installs, opens, updates, etc. However, you can disable the automatic tracking by setting the
withTrackLifecycleEvents parameter to
false, as shown:
RudderConfig config = new RudderConfigBuilder().WithTrackLifecycleEvents(false)
To track the application life cycle events on the Android platform, you need to add the
RudderPreferbs.prefab file from the path
Assets/Rudder/RudderPreferbs.prefab to every scene in your Unity app. Also, ensure that the
RudderPreferbs.prefab is linked to the
The Unity SDK depends on the lifecycle method
onApplicationFocus of the
MonoBehaviour class to determine the Application Opened and Application Backgrounded events on the Android platform.
Hence, when an application is brought to focus, an
Application Opened event is sent, and when the application is moved out of focus, an
Application Backgrounded event is sent. So, these events might be triggered even before the RudderStack SDK gets initialized to create the actions and execute them once the SDK is initialized.
The following requirements must be met to ensure that the Application Updated lifecycle event is triggered:
- For iOS: Make sure the
Bundle versionin the
Info.plistfile of your application is incremented. If the
Bundle versionof your
targetpoints to the
Bundle versionof your
project, then increment it.
- For Android: Make sure the
defaultConfigobject nested in the
androidobject of your app's