Bugsee Unity SDK

UPM package for the Bugsee crash and session-replay SDK on Unity (2021.3+).

This repository replaces the legacy .unitypackage / Assets/Plugins distribution. The previous repo remains available as a reference foundation.

Install

In Unity Package Manager → Add package from git URL:

https://github.com/bugsee/bugsee-unity.git

Pin a version/tag when available:

https://github.com/bugsee/bugsee-unity.git#0.1.0

That is the whole install: no scoped registry, no EDM4U, no dependency-resolve step and no custom Gradle templates to enable. On Android the package declares the Bugsee SDK in the Gradle project Unity generates for each build (see below); on iOS it adds the Bugsee Swift package to the Xcode project.

Projects that use EDM4U for other SDKs keep working. If the project already declares com.bugsee:bugsee-android itself (through EDM4U, a custom mainTemplate.gradle or a local AAR), that declaration is kept, nothing is added next to it, and the build log warns when its version differs from the one this package pins.

Native SDKs

Platform	Integration	Current pin
Android	Maven Central, declared in the generated Gradle project by BugseeAndroidMavenDependencies	bugsee-android:7.4.2 + bugsee-android-ndk:7.4.2
iOS	Swift Package Manager + Plugins/iOS/BugseeUnityBridge.mm	bugsee/spm 7.0.0

Android stack

Piece	Status
bugsee-android	7.4.2, added to unityLibrary/build.gradle at build time (no Maven transitives)
bugsee-android-ndk	Same version, declared alongside (native fatal capture for IL2CPP primary LNM)
mavenCentral()	Added to the generated project repositories only if Unity's layout lacks it
Gradle plugin 4.0.8	Patched into the generated Gradle project by BugseeAndroidGradleSetup when it pins AGP 8.6+ (Unity 6; ndk { enabled = true }; for an Export Project the block also reads BUGSEE_APP_TOKEN from the environment of the later Gradle build, see Export Project), in Groovy or Kotlin DSL files, see Gradle file layouts. On Unity 2021.3 / 2022.3 (AGP 7.4.2) and Unity 6000.0.1-44 (AGP 8.3.0) it cannot run; the build-id asset is added instead and symbols are uploaded by the Editor with bugsee-cli found or downloaded automatically, see Documentation~/index.md

Refreshing native artifacts

./Tools~/scripts/update-native-sdks.sh

See Tools~/versions.env for pinned versions and paths.

The script also vendors the option manifests the native SDKs publish for the pinned versions (Tools~/scripts/update-options-manifest.sh, into Tests~/WrapperPolicy/Fixtures/options-manifest/). After a bump, run the WrapperPolicy tests: OptionsManifestTests fails for a new, removed or changed native option until the wrapper exposes it or lists it as not exposed (with the issue that tracks it). If a pin has no published manifest yet, the script warns and the test stays red until update-options-manifest.sh succeeds (ANDROID_MANIFEST_FILE / IOS_MANIFEST_FILE take a manifest from a local SDK build). Two branches that bump different pins, or one that bumps a pin while another adds the manifests, conflict only through Tools~/versions.env and the vendored files: whichever merges second runs update-native-sdks.sh again (the CHANGELOG line that names the manifest versions is a pin in native-pins.txt and is rewritten with the rest), otherwise Vendored_manifests_are_verbatim_copies_of_the_pinned_versions is red on main.

Crashes & symbols

See Documentation~/index.md for:

• ExceptionPipeline vs DetectAndReportCrash
• Hang / ANR / OOM launch options
• BUGSEE_APP_TOKEN Editor uploads (il2cpp-linemap, elf, proguard); the IL2CPP mapping files are written without it, for a later CI upload
• iOS archive-time dSYM + linemap Run Script
• Create symbols.zip / FULL native debug symbols vs SYMBOL_TABLE

Layout

Runtime/           # C# runtime API + asmdef
Editor/            # Android Gradle injection, iOS SPM, linemap + symbol upload
Plugins/           # iOS ObjC++ bridge, Android UnityManagedException.java
Native~/ios/Bugsee # Local SPM package, used only when UseRemoteSpm is off (default: github.com/bugsee/spm); no xcframework is committed
Tools~/            # Version pins + maintenance scripts
Documentation~/    # Package docs shown in Package Manager
Samples~/
  BugseeMiniGame/  # Standalone QA minigame (excluded from UPM via ~)

Sample project

Open Samples~/BugseeMiniGame in Unity Hub (2021.3+) to try a small arena with HUD buttons and in-world Bugsee stations. See that folder’s README.

Status

• Android + iOS bridges (Launch, exceptions, filters, report handler, lifecycle, native crash options)
• ExceptionPipeline (managed auto-capture) + UnityManagedException JSON contract
• Editor symbol orchestrator (linemap / ELF / ProGuard / iOS archive dSYM)
• Contracts (Options, Lifecycle, Reporting, Exchange, Appearance, Feedback)

See DESIGN.md for the full plan.

License

MIT — see LICENSE.