LethalAnalytics

Allows mod creators to see how their mods are used, easily catch errors, and learn about their audience.

This is a mod library or dependency. If you're playing with this mod installed, check out its LethalConfig for more info.

Dependencies

Overview

• Supported Analytics Sites
• Usage
  • Setting up
  • Creating a GA session
  • Sending GA events
  • Creating a README note
  • Creating a GA4 property
• Telemetrics
• Issues and Contributions
• Licencing

Supported Analytics Sites:

• Google Analytics (GA4) [Free]

• • User & new user charts supported
  • Location (city) map & charts supported
  • Events (with dimensions and metrics) supported
  • Engagement time charts supported
  • Screen resolution chart supported

• More coming soon (upon request)

Usage

Setting up

First, reference the LethalAnalytics.dll file (downloaded from Thunderstore or Github) from your project.

In order to access the LethalAnalytics API, use the LethalAnalytics namespace:

using LethalAnalytics;

Also include LethalAnalytics as a BepInDependency of your mod so that BepInEx can work its dependency graphing magic (and properly load LethalAnalytics):

[BepInPlugin(modGUID, modName, modVersion)]
[BepInDependency("net.RB007.LethalAnalytics")]   <--- (right here)
public class YourHopefullyErrorFreeModOrSmth : BaseUnityPlugin { ... }

If uploading your mod to Thunderstore, make sure to include LethalAnalytics in your manifest.json file.

Creating a GA session

Reference the static AnalyticsManager class and call the registerGASession(...) method to connect your mod to Google Analytics (GA4):

GASession gaSession = AnalyticsManager.registerGASession("net.YourUsername.YourMod", "Your Mod Name", "1.0.0", "Your mod desc. that explains what data you will collect and WHY you're collecting it.", "G-YOURMEASUREMENTID");

See Creating a GA4 property if you need a MEASUREMENT ID.

If needed, you can register multiple GA sessions (and still send events to each, separately). Please be careful about changing your modId, modName, and modVersion. This can cause issues with session creation and user consent settings.

Here's some documentation about its parameters:

By default, every instance of GASession sends a few user events:

Sending GA events

In order to send GA events, you'll need an instance of a GASession. It's recommended that you store the previously shown GASession instance in an internal static variable. That way, you can safely access it throughout your mod assembly.

internal static GASession gaSession = AnalyticsManager.registerGASession(...);

Then, call the sendGAEvent(...) method, from your GASession instance, to send custom GA events to your property.

gaSession.sendGAEvent("category", "name", new Dictionary<string, string>() { ["event_param"] = "event_value" });

Please be careful about sending events too quickly and keep event params minimal. Your mod shouldn't dramatically affect a user's networking.

Here's some documentation about its parameters:

And here's an example of it in action (in the wild 😲):

[HarmonyPatch(typeof(GrabbableObject))]
public class ItemPatch
{
  [HarmonyPatch("OnBroughtToShip")]
  [HarmonyPostfix]
  public static void patchCollect(ref Item ___itemProperties, ref int ___scrapValue)
  {
    YourModClass.gaSession.sendGAEvent("event", "collect", new Dictionary<string, string>() { ["item_name"] = ___itemProperties.itemName, ["scrap_value"] = ___scrapValue.ToString(), ["elapsed"] = StartOfRound.Instance.timeSinceRoundStarted.ToString() });
  }
}

The event logs when a user brings a new scrap item to the ship and sends its name, value, and the time since the ship landed, to the GA property.

Creating a README note

[!IMPORTANT] When using LethalAnalytics, it's extremely recommended that you include some sort of README notice for your mod.

See Telemetrics for an example (below). It's always important to be transparent and respect user privacy. Users should know what events are being collected and why.

Creating a GA4 property

• Navigate to https://analytics.google.com/ --> Create --> Property.
• Enter your property name and time zone --> Next.

• Select an industry (ex. Games) and business size (ex. Small) --> Next.

• Select (at least) Examine user behavior --> Create.

• Choose the Web platform. --> Enter your modId (ex. net.YourUsername.YourMod) as the URL and type your mod name as the Stream name (verify that Enhanced measurement is on).

• Select your newly-created web stream --> Copy the MEASUREMENT ID.

• That's it. You're all set! Use your MEASUREMENT ID when registering a GA session above. Once your users run your mod, they'll show up in your Realtime (and normal) reports with any sent events.

[!TIP] Generally, it's best to keep your MEASUREMENT ID safe. Anyone with it can send data to your property (Google does a decent job at removing bots/spam, though). Feel free to hide/obfuscate it in your code.

Telemetrics

Unless turned off in the config, LethalAnalytics may upload small amounts of Lethal Company and LAs user data. This helps me understand what features are used the most and what I can improve.

What's collected?

• OS, LC, and LethalAnalytics version data
• Your CPU (type), GPU (type), and screen resolution
• The names of mods that use LAs, the amount of events sent (but not their contents), and a few game events
• Your language and region (ex. en-US, Chicago)

[!IMPORTANT] Your Steam username is NOT sent (to keep things anon.).

This section doesn't include analytics/telemetrics data collected by other mods. Consult each mod README and their config description for more info.

Issues and Contributions

Please follow the available issue templates when submitting requests. Use the discussions tab when wanting to chat. Pull requests (to the dev branch) and other user contributions are encouraged and always welcome.

Licencing

Read the LICENSE file for more information. The Contributor Agreement can be found there too. By downloading or contributing to this repo, you agree to the terms stated in the LICENSE file.

Copyright (C) 2024 RoosterBooster007

[!IMPORTANT] Please include the above copyright notice when distributing or modifying any code.