Unity
Detailed technical documentation on the RudderStack Unity SDK to send event data from your games to various destinations.
Last updated
Was this helpful?
Detailed technical documentation on the RudderStack Unity SDK to send event data from your games to various destinations.
Last updated
Was this helpful?
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 configure the Unity SDK, you will need the following:
You will need to set up a RudderStack account.
Once signed up, set up a Unity source in the dashboard. For more information, follow this guide. You should then see a Write Key for this source, as shown below:
You will also need a data plane URL. Follow this section for more information on the data plane URL and where to get it.
Finally, you will need the Unity development kit.
Follow these steps to integrate the RudderStack Unity SDK with 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:
Select rudder-sdk-unity.unitypackage
from the downloaded location and click on Open, as shown:
Click on Import
in the import popup as shown:
To initialize the RudderStack client, follow these steps:
Add the import
to all the files where you wish to use RudderClient
.
Then, add the following code in the Awake
method of your main GameObject
Script:
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 RudderConfigBuilder
:
logLevel
Integer
Controls how much of the log you want to see from the SDK.
RudderLogLevel.INFO
dataPlaneUrl
String
Your data plane URL.
https://hosted.rudderlabs.com
flushQueueSize
Integer
Number of events in a batch request to the RudderStack server.
30
dbThresholdCount
Integer
Number of events to be saved in the SQLite
database. Once the limit is reached, older events are deleted from the database.
10000
sleepcount
Integer
Minimum waiting time to flush the events to the RudderStack server. The minimum value can be set to 1 second
.
10 seconds
configRefreshInterval
Integer
The SDK will fetch the config from dashboard
after the specified time.
2 hours
trackLifecycleEvents
Boolean
Determines if the SDK will automatically capture the application lifecycle events.
true
recordScreenViews
Boolean
Determines if the SDK will automatically capture the screen view events.
false
autoCollectAdvertId
Boolean
Determines if the SDK will collect the advertisement ID.
false
controlPlaneUrl
String
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.
You should not pass the controlPlaneUrl
parameter 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 reset
method.
RudderStack provides some pre-defined APIs for building the RudderTraits
object like PutEmail()
, 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:
anonymousId
using setAnonymousId
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.
A sample track
event is as shown:
The screen
call lets you record the user activities on their mobile screen with any additional relevant information about the viewed screen.
A sample screen
event is as shown:
The 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:
Plugins/Android/unity-plugin-release.aar
Plugins/iOS/RudderSDKUnity
RudderStack collects the advertisement ID only if withAutoCollectAdvertId
is explicitly set to true
during the SDK initialization, as shown:
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:
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 RudderClient.cs
script.
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 version
in the Info.plist
file of your application is incremented. If the Bundle version
of your target
points to the Bundle version
of your project
, then increment it.
For Android: Make sure the versionCode
in the defaultConfig
object nested in the android
object of your app's build.gradle
is incremented.
Refer to the Application Lifecycle Events Specification guide for more information.
For queries on any of the sections covered in this guide, you can contact us or start a conversation in our Slack community.
If you come across any issues while using the Unity SDK, you can also open a new issue on our GitHub Issues page.
Change this parameter only if you are self-hosting the control plane. Check the section below for more information. The SDK will add /sourceConfig
along with this URL to fetch the source configuration.