Unity SDK v2 Beta

Use the RudderStack Unity SDK to send event data from your games to various destinations.

See the GitHub codebase to get a more hands-on understanding of the SDK.

SDK setup requirements

Unity source write key

Installing the Unity SDK

  1. Download rudder-sdk-unity.unitypackage.
  2. Import the downloaded package to your project. From the Assets menu, go to Import Package > Custom Package… :
Import custom package
  1. Select rudder-sdk-unity.unitypackage from the downloaded location and click Open:
Select RudderStack Unity package
  1. Click Import in the import popup:
Import popup
  1. Add the RudderStack.prefab file from the path Assets/RudderStack/Unity/Prefabs/RudderStack.prefab to every scene in your Unity app. Also, make sure that RudderStack.prefab is linked to the RSMaster, RSScreenView, and RSLogger scripts.
Add prefab file

Initializing the RudderStack client

  1. Import the SDK:
using RudderStack.Unity;
  1. Initialize the SDK as shown. Replace WRITE_KEY and DATA_PLANE_URL with the actual values obtained in the SDK setup requirements section.
RSAnalytics.Initialize("WRITE_KEY",
		new RSConfig(dataPlaneUrl: "DATA_PLANE_URL"));

// for coroutine
StartCoroutine(RSAnalytics.InitializeRoutine("WRITE_KEY",
		new RSConfig(dataPlaneUrl: "DATA_PLANE_URL")));

SDK initialization options

You can configure your client based on the following parameters using RudderConfigBuilder:

ParameterTypeDescription
logLevelEnumControls how much of the log you want to see from the SDK.

Default value: Logger.Level.INFO
dataPlaneUrlStringYour data plane URL.
dbThresholdCountIntegerNumber of events to be saved in the SQLite database. Once the limit is reached, older events are deleted from the database.

Default value: 10000
sleepcountIntegerMinimum waiting time to flush the events to the RudderStack server. The minimum value can be set to 1 second.

Default value:10 seconds
trackLifecycleEventsBooleanDetermines if the SDK will automatically capture the application lifecycle events.

Default value: true
recordScreenViewsBooleanDetermines if the SDK will automatically capture the screen view events.

Default value: false
controlPlaneUrlStringChange 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 /sourceConfig along with this URL to fetch the source configuration.

Default value: https://api.rudderlabs.com
gzipBooleanGzips the event requests.

Default value: true

Self-hosted control plane

Do not pass the controlPlaneUrl parameter during the SDK initialization if you are using the RudderStack Cloud dashboard to set up your connections. The SDK supports this parameter only if you are using the open source Control Plane Lite utility to self-host your control plane.

Identify

The identify call lets you identify a visiting user and associate them to their actions. It also lets you record the traits about them like their name, email address, etc.

The Unity SDK captures deviceId and uses that as anonymousId for identifying the user. This helps in tracking the users across the application installation. To attach more information to the user, use the identify method.

Once the SDK identifies the user, the SDK persists and passes the user information to the subsequent calls. To reset the user identification, use the reset method.

The following snippet highlights a sample identify call:

RSAnalytics.Client.Identify("unity_user_id",
                new Dictionary<string, object> { { "email", "abc@example.com" }, { "age", 24 }, { "name", "First Last" }, { "gender", "Male" } });

Override anonymousId using setAnonymousId

You can explicitly set the anonymousId for all future events using the PutAnonymousId() method.

RSClient.PutAnonymousId("anonymous_id");

Track

The track call lets you record the users’ in-game activity. Each user action is called an event.

The following snippet highlights a sample track call:

RSAnalytics.Client.Track("sample_track",
                new Dictionary<string, object> { { "key_1", "value_1" }, { "key_2", 4 }, { "key_3", 4.2 }, { "key_4", true } });

Track application lifecycle events

The Unity SDK lets you track the Application Lifecycle Events to get insights into the app metrics like installs, opens, updates, etc.

To enable automatic tracking, set trackLifeCycleEvents method to true while initializing the SDK:

RSAnalytics.Initialize("WRITE_KEY",
                new RSConfig(dataPlaneUrl: "DATA_PLANE_URL")
                    .SetTrackLifeCycleEvents(true));

Trigger Application Updated lifecycle event

To ensure that the Application Updated lifecycle event is triggered successfully:

  • 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.

Screen

The screen call is the mobile equivalent of the page call. It lets you record the screen views on your mobile app along with other relevant information about the screen.

The following snippet highlights a sample screen call:

RSAnalytics.Client.Screen("sample_screen",
                new Dictionary<string, object> { { "key_1", "value_1" }, { "key_2", 4 }, { "key_3", 4.2 }, { "key_4", true } });

Automatic screen recording

You can enable the automatic recording of screen views by setting recordScreenViews to true while initializing the SDK. This automatically sends a screen call for every screen that a user views. By default, recordScreenViews is set to false.

RSAnalytics.Initialize("WRITE_KEY",
                new RSConfig(dataPlaneUrl: "DATA_PLANE_URL")
                    .SetRecordScreenViews(true));
info
The recordScreenViews parameter records the screen views of the native Android Activities or the iOS Views only and not by the React Native Views.

Page

The page call lets you record the page views on your application along with the other relevant information about the page.

A sample page call is shown below:

RSAnalytics.Client.Page("sample_page",
                new Dictionary<string, object> { { "key_1", "value_1" }, { "key_2", 4 }, { "key_3", 4.2 }, { "key_4", true } });

Group

The group call lets you link an identified user with a group, such as a company, organization, or an account. It also lets you record any custom traits or properties associated with that group.

The following snippet highlights a sample group call made using the Unity SDK:

RSAnalytics.Client.Group("group_id",
                new Dictionary<string, object> { { "key_1", "value_1" }, { "key_2", 4 }, { "key_3", 4.2 }, { "key_4", true } });

Alias

The alias call lets you merge different identities of a known user. It is an advanced method that lets you change the tracked user’s ID explicitly. You can use alias for managing the user’s identity in some of the downstream destinations.

warning
RudderStack supports sending alias events only to select downstream destinations. Refer to the destination-specific documentation for more details.

A sample alias call is shown below:

RSAnalytics.Client.Alias("new_unity_user_id");

Reset

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

RSAnalytics.Client.Reset();

Set the advertisement ID

Use the PutAdvertisingId() method to explicitly set an advertising ID.

RSClient.PutAdvertisingId("advertisement_id");

Set the device token

You can pass your device token for push notifications for the destinations which support the feature using the PutDeviceToken() method. RudderStack sets the token under context.device.token.

RSClient.PutDeviceToken("device_token");

FAQ

Which platforms are does Unity SDK support?

The Unity SDK v2 supports the following platforms:

  • Android
  • iOS
  • Windows
  • macOS
  • Xbox
  • PlayStation

Do I need to add anything to my Android ProGuard rules?

If you are facing any event delivery issues in your production environment, verify if you have added the following line in your ProGuard rules:

-keep class com.rudderstack.android.** { *; }

How do I gzip event requests in Unity SDK?

The Unity SDK automatically gzips requests. To disable this feature, set the Gzip parameter to false while initializing the SDK:

RSAnalytics.Initialize("WRITE_KEY",
                new RSConfig(dataPlaneUrl: "DATA_PLANE_URL")
                    .SetGzip(false));
warning
Gzip requires rudder-server v1.4 or higher. Otherwise, your events might fail.

Questions? Contact us by email or on Slack