CONTRIBUTING.md

Contributing

First of all, thanks for contributing!

This document provides some basic guidelines for contributing to this repository. To propose improvements, feel free to submit a PR or open an issue.

Found a bug?

For any urgent matters (such as outages) or issues concerning the Datadog service or UI, contact our support team through https://docs.datadoghq.com/help/ for direct assistance.

To submit a bug report concerning the Datadog Unity SDK, open a GitHub Issue. Use the appropriate template and provide all listed details to help us resolve the issue.

Prerequisites

To work on the Datadog Unity SDK, you'll need to:

• Install Unity CLI.
  • To verify: unity --version
• Install the .NET SDK.
• Ensure that you have Python 3.14 installed on your system.
  • To verify: python3 --version

Python tooling

Python dependencies and commands are defined in the root pyproject.toml. The development scripts and mock server share one environment.

Both setups use editable installation, so Python code changes take effect without reinstalling.

Using pip

Install the tooling from the repository root with pip:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --editable .
dd-unity-unit-test

After changing dependencies or command definitions in pyproject.toml, repeat the pip install command.

Run Python checks from the repository root:

ruff check
ty check
pytest

Using uv

Install the tooling from the repository root with uv:

uv sync
source .venv/bin/activate
dd-unity-unit-test
python -m dd_sdk_unity.mock_server

After changing dependencies or command definitions in pyproject.toml, run uv sync again. The dd-unity-* commands use the existing environment without syncing it.

Select .venv as your IDE's Python environment to make the development tools available there.

Run Python checks from the repository root:

uv run ruff check
uv run ty check
uv run pytest

The uv run commands update their environment automatically.

Android prerequisites

To build the SDK for Android:

• Ensure that all relevant Unity Editor installs include Android Build Support, OpenJDK, and Android SDK & NDK Tools. The install_unity script installs these modules.
• For Android emulator support in scripts, install the Android SDK and the cmdline-tools package.
  • To verify the SDK has successfully installed, check that $ANDROID_HOME is set, and $ANDROID_HOME/cmdline-tools/latest exists.

iOS prerequisites

To build the SDK for iOS:

• Ensure that all relevant Unity Editor installs include iOS Build Support. The install_unity script installs this module.
• Install Xcode.
  • To verify Xcode successfully installed, run: xcodebuild -version
• Ensure that you've configured Xcode for automatic signing by authenticating with your Apple ID.
• Install xcbeautify via brew install xcbeautify
  • To verify xcbeautify successfully installed, run: xcbeautify --version

Datadog's own iOS dependency (dd-sdk-ios) is a prebuilt XCFramework vendored directly into the Datadog.Unity package via Unity's native Plugin importer — neither CocoaPods nor SPM runs to resolve it. Ruby/CocoaPods are not required for Datadog's own dependency (this is independent of Android-side Gradle dependency resolution, which is unaffected).

Before your first iOS build in a fresh clone, stage the XCFramework once:

dd-unity-ios-xcframework stage

