/gt renewcache (3) – Manually renews the cache.
/gt link (4) – Links your Minecraft account to external connections.discord - Begins the process to link your Minecraft account with your Discord. Join our Discord Server to complete the connection.email <email> - Adds an email to receive account-related updates. This is not a newsletter.email <address> - Adds an email to receive account-related updates. This is not a newsletter./gt unlink (5) – Removes external connections from your Minecraft account.discord - Unlinks your Minecraft account from Discord.email <email> - Removes your email from the account.email - Removes your email from the account./gt verify (6) - Verifies specific connections.We're currently working on a Fabric version of GlobalTags. If you have good fabric and mixin knowledge and you want to contribute, feel free to create a ticket on our Discord Server!
GlobalTags is an API designed to enhance player experiences by allowing users to create custom tags visible to everyone using the addon. This documentation will guide you through integrating, customizing, and extending GlobalTags for your project.
"},{"location":"#what-is-globaltags","title":"What is GlobalTags?","text":"GlobalTags enables players to create unique tags that are globally displayed, with options to customize their position and icon. It offers seamless integration across multiple platforms and supports various programming languages.
"},{"location":"#features","title":"Features","text":"Feel free to explore the documentation and start building with GlobalTags!
"},{"location":"faq/","title":"FAQ","text":""},{"location":"faq/#general","title":"General","text":""},{"location":"faq/#what-do-the-different-role-icons-mean","title":"What do the different role icons mean?","text":"Icon RoleAdmin
Developer
Discord Moderator
Partner
Financial Supporter / Discord Booster
"},{"location":"faq/#which-commands-can-i-use","title":"Which commands can I use?","text":"There are several commands to help manage your settings. The main command is /globaltags, or you can use the shorthand /gt. Here are the available subcommands:
/gt (1) - Displays the current API and Agent versions./gt clearcache (2) \u2013 Instantly clears your cache./gt renewcache (3) \u2013 Manually renews the cache./gt link (4) \u2013 Links your Minecraft account to external connections.discord - Begins the process to link your Minecraft account with your Discord. Join our Discord Server to complete the connection.email <email> - Adds an email to receive account-related updates. This is not a newsletter./gt unlink (5) \u2013 Removes external connections from your Minecraft account.discord - Unlinks your Minecraft account from Discord.email <email> - Removes your email from the account./gt verify (6) - Verifies specific connections.email <code> - Verifies your email by entering the confirmation code sent to your inbox.Base Command:
/globaltagsClear Cache:
/gt ccRenew Cache:
/gt renew, /gt rcLink Connection:
Unlink Connection:
Verify Connection:
You can customize your tag with colors using Minecraft's default color codes. To add a color to your tag, simply include the appropriate color code before your text. The codes range from 0-9 for various numbers, and a-f for letters, along with additional codes for effects like bold or italic text.
Here's a quick reference for Minecraft's color codes:
0 - Black1 - Dark Blue2 - Dark Green3 - Dark Aqua4 - Dark Red5 - Dark Purple6 - Gold7 - Gray8 - Dark Gray9 - Bluea - Greenb - Aquac - Redd - Light Purplee - Yellowf - Whitek - Obfuscatedl - Boldm - Strikethroughn - Underlinedo - ItalicHex colors are not supported yet, but this feature may be added in the future. To apply these codes, use the & symbol followed by the code, like this:
&aThis is a green tag\nNote
Please do NOT put spaces after color codes as this will create a whitespace which is a rule violation.
Do - &eExample Don't - &e Example
Certain words, such as \"LabyMod\", are on a blocklist to prevent users from impersonating staff members. For example, setting your tag to something like &f&lLabyMod &cModerator could closely mimic official staff tags. This blocklist helps maintain authenticity and prevents confusion among users.
The GlobalTags system is provided for use by players and developers in the Minecraft community. We allow a lot of freedom in the choice of tags, but there are some limits that must not be exceeded. Your use of the service is subject to the following conditions:
Violating these rules may result in a permanent suspension from GlobalTags services, without any refunds for prior purchases. See General Terms and Conditions
"},{"location":"api/custom-auth-provider/","title":"Creating your own auth provider for the API","text":"Thank you for your interest in contributing to the GlobalTags API! Contributions are welcome and greatly appreciated.
"},{"location":"api/custom-auth-provider/#setting-up-your-development-environment","title":"Setting Up Your Development Environment","text":"Install Dependencies
Ensure you have bun installed. Then run:
bun i\nCreate a config
See Create a Configuration File
Run the API
bun dev\nThe GlobalTags API uses an AuthProvider class to handle authentication. To extend the authentication mechanism, you can implement your own class by extending src/auth/AuthProvider.
As outlined in the How Authentication Works section, the Authorization header must consist of two values: id and token.
You need to define the following values:
id: The unique identifier for your provider. In this example, we'll use Testing as the id.name: A descriptive name for your service, such as the name of the authentication mechanism. In this example, we'll use MyService as the name. (1)
name is used only for naming files and classes; it has no effect on the code itself.If you're unsure about the implementation, you can refer to the existing AuthProvider implementations for guidance.
AuthProvider Class","text":"Create a new file in the src/auth/providers directory, for example, MyServiceProvider.ts, that extends AuthProvider. You need to implement the #getUUID method and initialize the constructor.
import AuthProvider from \"../AuthProvider\";\n\nexport default class MyServiceProvider extends AuthProvider {\n constructor() {\n super('Testing'); // (1)\n }\n\n async getUUID(token: string): Promise<string | null> { // (2)\n return \"00000000-0000-0000-0000-000000000000\"; // (3)\n }\n}\nid value for your provider.token parameter refers only to the token itself and does not include the authentication provider id.null if the token does not map to a valid UUID.AuthProvider","text":"To test your custom authentication provider, send a POST request to /players/<uuid> with the appropriate Authorization header in the format <id> <token>. For this example, a header could look like this:
Authorization: Testing somerandomtoken\nYou can then submit the changes by opening a pull request with a clear title and description of your changes.
"},{"location":"api/custom-auth-provider/#license","title":"License","text":"By contributing to GlobalTags API, you agree that your contributions will be licensed under the MIT License.
Thank you for your contributions! Your efforts help improve the GlobalTags API for everyone.
"},{"location":"api/guide/","title":"GlobalTags API","text":"The GlobalTags API is the core component that enables communication between mod wrappers and the database. This guide will walk you through the usage of the API and offer solutions to common issues.
SelfhostingIf you want to host your own instance of the GlobalTagsAPI, see the Self-hosting Guide.
"},{"location":"api/guide/#available-routes-and-how-to-use-them","title":"Available Routes and How to Use Them","text":"For a complete list of available routes and detailed documentation on how to use them, visit our API documentation. If you're interested in using the API within a specific programming language, don't forget to check out our various language wrappers for implementation examples.
"},{"location":"api/guide/#authentication","title":"Authentication","text":"To interact with the GlobalTags API, proper authentication is essential. Here's how our authentication process works:
"},{"location":"api/guide/#how-authentication-works","title":"How Authentication Works","text":"You authenticate by passing an Authorization header with your request. This header consists of two parts: the authentication provider ID (id) and the token (token). The format of the header looks like this:
Authorization: <id> <token>\nAn authentication provider (or auth provider for short) is the system that verifies the token and extracts a player's UUID from it. This design allows the API to work flexibly across different environments, ensuring broad compatibility.
By using auth providers, we make it easy to integrate GlobalTags with various authentication systems while keeping the API secure and adaptable.
"},{"location":"api/guide/#example","title":"Example","text":"Default Authentication ProvidersHere are the three default authentication providers supported by GlobalTags:
YggdrasilProvider): Requires a Minecraft access token as the token parameter.LabyConnectProvider): Requires a LabyConnect session token as the token parameter.ApiKeyProvider): Requires an API token, which must be manually assigned to an account by staff.Let's walk through an example to illustrate how the authentication process works. Suppose you send the following Authorization header in your request:
Authorization: Minecraft someminecraftsessiontoken\nHere's what happens next:
id - in this case, Minecraft.someminecraftsessiontoken) and attempts to extract a UUID from it.Want to create your own custom authentication provider? This guide covers everything you need to know.
"},{"location":"api/guide/#image-serving","title":"Image Serving","text":"Icons and role images play a key role in GlobalTags, so the API provides specific routes to serve these images. Below are the routes you can use to access the three types of icons.
"},{"location":"api/guide/#accessing-default-global-icons","title":"Accessing Default Global Icons","text":"To load default icons, use the following URL format, replacing <name> with the lowercase name of the icon:
https://cdn.rappytv.com/globaltags/icons/<name>.png\nFor custom per-player icons, you\u2019ll need the hash value, which can be obtained by making a GET request to /players/<uuid> and retrieving the icon.hash key. Then, use the following URL format:
https://api.globaltags.xyz/players/<uuid>/icon/<hash>\nTo load role-specific icons, use the URL format below, replacing <name> with the role name:
https://cdn.rappytv.com/globaltags/icons/role/<name>.png\nError message: You've entered a malformed authorization header!
Cause: This error occurs when you either omit the Authorization header for a protected route or provide an invalid auth provider id that doesn't match any registered providers.
Solution: Ensure that the Authorization header follows the correct format:
Authorization: <auth provider id> <token>\nid is valid and corresponds to a registered provider."},{"location":"api/guide/#2-database-connection-issue","title":"2. Database Connection Issue","text":"Error message: The database is not connected. Please try again later!
Cause: This error indicates that the API could not establish a connection to the database.
Solution: Wait for a few minutes, as this issue is often temporary. If the problem persists for more than 5 minutes, please report it to our team through our Discord Server.
"},{"location":"api/guide/#3-unknown-error","title":"3. Unknown Error","text":"Error message: An unknown error ocurred! Please try again later
Cause: This error occurs due to an internal issue while processing your request. The system returns a generic error message to avoid exposing sensitive information.
Solution: Be patient, as resubmitting the request likely won't fix the issue. However, the development team will be automatically notified, and we will work on resolving it. If the error resolves itself, feel free to continue.
"},{"location":"api/self-hosting/","title":"Self-hosting the GlobalTagsAPI","text":""},{"location":"api/self-hosting/#prerequisites","title":"Prerequisites","text":"Start by cloning the repository to your local machine:
git clone https://github.com/Global-Tags/API gtapi\ncd gtapi\nNext, create a configuration file by copying the example provided. Adjust the settings in config.json as needed. The only mandatory change is the srv field, which should contain the connection string to your MongoDB instance.
cp config.json.example config.json\nInstall Required Dependencies
Use the following command to install the necessary dependencies:
bun i\nStart the API
To run the API, execute:
bun start\nTo keep the API online, install a tool called pm2 to daemonize the process:
# Install pm2 and pm2-logrotate globally\nbun i -g pm2 pm2-logrotate\n\n# Start the daemon\npm2 start src/index.ts --interpreter ~/.bun/bin/bun --name GlobalTagAPI\nYou have two options for running the API with Docker:
Option 1: Using Docker Compose
Run the following command to start the API in detached mode:
docker compose up -d # (1)\n-d option to run it in the foreground.Option 2: Without Docker Compose
You can also run the API without Docker Compose by executing:
docker run -p 5000:5000 $(docker build -q .)\nIn development
We're currently working on a Fabric version of GlobalTags. As this is a pretty complicated process we kindly ask you to be patient :)
If you have good fabric and mixin knowledge and you want to contribute, feel free to create a ticket on our Discord Server!
"},{"location":"implementations/labymod/","title":"LabyMod Addon","text":"Fun FactDid you know that the original idea behind GlobalTags was to create a simple LabyMod addon just for friends? It was later released to the public and expanded to support a wider range of environments!
"},{"location":"implementations/labymod/#installation","title":"Installation","text":"You can easily install the addon by searching for \"GlobalTags\" in the LabyMod Addon Store. It is available for all versions.
"},{"location":"implementations/labymod/#how-to-set-a-custom-tag","title":"How to Set a Custom Tag","text":"To create a custom tag, follow these steps:
In the settings, you'll see a tag preview and an input field. Enter your desired tag (1), select a position for the tag, choose an icon, and click \"Update\" to apply the changes.
If you've been banned, it's likely for a significant rule violation, and you'll probably only be granted one second chance. To appeal your ban:
If the appeal button is clickable, a modal will pop up with an input field. Write your apology or the reason you believe the ban should be lifted, and click \"Send appeal.\" Your appeal will be reviewed, and a decision will be made on whether to lift the ban.
"},{"location":"wrappers/java/","title":"Java Wrapper","text":"WarningYou'll need Java Development Kit (JDK) 17 or higher to be able to use the wrapper. This may change in the future.
"},{"location":"wrappers/java/#overview","title":"Overview","text":"The GlobalTags Java Wrapper provides an easy-to-use class for interacting with the GlobalTags API. This wrapper simplifies the integration of custom player tags in a Minecraft mod, enabling developers to fetch tag data including the player's tag, icon, and roles. It offers various methods to authenticate with the API, handle cache, and translate color codes for text display.
"},{"location":"wrappers/java/#features","title":"Features","text":"To use this wrapper in your Java project, you can add it via Maven or Gradle. The package includes all necessary dependencies and models required to integrate the GlobalTags API into your mod. You don't need to add a seperate repository as it's hosted on Maven Central.
WarningYou need to replace VERSION with the version you want to use. This is the latest stable tag:
<dependencies>\n <dependency>\n <groupId>com.rappytv.globaltags</groupId>\n <artifactId>GlobalTagsJava</artifactId>\n <version>VERSION</version>\n </dependency>\n</dependencies>\ndependencies {\n compileOnly(\"com.rappytv.globaltags:GlobalTagsJava:VERSION\")\n}\ndependencies {\n compileOnly \"com.rappytv.globaltags:GlobalTagsJava:VERSION\"\n}\nTo implement the wrapper, create a class that extends the GlobalTagsAPI<T> class. This will give you access to a wide range of methods to interact with the GlobalTags API, such as fetching player information, translating color codes, handling authentication, and more.
public class MyGlobalTagsAPI implements GlobalTagsAPI<String> { // (1)\n\n @Override\n public Agent getAgent() {\n return new Agent(\"MyMod\", \"v1.0.0\", \"1.21\"); // (2)\n }\n\n @Override\n public String getLanguageCode() {\n return \"en_us\"; // (3)\n }\n\n @Override\n public String translateColorCodes(String input) {\n return input; // (4)\n }\n\n @Override\n public UUID getClientUUID() {\n return UUID.randomUUID(); // (5)\n }\n\n @Override\n public AuthProvider getAuthType() {\n return AuthProvider.YGGDRASIL; // (6)\n }\n\n @Override\n public String getAuthorization() {\n return \"my-api-token\"; // (7)\n }\n}\nT generic in GlobalTagsAPI<T> represents the type used for colored text components. It allows flexibility in how you implement color formatting, whether as a simple String, a TextComponent, or another type. Please note that the ApiHandler<T> and the PlayerInfo<T> also need to use the same generic value as the GlobalTagsAPI<T>.T class. For simplicity, this example returns the input as is.UUID.public class Main {\n\n private static GlobalTagsAPI<String> api;\n\n public static void main(String[] args) {\n // Create an instance of your implementation and save it in some kind of field or attribute\n api = new MyGlobalTagsAPI();\n\n // Fetch a player's tag data, cache it and print it out once resolved\n api.getCache().resolve(uuid, System.out::println);\n\n // Fetch the client's tag data, cache it and print it out once resolved (The client's uuid is the uuid specified in GlobalTagsAPI#getClientUUID)\n api.getCache().resolveSelf(System.out::println);\n\n // Fetch a player's tag data without caching it and print it out once resolved\n api.getApiHandler().getInfo(uuid, System.out::println);\n\n // Get a player's tag from the cache (or null if it's not in the cache)\n System.out.println(api.getCache().get(uuid).getTag());\n\n // Report a player and log the response message\n api.getApiHandler().reportPlayer(uuid, \"Racism\", (response) -> System.out.println(response.data()));\n\n // Get a player's ban reason (Note: This will only work on accounts with the GlobalTags admin permissions)\n PlayerInfo<String> info = api.getCache().get(uuid);\n System.out.println(info.isSuspended() ? info.getSuspension().getReason() : \"The user is not banned.\"); // (1)\n\n // Clear the cache\n api.getCache().clear();\n\n // Renew the cache (2)\n api.getCache().renew();\n }\n}\nSuspension#getReason will not be null as long as Suspension#isActive is trueAlso, everything is documented with javadocs so everything should be pretty self-explanatory. If you have any questions don't hesitate to create a new issue or create a ticket on the Discord Server.
"},{"location":"wrappers/java/#caching","title":"Caching","text":"The wrapper comes with a built-in caching mechanism to minimize redundant API calls. By default, cached data is refreshed every 5 minutes and completely cleared every 30 minutes.
Custom cache intervalsYou can customize the cache renewal and clearing intervals by creating your own PlayerInfo.Cache<T> instance using the constructor with the options parameter. After that, simply override the GlobalTagsAPI#getCache method to return your custom cache instance.
Using the example from above it would look like this:
public class MyGlobalTagsAPI implements GlobalTagsAPI<String> {\n\n private final PlayerInfo.Cache<T> cache = new PlayerInfo.Cache<>(this, new PlayerInfo.Cache.Options() {\n @Override\n public long getCacheClearInterval() {\n // 10 minutes for example\n return 1000 * 60 * 10;\n }\n\n @Override\n public long getCacheRenewInterval() {\n // 2 minutes for example\n return 1000 * 60 * 2;\n }\n });\n\n @Override\n public Agent getAgent() {\n return new Agent(\"MyMod\", \"v1.0.0\", \"1.21\");\n }\n\n @Override\n public String getLanguageCode() {\n return \"en_us\";\n }\n\n @Override\n public String translateColorCodes(String input) {\n return input;\n }\n\n @Override\n public UUID getClientUUID() {\n return UUID.randomUUID();\n }\n\n // Override the cache getter here\n @Override\n public PlayerInfo.Cache<T> getCache() {\n return cache;\n }\n\n @Override\n public AuthProvider getAuthType() {\n return AuthProvider.YGGDRASIL;\n }\n\n @Override\n public String getAuthorization() {\n return \"my-api-token\";\n }\n}\nTo authenticate with the API, you need to provide an authorization token or other credentials depending on the authentication method (AuthProvider). To create an own auth mechanism for the API please read this page.
You can see production examples here:
This is subject to change. The Typescript wrapper will receive an update with a lot of breaking changes soon.
"},{"location":"wrappers/typescript/#dependency-installation","title":"Dependency installation","text":"To use this wrapper in your JavaScript/TypeScript app, you can add it via the npm registry.
npm bun pnpm yarnnpm i globaltags.ts\nbun i globaltags.ts\npnpm add globaltags.ts\nyarn add globaltags.ts\nAfter adding the dependency you can import the actual API class like this:
ES7 CommonJSimport { GlobalTagAPI } from \"globaltags.ts\";\nconst { GlobalTagAPI } = require('globaltags.ts');\nTo use the wrapper you only need to instantiate a new GlobalTagAPI object. You can then use GlobalTagAPI#fetchPlayer to fetch player data and receive an instance of the Player class.
const api = new GlobalTagAPI(); // (1)\n\n// Get a player instance from a specific player uuid\nconst player = await api.fetchPlayer('<UUID>', { token: '<YOUR API KEY>' }).catch(() => null);\n\nif(!player) return;\n\n// You can now interact with the player data.\nconsole.log(player.tag || 'No Tag'); // (2)\n\nplayer.setTag('The new tag :o', { token: 'current auth token' }); // (3)\n\nplayer.appealBan('I want to apologize', { token: 'token' }); // (4)\nIf you find any bugs or have feature ideas feel free to create an issue.
"}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Welcome to GlobalTags","text":"We're looking for developers!We're currently working on a Fabric version of GlobalTags. If you have good fabric and mixin knowledge and you want to contribute, feel free to create a ticket on our Discord Server!
GlobalTags is an API designed to enhance player experiences by allowing users to create custom tags visible to everyone using the addon. This documentation will guide you through integrating, customizing, and extending GlobalTags for your project.
"},{"location":"#what-is-globaltags","title":"What is GlobalTags?","text":"GlobalTags enables players to create unique tags that are globally displayed, with options to customize their position and icon. It offers seamless integration across multiple platforms and supports various programming languages.
"},{"location":"#features","title":"Features","text":"Feel free to explore the documentation and start building with GlobalTags!
"},{"location":"faq/","title":"FAQ","text":""},{"location":"faq/#general","title":"General","text":""},{"location":"faq/#what-do-the-different-role-icons-mean","title":"What do the different role icons mean?","text":"Icon RoleAdmin
Developer
Discord Moderator
Partner
Financial Supporter / Discord Booster
"},{"location":"faq/#which-commands-can-i-use","title":"Which commands can I use?","text":"There are several commands to help manage your settings. The main command is /globaltags, or you can use the shorthand /gt. Here are the available subcommands:
/gt (1) - Displays the current API and Agent versions./gt clearcache (2) \u2013 Instantly clears your cache./gt renewcache (3) \u2013 Manually renews the cache./gt link (4) \u2013 Links your Minecraft account to external connections.discord - Begins the process to link your Minecraft account with your Discord. Join our Discord Server to complete the connection.email <address> - Adds an email to receive account-related updates. This is not a newsletter./gt unlink (5) \u2013 Removes external connections from your Minecraft account.discord - Unlinks your Minecraft account from Discord.email - Removes your email from the account./gt verify (6) - Verifies specific connections.email <code> - Verifies your email by entering the confirmation code sent to your inbox.Base Command:
/globaltagsClear Cache:
/gt ccRenew Cache:
/gt renew, /gt rcLink Connection:
Unlink Connection:
Verify Connection:
You can customize your tag with colors using Minecraft's default color codes. To add a color to your tag, simply include the appropriate color code before your text. The codes range from 0-9 for various numbers, and a-f for letters, along with additional codes for effects like bold or italic text.
Here's a quick reference for Minecraft's color codes:
0 - Black1 - Dark Blue2 - Dark Green3 - Dark Aqua4 - Dark Red5 - Dark Purple6 - Gold7 - Gray8 - Dark Gray9 - Bluea - Greenb - Aquac - Redd - Light Purplee - Yellowf - Whitek - Obfuscatedl - Boldm - Strikethroughn - Underlinedo - ItalicHex colors are not supported yet, but this feature may be added in the future. To apply these codes, use the & symbol followed by the code, like this:
&aThis is a green tag\nNote
Please do NOT put spaces after color codes as this will create a whitespace which is a rule violation.
Do - &eExample Don't - &e Example
Certain words, such as \"LabyMod\", are on a blocklist to prevent users from impersonating staff members. For example, setting your tag to something like &f&lLabyMod &cModerator could closely mimic official staff tags. This blocklist helps maintain authenticity and prevents confusion among users.
The GlobalTags system is provided for use by players and developers in the Minecraft community. We allow a lot of freedom in the choice of tags, but there are some limits that must not be exceeded. Your use of the service is subject to the following conditions:
Violating these rules may result in a permanent suspension from GlobalTags services, without any refunds for prior purchases. See General Terms and Conditions
"},{"location":"api/custom-auth-provider/","title":"Creating your own auth provider for the API","text":"Thank you for your interest in contributing to the GlobalTags API! Contributions are welcome and greatly appreciated.
"},{"location":"api/custom-auth-provider/#setting-up-your-development-environment","title":"Setting Up Your Development Environment","text":"Install Dependencies
Ensure you have bun installed. Then run:
bun i\nCreate a config
See Create a Configuration File
Run the API
bun dev\nThe GlobalTags API uses an AuthProvider class to handle authentication. To extend the authentication mechanism, you can implement your own class by extending src/auth/AuthProvider.
As outlined in the How Authentication Works section, the Authorization header must consist of two values: id and token.
You need to define the following values:
id: The unique identifier for your provider. In this example, we'll use Testing as the id.name: A descriptive name for your service, such as the name of the authentication mechanism. In this example, we'll use MyService as the name. (1)
name is used only for naming files and classes; it has no effect on the code itself.If you're unsure about the implementation, you can refer to the existing AuthProvider implementations for guidance.
AuthProvider Class","text":"Create a new file in the src/auth/providers directory, for example, MyServiceProvider.ts, that extends AuthProvider. You need to implement the #getUUID method and initialize the constructor.
import AuthProvider from \"../AuthProvider\";\n\nexport default class MyServiceProvider extends AuthProvider {\n constructor() {\n super('Testing'); // (1)\n }\n\n async getUUID(token: string): Promise<string | null> { // (2)\n return \"00000000-0000-0000-0000-000000000000\"; // (3)\n }\n}\nid value for your provider.token parameter refers only to the token itself and does not include the authentication provider id.null if the token does not map to a valid UUID.AuthProvider","text":"To test your custom authentication provider, send a POST request to /players/<uuid> with the appropriate Authorization header in the format <id> <token>. For this example, a header could look like this:
Authorization: Testing somerandomtoken\nYou can then submit the changes by opening a pull request with a clear title and description of your changes.
"},{"location":"api/custom-auth-provider/#license","title":"License","text":"By contributing to GlobalTags API, you agree that your contributions will be licensed under the MIT License.
Thank you for your contributions! Your efforts help improve the GlobalTags API for everyone.
"},{"location":"api/guide/","title":"GlobalTags API","text":"The GlobalTags API is the core component that enables communication between mod wrappers and the database. This guide will walk you through the usage of the API and offer solutions to common issues.
SelfhostingIf you want to host your own instance of the GlobalTagsAPI, see the Self-hosting Guide.
"},{"location":"api/guide/#available-routes-and-how-to-use-them","title":"Available Routes and How to Use Them","text":"For a complete list of available routes and detailed documentation on how to use them, visit our API documentation. If you're interested in using the API within a specific programming language, don't forget to check out our various language wrappers for implementation examples.
"},{"location":"api/guide/#authentication","title":"Authentication","text":"To interact with the GlobalTags API, proper authentication is essential. Here's how our authentication process works:
"},{"location":"api/guide/#how-authentication-works","title":"How Authentication Works","text":"You authenticate by passing an Authorization header with your request. This header consists of two parts: the authentication provider ID (id) and the token (token). The format of the header looks like this:
Authorization: <id> <token>\nAn authentication provider (or auth provider for short) is the system that verifies the token and extracts a player's UUID from it. This design allows the API to work flexibly across different environments, ensuring broad compatibility.
By using auth providers, we make it easy to integrate GlobalTags with various authentication systems while keeping the API secure and adaptable.
"},{"location":"api/guide/#example","title":"Example","text":"Default Authentication ProvidersHere are the three default authentication providers supported by GlobalTags:
YggdrasilProvider): Requires a Minecraft access token as the token parameter.LabyConnectProvider): Requires a LabyConnect session token as the token parameter.ApiKeyProvider): Requires an API token, which must be manually assigned to an account by staff.Let's walk through an example to illustrate how the authentication process works. Suppose you send the following Authorization header in your request:
Authorization: Minecraft someminecraftsessiontoken\nHere's what happens next:
id - in this case, Minecraft.someminecraftsessiontoken) and attempts to extract a UUID from it.Want to create your own custom authentication provider? This guide covers everything you need to know.
"},{"location":"api/guide/#image-serving","title":"Image Serving","text":"Icons and role images play a key role in GlobalTags, so the API provides specific routes to serve these images. Below are the routes you can use to access the three types of icons.
"},{"location":"api/guide/#accessing-default-global-icons","title":"Accessing Default Global Icons","text":"To load default icons, use the following URL format, replacing <name> with the lowercase name of the icon:
https://cdn.rappytv.com/globaltags/icons/<name>.png\nFor custom per-player icons, you\u2019ll need the hash value, which can be obtained by making a GET request to /players/<uuid> and retrieving the icon.hash key. Then, use the following URL format:
https://api.globaltags.xyz/players/<uuid>/icon/<hash>\nTo load role-specific icons, use the URL format below, replacing <name> with the role name:
https://cdn.rappytv.com/globaltags/icons/role/<name>.png\nError message: You've entered a malformed authorization header!
Cause: This error occurs when you either omit the Authorization header for a protected route or provide an invalid auth provider id that doesn't match any registered providers.
Solution: Ensure that the Authorization header follows the correct format:
Authorization: <auth provider id> <token>\nid is valid and corresponds to a registered provider."},{"location":"api/guide/#2-database-connection-issue","title":"2. Database Connection Issue","text":"Error message: The database is not connected. Please try again later!
Cause: This error indicates that the API could not establish a connection to the database.
Solution: Wait for a few minutes, as this issue is often temporary. If the problem persists for more than 5 minutes, please report it to our team through our Discord Server.
"},{"location":"api/guide/#3-unknown-error","title":"3. Unknown Error","text":"Error message: An unknown error ocurred! Please try again later
Cause: This error occurs due to an internal issue while processing your request. The system returns a generic error message to avoid exposing sensitive information.
Solution: Be patient, as resubmitting the request likely won't fix the issue. However, the development team will be automatically notified, and we will work on resolving it. If the error resolves itself, feel free to continue.
"},{"location":"api/self-hosting/","title":"Self-hosting the GlobalTagsAPI","text":""},{"location":"api/self-hosting/#prerequisites","title":"Prerequisites","text":"Start by cloning the repository to your local machine:
git clone https://github.com/Global-Tags/API gtapi\ncd gtapi\nNext, create a configuration file by copying the example provided. Adjust the settings in config.json as needed. The only mandatory change is the srv field, which should contain the connection string to your MongoDB instance.
cp config.json.example config.json\nInstall Required Dependencies
Use the following command to install the necessary dependencies:
bun i\nStart the API
To run the API, execute:
bun start\nTo keep the API online, install a tool called pm2 to daemonize the process:
# Install pm2 and pm2-logrotate globally\nbun i -g pm2 pm2-logrotate\n\n# Start the daemon\npm2 start src/index.ts --interpreter ~/.bun/bin/bun --name GlobalTagAPI\nYou have two options for running the API with Docker:
Option 1: Using Docker Compose
Run the following command to start the API in detached mode:
docker compose up -d # (1)\n-d option to run it in the foreground.Option 2: Without Docker Compose
You can also run the API without Docker Compose by executing:
docker run -p 5000:5000 $(docker build -q .)\nIn development
We're currently working on a Fabric version of GlobalTags. As this is a pretty complicated process we kindly ask you to be patient :)
If you have good fabric and mixin knowledge and you want to contribute, feel free to create a ticket on our Discord Server!
"},{"location":"implementations/labymod/","title":"LabyMod Addon","text":"Fun FactDid you know that the original idea behind GlobalTags was to create a simple LabyMod addon just for friends? It was later released to the public and expanded to support a wider range of environments!
"},{"location":"implementations/labymod/#installation","title":"Installation","text":"You can easily install the addon by searching for \"GlobalTags\" in the LabyMod Addon Store. It is available for all versions.
"},{"location":"implementations/labymod/#how-to-set-a-custom-tag","title":"How to Set a Custom Tag","text":"To create a custom tag, follow these steps:
In the settings, you'll see a tag preview and an input field. Enter your desired tag (1), select a position for the tag, choose an icon, and click \"Update\" to apply the changes.
If you've been banned, it's likely for a significant rule violation, and you'll probably only be granted one second chance. To appeal your ban:
If the appeal button is clickable, a modal will pop up with an input field. Write your apology or the reason you believe the ban should be lifted, and click \"Send appeal.\" Your appeal will be reviewed, and a decision will be made on whether to lift the ban.
"},{"location":"wrappers/java/","title":"Java Wrapper","text":"WarningYou'll need Java Development Kit (JDK) 17 or higher to be able to use the wrapper. This may change in the future.
"},{"location":"wrappers/java/#overview","title":"Overview","text":"The GlobalTags Java Wrapper provides an easy-to-use class for interacting with the GlobalTags API. This wrapper simplifies the integration of custom player tags in a Minecraft mod, enabling developers to fetch tag data including the player's tag, icon, and roles. It offers various methods to authenticate with the API, handle cache, and translate color codes for text display.
"},{"location":"wrappers/java/#features","title":"Features","text":"To use this wrapper in your Java project, you can add it via Maven or Gradle. The package includes all necessary dependencies and models required to integrate the GlobalTags API into your mod. You don't need to add a seperate repository as it's hosted on Maven Central.
WarningYou need to replace VERSION with the version you want to use. This is the latest stable tag:
<dependencies>\n <dependency>\n <groupId>com.rappytv.globaltags</groupId>\n <artifactId>GlobalTagsJava</artifactId>\n <version>VERSION</version>\n </dependency>\n</dependencies>\ndependencies {\n compileOnly(\"com.rappytv.globaltags:GlobalTagsJava:VERSION\")\n}\ndependencies {\n compileOnly \"com.rappytv.globaltags:GlobalTagsJava:VERSION\"\n}\nTo implement the wrapper, create a class that extends the GlobalTagsAPI<T> class. This will give you access to a wide range of methods to interact with the GlobalTags API, such as fetching player information, translating color codes, handling authentication, and more.
public class MyGlobalTagsAPI implements GlobalTagsAPI<String> { // (1)\n\n @Override\n public Agent getAgent() {\n return new Agent(\"MyMod\", \"v1.0.0\", \"1.21\"); // (2)\n }\n\n @Override\n public String getLanguageCode() {\n return \"en_us\"; // (3)\n }\n\n @Override\n public String translateColorCodes(String input) {\n return input; // (4)\n }\n\n @Override\n public UUID getClientUUID() {\n return UUID.randomUUID(); // (5)\n }\n\n @Override\n public AuthProvider getAuthType() {\n return AuthProvider.YGGDRASIL; // (6)\n }\n\n @Override\n public String getAuthorization() {\n return \"my-api-token\"; // (7)\n }\n}\nT generic in GlobalTagsAPI<T> represents the type used for colored text components. It allows flexibility in how you implement color formatting, whether as a simple String, a TextComponent, or another type. Please note that the ApiHandler<T> and the PlayerInfo<T> also need to use the same generic value as the GlobalTagsAPI<T>.T class. For simplicity, this example returns the input as is.UUID.public class Main {\n\n private static GlobalTagsAPI<String> api;\n\n public static void main(String[] args) {\n // Create an instance of your implementation and save it in some kind of field or attribute\n api = new MyGlobalTagsAPI();\n\n // Fetch a player's tag data, cache it and print it out once resolved\n api.getCache().resolve(uuid, System.out::println);\n\n // Fetch the client's tag data, cache it and print it out once resolved (The client's uuid is the uuid specified in GlobalTagsAPI#getClientUUID)\n api.getCache().resolveSelf(System.out::println);\n\n // Fetch a player's tag data without caching it and print it out once resolved\n api.getApiHandler().getInfo(uuid, System.out::println);\n\n // Get a player's tag from the cache (or null if it's not in the cache)\n System.out.println(api.getCache().get(uuid).getTag());\n\n // Report a player and log the response message\n api.getApiHandler().reportPlayer(uuid, \"Racism\", (response) -> System.out.println(response.data()));\n\n // Get a player's ban reason (Note: This will only work on accounts with the GlobalTags admin permissions)\n PlayerInfo<String> info = api.getCache().get(uuid);\n System.out.println(info.isSuspended() ? info.getSuspension().getReason() : \"The user is not banned.\"); // (1)\n\n // Clear the cache\n api.getCache().clear();\n\n // Renew the cache (2)\n api.getCache().renew();\n }\n}\nSuspension#getReason will not be null as long as Suspension#isActive is trueAlso, everything is documented with javadocs so everything should be pretty self-explanatory. If you have any questions don't hesitate to create a new issue or create a ticket on the Discord Server.
"},{"location":"wrappers/java/#caching","title":"Caching","text":"The wrapper comes with a built-in caching mechanism to minimize redundant API calls. By default, cached data is refreshed every 5 minutes and completely cleared every 30 minutes.
Custom cache intervalsYou can customize the cache renewal and clearing intervals by creating your own PlayerInfo.Cache<T> instance using the constructor with the options parameter. After that, simply override the GlobalTagsAPI#getCache method to return your custom cache instance.
Using the example from above it would look like this:
public class MyGlobalTagsAPI implements GlobalTagsAPI<String> {\n\n private final PlayerInfo.Cache<T> cache = new PlayerInfo.Cache<>(this, new PlayerInfo.Cache.Options() {\n @Override\n public long getCacheClearInterval() {\n // 10 minutes for example\n return 1000 * 60 * 10;\n }\n\n @Override\n public long getCacheRenewInterval() {\n // 2 minutes for example\n return 1000 * 60 * 2;\n }\n });\n\n @Override\n public Agent getAgent() {\n return new Agent(\"MyMod\", \"v1.0.0\", \"1.21\");\n }\n\n @Override\n public String getLanguageCode() {\n return \"en_us\";\n }\n\n @Override\n public String translateColorCodes(String input) {\n return input;\n }\n\n @Override\n public UUID getClientUUID() {\n return UUID.randomUUID();\n }\n\n // Override the cache getter here\n @Override\n public PlayerInfo.Cache<T> getCache() {\n return cache;\n }\n\n @Override\n public AuthProvider getAuthType() {\n return AuthProvider.YGGDRASIL;\n }\n\n @Override\n public String getAuthorization() {\n return \"my-api-token\";\n }\n}\nTo authenticate with the API, you need to provide an authorization token or other credentials depending on the authentication method (AuthProvider). To create an own auth mechanism for the API please read this page.
You can see production examples here:
This is subject to change. The Typescript wrapper will receive an update with a lot of breaking changes soon.
"},{"location":"wrappers/typescript/#dependency-installation","title":"Dependency installation","text":"To use this wrapper in your JavaScript/TypeScript app, you can add it via the npm registry.
npm bun pnpm yarnnpm i globaltags.ts\nbun i globaltags.ts\npnpm add globaltags.ts\nyarn add globaltags.ts\nAfter adding the dependency you can import the actual API class like this:
ES7 CommonJSimport { GlobalTagAPI } from \"globaltags.ts\";\nconst { GlobalTagAPI } = require('globaltags.ts');\nTo use the wrapper you only need to instantiate a new GlobalTagAPI object. You can then use GlobalTagAPI#fetchPlayer to fetch player data and receive an instance of the Player class.
const api = new GlobalTagAPI(); // (1)\n\n// Get a player instance from a specific player uuid\nconst player = await api.fetchPlayer('<UUID>', { token: '<YOUR API KEY>' }).catch(() => null);\n\nif(!player) return;\n\n// You can now interact with the player data.\nconsole.log(player.tag || 'No Tag'); // (2)\n\nplayer.setTag('The new tag :o', { token: 'current auth token' }); // (3)\n\nplayer.appealBan('I want to apologize', { token: 'token' }); // (4)\nIf you find any bugs or have feature ideas feel free to create an issue.
"}]} \ No newline at end of file diff --git a/sitemap.xml.gz b/sitemap.xml.gz index ba48cb4..6067338 100644 Binary files a/sitemap.xml.gz and b/sitemap.xml.gz differ