Unity SDK v2 Beta

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

SDK setup requirements

• Download and install the Unity development kit.
• Sign up for RudderStack.
• Set up a Unity source in your RudderStack Cloud dashboard. Note the write keyThe write key (or source write key) is a unique identifier for your source. RudderStack uses this key to send events from a source to the specified destination. for this source.
• You will also need the data plane URL associated with your RudderStack workspace.

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… :

3. Select rudder-sdk-unity.unitypackage from the downloaded location and click Open:

4. Click Import in the import popup:

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

Initializing the RudderStack client

1. Import the SDK:

using RudderStack.Unity;

2. 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:

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

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.

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

Gzip requires rudder-server v1.4 or higher. Otherwise, your events might fail.

Questions? Contact us by email or on Slack