From 81d9a5c9a482307b67ad2d88b6ffa600d38ecd64 Mon Sep 17 00:00:00 2001 From: Oliver Date: Fri, 18 Apr 2025 13:06:42 +0200 Subject: [PATCH] docs: Add getting started guides for FancyAnalytics --- .../getting-started/getting-started.md | 33 ++++++ .../getting-started/java-sdk.md | 78 ++++++++++++ .../getting-started/minecraft-plugins.md | 112 ++++++++++++++++++ .../getting-started/minecraft-servers.md | 32 +++++ .../getting-started/rest-api.md | 8 ++ 5 files changed, 263 insertions(+) create mode 100644 docs/src/fancyanalytics/getting-started/getting-started.md create mode 100644 docs/src/fancyanalytics/getting-started/java-sdk.md create mode 100644 docs/src/fancyanalytics/getting-started/minecraft-plugins.md create mode 100644 docs/src/fancyanalytics/getting-started/minecraft-servers.md create mode 100644 docs/src/fancyanalytics/getting-started/rest-api.md diff --git a/docs/src/fancyanalytics/getting-started/getting-started.md b/docs/src/fancyanalytics/getting-started/getting-started.md new file mode 100644 index 00000000..091da064 --- /dev/null +++ b/docs/src/fancyanalytics/getting-started/getting-started.md @@ -0,0 +1,33 @@ +--- +icon: info +--- + +There are multiple ways to send data to FancyAnalytics. + +!!! danger +The FancyAnalytics platform is still in development. Expect breaking changes in the future. +!!! + +### For Minecraft servers + +If you run a Minecraft server, you might want to track metrics about your players and server performance. +We provide a Minecraft plugin which can be installed on your server to send data to FancyAnalytics. +See the [Minecraft Servers](minecraft-servers.md) page for more information. + +### For Minecraft plugins + +If you are a Minecraft plugin developer, you might want to track metrics about your plugin usage. +So you know how many people are using your plugin and how they are using it. +We provide a Java SDK which is specifically designed for Minecraft plugins. +See the [Minecraft Plugins](minecraft-plugins.md) page for more information. + +### For Java developers + +If you are a Java developer, who wants to track metrics about your Java application, without being in the Minecraft ecosystem, you can use our Java SDK. +The Java SDK is a general purpose SDK which can be used to track metrics about any Java application. +See the [Java SDK](java-sdk.md) page for more information. + +### For everyone else + +If you are not a Java developer, or you are using a different programming language, you can use our REST API to send data to FancyAnalytics. +See the [REST API](rest-api.md) page for more information. \ No newline at end of file diff --git a/docs/src/fancyanalytics/getting-started/java-sdk.md b/docs/src/fancyanalytics/getting-started/java-sdk.md new file mode 100644 index 00000000..245c1711 --- /dev/null +++ b/docs/src/fancyanalytics/getting-started/java-sdk.md @@ -0,0 +1,78 @@ +--- +icon: dot +order: 300 +--- + +# Java SDK + +This guide will help you set up FancyAnalytics in your general Java application. + +## Include the Java SDK + +### Gradle + +```kotlin +repositories { + maven("https://repo.fancyinnovations.com/releases") +} +``` + +```kotlin +dependencies { + implementation("de.oliver.fancyanalytics:java-sdk:VERSION") +} +``` + +### Maven + +```xml + + fancyplugins-releases + FancyPlugins Repository + https://repo.fancyinnovations.com/releases + +``` + +```xml + + de.oliver.FancyAnalytics + java-sdk + VERSION + +``` + +!!! warning +Make sure to shade the API into your app! You can use the [Shade plugin](https://imperceptiblethoughts.com/shadow/) for this. +!!! + +## Use the API + +### Initialize the ApiClient + +First you need to create an instance of the `ApiClient` class. + +```java +ApiClient fancyAnalytics = new ApiClient("https://api.fancyanalytics.net", "", "YOUR API TOKEN"); +``` + +### Send metric data + +You can send metric data to the server using the record service. + +```java +Record record = new Record("unique sender id", "project id", timestamp, new HashMap<>()); +record.withEntry("metric name", "metric value"); + +fancyAnalytics.getRecordService().createRecord("project id", record); +``` + +### Send events + +You can also send events to the server using the event service. + +```java +Event event = new Event("event name", new HashMap<>()); +event.withProperty("prop key", "prop value"); + +fancyAnalytics.getEventService().createEvent("project id", event); +``` \ No newline at end of file diff --git a/docs/src/fancyanalytics/getting-started/minecraft-plugins.md b/docs/src/fancyanalytics/getting-started/minecraft-plugins.md new file mode 100644 index 00000000..ad92066b --- /dev/null +++ b/docs/src/fancyanalytics/getting-started/minecraft-plugins.md @@ -0,0 +1,112 @@ +--- +icon: dot +order: 400 +--- + +# Minecraft Plugins + +This guide will help you set up FancyAnalytics in your Minecraft plugin. The API is very easy to use and has many default metrics. You can also define your own metrics and events. + +## Include the FancyAnalytics API + +### Gradle + +```kotlin +repositories { + maven("https://repo.fancyinnovations.com/releases") +} +``` + +```kotlin +dependencies { + implementation("de.oliver.fancyanalytics:mc-api:VERSION") +} +``` + +### Maven + +```xml + + fancyplugins-releases + FancyPlugins Repository + https://repo.fancyinnovations.com/releases + +``` + +```xml + + de.oliver.FancyAnalytics + mc-api + VERSION + +``` + +!!! warning +Make sure to shade the API into your plugin! You can use the [Shade plugin](https://imperceptiblethoughts.com/shadow/) for this. +!!! + +## Initialize the API + +```java +FancyAnalyticsAPI fancyAnalytics = new FancyAnalyticsAPI("project-id", "api-token"); +fancyAnalytics.registerMinecraftPluginMetrics(); +fancyAnalytics.initialize(); +``` + +You can find your project ID and api token in the project settings page. + +### Custom metrics + +You can also send custom metrics to the server: + +```java +// Register a number metric to track the amount of npcs +fancyAnalytics.registerNumberMetric(new MetricSupplier<>("amount_npcs", () -> npcManager.getNpcs().size())); + +// Register a string metric to track the used language +fancyAnalytics.registerStringMetric(new MetricSupplier<>("language", () -> languageManager.getLanguage())); +``` + +You can also send multiple values at once with the `registerStringArrayMetric` and `registerNumberArrayMetric` methods. +This is useful for tracking the player client's version for example. + +Make sure to add the metrics on website at the project settings page (must be same name as in the code)! + +### Events + +Some things are better tracked as events. For example, purchases in a shop. You can send events like this: + +```java +fancyAnalytics.sendEvent( + new Event("PurchasedItem") + .withProperty("player","Steve") + .withProperty("item","Diamond") + .withProperty("amount","1") + .withProperty("price","5") +); +``` + +You can also add custom properties to the event. Each property has a key (string) and a value (string but can be +converted to a number if needed). + +Once the first event is sent, there will be a new event-type created on the website. This event-type will have the name +and the keys of all properties of the event. You can then see the events on the website. + +You do not need to add the events on the website, they will be created automatically and all properties will be updated +automatically as well. + +### Error reporting + +FancyAnalytics can also track errors in your project. All you need to do is register all relevant loggers: + +```java +Logger myLogger = ...; +fancyAnalytics.getExceptionHandler().registerLogger(myLogger); +``` + +All exceptions that are thrown in the logger and are related to the plugin will be tracked. You can see all thrown +exceptions on the website. + +### Done! + +This is all you need to do to get started with FancyAnalytics. It will automatically send the data to the server. \ No newline at end of file diff --git a/docs/src/fancyanalytics/getting-started/minecraft-servers.md b/docs/src/fancyanalytics/getting-started/minecraft-servers.md new file mode 100644 index 00000000..9b0afe27 --- /dev/null +++ b/docs/src/fancyanalytics/getting-started/minecraft-servers.md @@ -0,0 +1,32 @@ +--- +icon: dot +order: 500 +--- + +# Minecraft Servers + +This guide will help you set up FancyAnalytics on your Minecraft server. The plugin already has many default metrics. + +## Installation + +To install FancyAnalytics on your server, you need to follow these steps: + +1. Download the latest release from the [download page](https://fancyanalytics.net/downloads) +2. Put the downloaded jar file in the ``plugins`` folder of your server +3. Restart your server +4. Run the command `/fancyanalytics version` to confirm that the plugin is installed + +## Configuration + +To use FancyAnalytics, you need to create an account on the [FancyAnalytics website](https://fancyanalytics.net/register) and create a new project. +After creating the project, you need to put the project ID and the API key in the `config.yml` file of the plugin. + +```yaml +project_id: "your project id" +api_key: "your api key", +enable_default_events: false +``` + +## Usage + +All you need to do is wait for the data to be collected, and then you can see it on the website. This can take up to 2 minutes. diff --git a/docs/src/fancyanalytics/getting-started/rest-api.md b/docs/src/fancyanalytics/getting-started/rest-api.md new file mode 100644 index 00000000..90ba1d02 --- /dev/null +++ b/docs/src/fancyanalytics/getting-started/rest-api.md @@ -0,0 +1,8 @@ +--- +icon: dot +order: 200 +--- + +# REST API + +TODO \ No newline at end of file