# Unreal Engine SDK

This plugin behaves as an Analytics Provider for Unreal Engine. It enables you to track in-game events using Treasure Data. Common use cases for this plugin are to track things like currency buys, item trades, and game progression.

You can start sending data from your [Unreal Engine](https://www.unrealengine.com/) app to Treasure Data using our Unreal Engine SDK.

![](/assets/image-20191022-132426.f322f86a09d78e50b2c307af1257421ea14e3b6fc60f4ed28604bd3eedc1d4b1.3fd85dbb.png)

- [Unreal Engine SDK Repository](https://github.com/treasure-data/td-ue4-sdk)


## Prerequisites

- The Unreal Engine has been compiled from source with all dependencies so third party plugins can build
- The Unreal Engine has been installed on your machine
- Blueprints plugin is in place and enabled
- Treasure Data plugin is in place and enabled
- You have a [Treasure Data Write-Only API Key](https://console.treasuredata.com/app/users)


Treasure Data strongly recommends that you use a write-only API key for ingest and import operations and whenever using Treasure Data SDKs.

How to get a Write-Only API Key
1. Login to the Treasure Data Console and go to the [API Key page](https://console.treasuredata.com/app/mp/ak).
2. If you don't already have a write-only API key, then create one. From the top right, select **Actions > Create API Key**.
3. Name the new API Key.
4. From the Type drop-down menu, select **Write-only**.
5. Select **Save**.
6. Copy your new Write-Only API Key and use it to authenticate the APIs in your project.


## Setup

### Setting Up Unreal Engine 5

1. Sign up for an [Unreal Engine account](https://github.com/EpicGames) in order to access the GitHub repository for Unreal Engine 5.
2. On the Unreal Engine website, use the **Personal > Apps and Accounts** page to connect your Unreal Account to GitHub.
3. Clone the Unreal repository from GitHub to your local machine.
4. Compile the Unreal Engine with all dependencies.


### Download and Place the Plugin

Get a copy of the plugin from the main GIT repository:


```bash
git clone https://github.com/treasure-data/td-ue4-sdk
```

Checkout the branch that matches your Unreal Engine version:


```bash Unreal Engine 5.3
git checkout UE-5.3
```


```bash Unreal Engine 4.x
git checkout master
```

Copy the new `td-ue4-sdk` to your Unreal Engine plugins folder. The target path looks something like this:


```bash
UnrealEngine/Engine/Plugins/td-ue4-sdk
```

Alternatively, you can copy the plugin content inside your Project Plugin directory. However, this approach does not work in a Linux Development environment.

### Build the Plugin

To build the plugin, you need to generate the build-rules. The UE Engine provides a script called **GenerateProjectFiles**:

- `GenerateProjectFiles.bat` (Windows)
- `GenerateProjectFiles.sh` (Unix/Linux/Mac)


Depending on your system (Unix-based or Windows), run the proper script from the command line:

- If the plugin is inside the Project directory (Project/Plugins), go to the Project root directory and run the script.
- If the plugin is inside the Engine, run the command from the Unreal Engine source root directory.


When the command finishes, type the `make` command:


```bash
make
```

After a few seconds, the plugin binary is available.

#### Speed Up Plugin Build Phase

In some cases you may need to re-build only the plugin. Using a normal `make` command can take some minutes as it parses and runs scripts to fix dependencies. To speed up the process, add the following options:


```bash
make UE4Editor ARGS=-canskiplink
```

### Enable the Analytics Plugins for Your Project

1. In the Unreal Engine Editor, select **Edit > Plugins**.
2. Open your project and the plugins window.
3. Enable the two required plugins:
  - **Blueprints**: located at Built-in > Analytics
  - **Treasure Data**: located at Installed > Analytics


![](/assets/image-20191022-132504.d8ef25004a8914d9aeb816f1eb52423fec61361b2651eb26a106463e80f05c0e.3fd85dbb.png)
![](/assets/image-20191022-132513.795ddcb8d26225801bc0bb865cdde797762f202f6828b83cca73769d289dd941.3fd85dbb.png)

### Configure Project Settings

From your project directory, open and edit the `Config/DefaultEngine.ini` file and append the following content at the bottom:


```ini
[Analytics]
ProviderModuleName=TreasureData
TDApiKey=TD-WRITE-ONLY-KEY
TDDatabase=DATABASE_NAME
TDRegion=[US01,AP01,AP02,AP03,EU01]
SendInterval=10

[AnalyticsDevelopment]
ProviderModuleName=TreasureData
TDApiKey=TD-WRITE-ONLY-KEY
TDDatabase=DATABASE_NAME
TDRegion=[US01,AP01,AP02,AP03,EU01]
SendInterval=10

[AnalyticsTest]
ProviderModuleName=TreasureData
TDApiKey=TD-WRITE-ONLY-KEY
TDDatabase=DATABASE_NAME
TDRegion=[US01,AP01,AP02,AP03,EU01]
SendInterval=10
```

The combined length of database name and table name must be shorter than 129 characters.

After making your changes, save the file and restart the Unreal Engine Editor.

## Gathering Metrics with Blueprints

In the Editor, select **Blueprints > Open Level Blueprint**.

![](/assets/image-20191022-132603.0ebbdf6e5796a5cd6d2ad8fb6e0450ebc3a4dcd3b66aebc89b8ce7d24ff9a8b6.3fd85dbb.png)

In the Event graphs window, different events can now be connected to Analytics functions. The following image demonstrates how to track the `Session Start`, `Session End`, and `Record Event w/Attributes` events:

After a Game starts, the plugin will send the events to Treasure Data.

## Viewing Data on Treasure Data

To query game events:

1. From the [Treasure Data Console](https://console.treasuredata.com), select **Databases** from the workbench.
2. Open the database used in the game (specified in `Config/DefaultEngine.ini > TDDatabase`).


![](/assets/image-20191022-132637.e2074fcadb175961c18432787b104e2c10deac7024895099460750092f25a6a8.3fd85dbb.png)

By default two tables are created:

- **Sessions**: start and stop sessions
- **Events**: All events with or without attributes


To query records, select a table name and then select the **Query** button at the top of the screen. By default you can issue SQL queries similar to this:


```sql
SELECT * FROM events;
```

![](/assets/image-20191022-132726.316a30dce56d38fcfeaf69fc5934c01f73f7b3bf0802ed8f0a9a6c1b8c16e3d0.3fd85dbb.png)