The staged bundles under packages/Datadog.Unity/Plugins/iOS/ are .gitignored in this dev repo (fetched on demand, not committed to dd-sdk-unity's own git history). To check the staged state offline without re-fetching:

dd-unity-ios-xcframework verify

The pinned dd-sdk-ios version, its expected SHA-256, and its expected module list are the single source of truth in packages/Datadog.Unity/Editor/iOS/IosDependencyVersion.json.

Troubleshooting iOS dependencies

If an iOS build fails with a message from IosXcframeworkPreprocessBuild naming missing XCFramework module(s) under packages/Datadog.Unity/Plugins/iOS/, stage the XCFramework and try again:

dd-unity-ios-xcframework stage

EDM4U (Google's External Dependency Manager for Unity) has been removed from the package entirely. Neither an iOS nor an Android build invokes EDM4U or CocoaPods for Datadog's own dependencies. If an EDM4U window appears during any build, that indicates a stale EDM4U install left over in the local Unity project — it is not something this package requires or installs.

Updating the pinned dd-sdk-ios version

Bumping the pinned dd-sdk-ios version is a deliberate, manual maintainer action:

dd-unity-update-ios-version <version>

This fetches the target version's XCFramework, re-verifies that all currently-vendored modules are still present in the bundle (failing loudly and leaving the pin untouched if any are missing), stages and structurally verifies the result, and only then rewrites IosDependencyVersion.json with the new version and its digest. Useful flags:

• --dry-run — perform the fetch/verify/stage steps and print the pin that would be written, without writing it.
• --force — re-run the bump even if the target version already matches the current pin.

NATIVE_SDK_VERSIONS.md and the changelog are updated by the release flow, not by this script.

Committing the vendored XCFramework into the unity-package release payload is release-automation work — no release step is documented here.

Android dependencies

The pinned dd-sdk-android version and its artifact IDs are the single source of truth in packages/Datadog.Unity/Editor/Android/AndroidDependencyVersion.json.

DatadogGradlePostProcessor (an IPostGenerateGradleAndroidProject hook) writes implementation 'com.datadoghq:dd-sdk-android-{rum,logs,ndk}:<version>' into the generated unityLibrary/build.gradle, bounded by // Datadog Dependencies Start / // Datadog Dependencies End markers. Gradle resolves the transitive dependency graph from mavenCentral(), which Unity's own settingsTemplate.gradle already declares — no repository configuration is needed.

Unlike iOS, nothing is vendored into the package: the AARs are referenced by Maven coordinate and fetched by Gradle at build time, so there is no fetch/stage step and no Plugins/Android payload.

Updating the pinned dd-sdk-android version

Bumping the pinned dd-sdk-android version is a deliberate, manual maintainer action:

dd-unity-update-android-version <version>

This verifies that the three AARs are reachable on Maven Central and re-checks the transitive kotlin-stdlib/okhttp versions for drift before rewriting the pin, leaving the pin untouched on any failure. Useful flags:

• --dry-run — verify and print the pin that would be written, without writing it.
• --force — re-run the bump even if the target version already matches the current pin.
• --allow-transitive-drift — proceed after a detected transitive version change has been reviewed.

NATIVE_SDK_VERSIONS.md and the changelog are updated by the release flow, not by this script.

Repository overview

The following instructions describe how to develop and test changes to the Datadog Unity SDK itself. For instructions on adding Datadog SDK functionality to your own Unity project, see the documentation in the DataDog/unity-package repository.

At a high level, the dd-sdk-unity repository is organized like so:

• samples/: Unity projects used for running tests and showcasing example usage.
• test_scaffolds/: Additional Unity projects used to test compatibility with a wider range of Unity versions.
• tools/dd_sdk_unity/mock_server/: Flask app used by integration tests to record HTTP requests sent by the SDK and validate expected usage.
• tools/dd_sdk_unity/scripts/: Scripts used to automate common development tasks.
• packages/Datadog.Unity/: The source of the Datadog Unity package, which is deployed to the root of the unity-package repo.

To get started, open samples/Datadog Sample in Unity 2022.3, then open the same project in your IDE of choice to begin editing the source of the Datadog.Unity package. Each project's ProjectSettings/ProjectVersion.txt records its exact Editor version.

Running tests locally

The Datadog SDK includes a suite of tests in packages/Datadog.Unity/Tests. All significant code changes to the SDK must have adequate test coverage.

When you open a pull request, your changes are validated exhaustively against our CI pipeline. As you work, though, it's helpful to run tests locally as well.

Unity versions

We currently run tests against these versions of Unity:

Test Suite	Unity Project	Unity Version
unit_test	test_scaffolds/2021 LTS	Unity 2021.3
unit_test	samples/Datadog Sample	Unity 2022.3
unit_test	test_scaffolds/6000 LTS	Unity 6000.2
integration_test	samples/Datadog Sample	Unity 2022.3

Our test scripts use the Unity CLI binary to locate and manage installed versions of the Unity Editor. If a test script is unable to locate the required version of the editor, it exits with an error.

To install the latest release of a specific editor version, along with all required components for testing the Datadog SDK, you can use the install_unity script:

# Install Unity 2022.3 and its required iOS/Android modules through Unity CLI
dd-unity-install-unity 2022.3

Unit tests

The unit_test script runs all tests except for those in the Integration namespace.

# Run Datadog SDK unit tests against the default 'Datadog Sample' project, with Unity 2022
dd-unity-unit-test

# Run the same tests in the '6000 LTS' project, with any version of Unity 6
dd-unity-unit-test --project 'test_scaffolds/6000 LTS' --unity-version 6000

# Run the same tests in the '2021 LTS' project, requiring an exact Unity 2021 build
dd-unity-unit-test --project 'test_scaffolds/2021 LTS' --unity-version 2021.3.44f1

When you run any of these commands from the root of this repository, the script locates the appropriate version of the Unity Editor, then boots a headless instance of that editor. That editor instance runs EditMode tests, then PlayMode tests, and then it exits.

Note: If you already have the target project open in Unity, test scripts will fail to run, as Unity does not permit the same project to be open in multiple editor instances. If you wish to run unit tests without closing the editor, you can run them directly through (Window → General → Test Runner).

Unit test results are written in JUnit format to unit-test-<mode>.xml. If all tests pass, the script will exit with a status code of 0.

Integration tests

Before running integration tests, close the target project in the Editor and make sure the test device can reach your computer's LAN address on port 5100. These commands use samples/Datadog Sample with Unity 2022.3:

# Run integration tests on Android, using an AVD
dd-unity-integration-test --platform android

# Run integration tests on an iOS Simulator
dd-unity-ios-xcframework stage
dd-unity-integration-test --platform ios --target simulator

# Run integration tests on iOS, using a physically-connected iPhone
dd-unity-integration-test --platform ios --target device

As with the unit test script, these commands launch the Unity Editor in headless mode to invoke the tests, but the integration test script also performs some additional setup:

• It launches a mock server that records incoming SDK requests so the tests can inspect and validate them.
• It configures the project's Datadog Settings to use that server and enable the features under test.
• It runs the tests on Android or iOS players, exercising the underlying native SDKs.

Use --project and --unity-version to select another project and Editor.

Results are written to integration-test-<platform>.xml in JUnit format, with logs alongside them. Mock-server logs are under the project's Library/DatadogIntegrationTests/ directory.

New integration tests should inherit IntegrationTestBase and use the integration category.

Debugging integration tests

To build an integration test player manually from Unity's Test Runner, start the mock server first:

dd-unity-integration-test-setup start --project 'samples/Datadog Sample'

Run the integration tests on an Android or iOS player. When finished, stop the server:

dd-unity-integration-test-setup stop --project 'samples/Datadog Sample'