Presence Guidelines

Revision 3.2

Guidelines

When publishing Presences to this GitHub, we require you to follow a set of guidelines. To some, these strict rules may seem harsh. However, the implementation of these rulesets will keep us and the users from running into any issues.

Creation

The general rules of presence development are as follows:

Presences must be related to the website of choice.
Presences cannot be made for illegal websites. (for e.g., stressors, drug marketing, child pornography, etc.)
Presences cannot be made for services featuring mainly explicit content.
- If the service has some explicit content, the presence must avoid displaying it.
The file structure must be clean and managed, do not include files which are not specified. (for e.g., vscode and git folders, image and text files, etc.)
Presences for websites with (.onion TLDs) or websites with free domains/hosts (for e.g., .TK [all free Freenom domains], .RF, GD, etc) are not permitted, exceptions can be made if a proof is presented showing that they paid for the domain.
The domain of the presence must be at least 2 months old.
Presence that target internal browser pages (like Chrome Web Store, chrome://, about: pages, etc) are not allowed as they require an experimental flag to be enabled on the user's end and could potentially cause damage to their browsers.
Presences with support for only a single subdomain will not be permitted, as they may seem broken for other pages (like the homepage), exceptions can be made for the policy and contact pages (content that isn't used often) or sites where the other content is unrelated. (for e.g., wikia pages)
Presences for online radios are only allowed if the radio has at least 100 weekly listeners and 15 concurrent and must have some features other than just showing album/song title, etc.
Presences are not allowed to run JS code with their own function to get variables. If there are issues with the built-in functions inside the Presence class, you are allowed to do your own function and you need to tell us about it in Pull Request description.
Low quality presences (or ones with little context) are not allowed (for e.g., only showing a logo and text but never changing it again).
Presences for services like Discord Bot/Server Lists must follow these extra requirements:
- The domain should be at least 6 months old.
- Unique visitors per day:
  - For 6 to 12 month old domains: 20,000 unique visitors/day.
  - For 12+ month old domains: 45,000 unique visitors/day.
- The website can't be on a cheap domain like .xyz, .club and so on.
- The website itself must have a very good quality, design, etc.
Presences should use common details (strings starting with "general."). You can achieve this using multiLanguage with the provided strings. If your presence requires custom strings, then you shouldn't use multiLanguage until the presence gets 1000 users. You can find an example here.
Including the presence.ts file, iframe.ts file, and metadata.json file is mandatory so the result would be what is represented in the following schema:

presence
├── metadata.json
└── presence.ts

or if you're using a iframe.ts file:

presence
├── metadata.json
├── presence.ts
└── iframe.ts

metadata.json

For the convenience of our presence developers, we have provided a schema which you can use to validate the integrity of your metadata file. This is entirely optional and is not required during the review process.

It is highly recommended that you organize your metadata file in the format shown below, and you must have grammatically correct service names, descriptions, tags, and setting fields. Anything not organized to specifications will not be permitted.

Each presence has a descriptor file called metadata.json, the metadata has a strict standard and an example of this file can be seem below:

{
  "$schema": "https://schemas.premid.app/metadata/1.9",
  "author": {
    "name": "USER",
    "id": "ID"
  },
  "contributors": [
    {
      "name": "USER",
      "id": "ID"
    }
  ],
  "service": "SERVICE",
  "altnames": ["SERVICE"],
  "description": {
    "en": "DESCRIPTION"
  },
  "url": "URL",
  "matches": ["URL"],
  "version": "VERSION",
  "logo": "URL",
  "thumbnail": "URL",
  "color": "#HEX000",
  "tags": ["TAG1", "TAG2"],
  "category": "CATEGORY",
  "regExp": "REGEXP",
  "iFrameRegExp": "REGEXP",
  "iframe": false,
  "iFrameMatches": ["URL"],
  "readLogs": false,
  "settings": [
    {
      "id": "multiLanguage",
      "multiLanguage": true
    }
    {
      "id": "ID",
      "title": "DISPLAY TITLE",
      "icon": "FONTAWESOME ICON",
      "value": true
    },
    {
      "id": "ID",
      "if": {
        "ID": true
      },
      "title": "DISPLAY TITLE",
      "icon": "FONTAWESOME ICON",
      "value": "\"%song%\" by %artist%",
      "placeholder": "use %song% or %artist%"
    },
    {
      "id": "ID",
      "title": "DISPLAY TITLE",
      "icon": "FONTAWESOME ICON",
      "value": 0,
      "values": ["1", "2", "etc."]
    }
  ]
}

If a field is listed as optional on the documentation or there is a * next to the key, and your presence uses the default value for it, do not include it in the metadata file. (for e.g., a presence without iframe support would not need the iframe field.)

All images in the metadata file must be hosted on i.imgur.com. Using content hosted on the website is not permitted as they can change the paths and files unwillingly.

A list of fields and their rules are listed below:

`$schema`

The schema key must include a dollar sign at the beginning of it, this will signal your text editor that you want to validate your JSON file against a model. As stated earlier, you do not need to include a schema, but if you include it you must take this into account.

`author`

The ID value must be your Discord snowflake ID. You can get it by enabling developer mode. Please do not confuse this with your application ID, which is only for your presence.

**`*contributors`**

Do not add yourself as a contributor, and do not add someone else as a contributor unless they have helped with the presence.

`service`

The service name must be the name of the presence directory. For example, if the presence is located at /websites/Y/YouTube/, the service name must be YouTube.
You cannot use the url as the service name unless the website uses the url as its official name. If the name is not descriptive and can be considered vague, using the url is required. (for e.g., YouTube is permitted because that is the official name and is descriptive, while youtube.com is not. Top is a non-descriptive name, so using the url top.gg is required.)
If service has some explicit branding rules of their name, you should follow them.

**`*altnames`**

Only use this in scenarios where a website goes under multiple official names (e.g. Pokémon and 포켓몬스터). Shortened versions of service names go under tags.

`description`

All presences are required to have an English description regardless of the website's prefered language.
Do not try and translate the description yourself unless you know that language, translators will modify your metadata.json and change the descriptions if necessary.

`url`

The url must be a string if the website only uses one domain. If the website uses multiple, make this an array and specify each one.
Do not include protocols in the url (for e.g., http or https), and do not include query parameters in the url (for e.g., www.google.com/search?gws_rd=ssl which should be www.google.com)

`matches` or `iFrameMatches`

An array of strings which need to follow https://developer.chrome.com/docs/extensions/develop/concepts/match-patterns.

`version`

Always make sure the version number follows semantic versioning standards, which translates to the following scheme: <NEW-FEATURE>.<HUGE-BUGFIX>.<SMALL-BUGFIX-OR-METADATA-CHANGES>. Anything else like 1.0.0.1, 1.0, 1, 1.0.0-BETA or changing 1.0.0 to 2.0.0 on a bug fix/small change is not permitted.
The version must always start at 1.0.0 unless told otherwise, other versions will not be permitted.

`logo`

The logo must be a square image with a 1:1 aspect ratio.
The image is required to have a resolution of 512x512 pixels. You can upsize it using a tool like waifu2x.

`thumbnail`

The thumbnail should preferably be a wide promotional card or a screenshot if the first is not available.

`color`

The color must be a hexadecimal value between #000000 and #FFFFFF.
The color string must be prepended with a hash symbol.

`tags`

All presences are required to have at least one tag.
Tags must not include any spaces, slashes, single/double quotation marks, Unicode characters, and should always be lowercase.
Tags should preferably include alternate service names to make searching easier (for e.g., if an Amazon presence had included AWS support, it would have its tags like amazon-web-services and aws)

`category`

The category must be one of the following listed on the documentation.
The presence must use a category that matches the content of the website. (for e.g., don't use anime when the website isn't related to anime).

**`regExp`
`iFrameRegExp`**

Regular expressions must be valid. Please test your expressions with the tools listed on the documentation.

`readLogs`

Must be boolean value (e.g. true or false).
Enables logs for your presence.

`warning`

Enables warning icon for prompting user that this presence needs more steps than only adding presence.
Example of presence using this metadata variable is VLC.

`settings`

If you decide to make a format string (for e.g., %song% by %artist%), you must have the variables surrounded by a percent sign on either side. Variables like %var, var%, or %%var%% and anything in between are not permitted for the sake of standardization.
The name of the settings must not be in all capital letters. For example, names such as SHOW BROWSING STATUS will not be permitted; however, names such as Show Browsing Status or Show browsing status are permitted.
If you are using the multiLanguage option it can have the following types:
- Boolean type which will only enable strings from general.json from the Localization repo or from the presence file (e.g. when the name of the presence is YouTube, the extension will get strings from youtube.json too.)
- String type (e.g. youtube) which will specify the name of the files that you want to get strings from.
- Array type (e.g. ["youtube", "discord"]) which will specify the name of the files that you want to get strings from.

presence.ts

The code you write must be well-written and must be readable and all strings must be grammatically correct (grammar errors on websites can be ignored).

Each presence follows a strict linting ruleset which will be checked during the review process. A couple of recommendations can be seen below. TypeScript Plugin Recommendations for Strict Type Checking. ESlint Recommendations. Prettier.

Here is a list of rules you must follow when writing your presence.ts file:

Preferably declare a new instance of the Presence class before any other variable to avoid rare issues that may occur.
Always use document.location to get current location information rather than window.location or location.
All assets must have a resolution of 512x512 pixels. You can upsize it using a tool like waifu2x.
Never use custom functions when native variants are available; this makes sure fixes on the extension level also apply to your presences. You're free to use whatever you need if you do not find them listed in the docs.
It is forbidden to code presences for a site without adding support to its primary language (for e.g., a YouTube presence coded with support only for Portueguese and Japanese, but not English itself.)
The smallImageKey and smallImageText fields are intended to provide additional/secondary context (such as playing/paused for video sites, browsing for regular sites, and other cases) not to promote Discord profiles or anything unrelated to PreMiD.
When accessing cookies for stored data, please prefix the key with PMD_.
You may only make HTTP/HTTPS requests to premid.app or the presence website API. If you are using external domains, you will be required to explain why it is necessary. The only allowed API to make requests is the Fetch API.
Do not set fields in the presenceData object to undefined or other null-like values after it has been declared, use the delete keyword instead. (for e.g., use delete data.startTimestamp instead of data.startTimestamp = undefined)
You are not allowed to write presences that change the functionality of a given website. This includes the addition, deletion, or modification of DOM elements.
Services which contain some explicit content should avoid displaying it in the presence. For example, use generic text when explicit warnings or tags are available.
If the service is very complex, consider separating the code into multiple files.
Presences that use buttons should follow extra requirements:
- Redirects to main page are prohibited.
- Promoting websites by them is prohibited.
- They can't display information you couldn't fit in other fields.
- Redirecting directly to audio/video stream is prohibited.

Modification

You must change the version in the metadata to be a higher value from the previous version when making changes to either the presence.ts, iframe.ts or metadata.json.

In some situations, presences may behave unexpectedly or could use some minor changes to improve their functionality. Here is a list of rules that you must follow while modifiying presences.

If you make modifications to a presence and change at least a quarter of the presence's codebase, you are allowed to add yourself as a contributor. Contact a reviewer for more information about this subject.
Anyone may create PRs to fix bugs. Do not change images if they are not outdated and are in specifications.

Verification

All code contributed to the store will be licensed under the Mozilla Public License 2.0.

If you need to contact someone, please use our official Discord server. All reviewers will have the Reviewer role on their profile.

Please keep in mind that the reviewers work voluntarily and manage other repositories in addition to this one, your pull request may not get reviewed until hours or even days after it has been created.

Always have an up-to-date fork before creating your pull request. This will help limit false positives from the checks.

The most important process of presence development is getting your presence on the store. This is done by making a pull request on GitHub on the PreMiD/Presences repository. Our reviewers will confirm that your presence is up to standards and will push it onto the store.

Presence Reviewers

`Restrictions`

Repetitive offenses such as breaking guidelines, spamming pull requests, threats, or innapropriate behavior will get you banned from creating presences.

In this scenario, the following changes will occur:

Presences under your management will be transferred to the PreMiD bot or another user (reviewer decision). The application id for each presence will be recreated under the new owner's name.
All of your issues and pull requests (presence creation, presence contribution, etc) created following the ban will be prompty closed.
Tickets created under your name regarding presence development will be deleted.

`Reviewing`

A few things you should know after opening a pull request:

It takes 2 reviewers to merge a pull request.
If a pull request is inactive for a period of 7 days, it will be promptly closed.
All checks must be passed in order to merge.
⚠️ You must provide new, unaltered screenshots (taken by you) showing a side-by-side comparison of your profile and the website to prove that your presence works. You are allowed to stitch screenshots together for viewing pleasure This applies for both creation and modification.
⚠️ You are also required to include screenshots of the presence settings in the extension if supplied. An example can be seen here.

`Checks`

Currently, a presence goes through 3 separate stages of checks. All of these checks help the reviewers determine whether your presence is suitable for deployment.

DeepScan is a bot that checks for code quality. If you ever receive errors for new issues, you are required to fix them. Warning: DeepScan doesn't always give you errors. Please look at CodeFactor warnings instead.
Compile and Lint checks for code quality. If you ever receive errors for new issues, you are required to fix them.
Presence Validator will scan your metadata.json file for any errors (for e.g., missing fields, invalid value types, etc.). If you ever see any new issues, you are also required to fix those. Adding a schema field to your metadata.json file will allow your text editor (if supported) to show you these errors during development.

`Additional Rules`

Always make sure to start your presence in the most appropriate folder, if its name starts with any Latin letter then it must be under its alphabetical match (for e.g., D/dアニメストア or G/Google). Any other Unicode/non-Latin characters must be under the # folder (for e.g., #/巴哈姆特) and numbers under the 0-9 folder (for e.g., 0-9/4anime).

After meeting all of the guidelines with the proper reviews and checks, your presence will be merged with the store.

Suggestions

If you have some suggestions about our guidelines, you should contact us @ PreMiD's Discord server and we will check them!

Contributions

Revision 3 of the guidelines was written and was contributed to by the following individuals:

Revision 2 of the guidelines was written and was contributed to by the following individuals:

Revision 1 was maintained by the following individuals:

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CONTRIBUTING.md

CONTRIBUTING.md

Presence Guidelines

Revision 3.2

Guidelines

Creation

metadata.json

`$schema`

`author`

**`*contributors`**

`service`

**`*altnames`**

`description`

`url`

`matches` or `iFrameMatches`

`version`

`logo`

`thumbnail`

`color`

`tags`

`category`

**`regExp`
`iFrameRegExp`**

`readLogs`

`warning`

`settings`

presence.ts

Modification

Verification

Presence Reviewers

`Restrictions`

`Reviewing`

`Checks`

`Additional Rules`

Suggestions

Contributions

Files

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Presence Guidelines

Revision 3.2

Guidelines

Creation

metadata.json

$schema

author

*contributors

service

*altnames

description

url

matches or iFrameMatches

version

logo

thumbnail

color

tags

category

*regExp *iFrameRegExp

readLogs

warning

settings

presence.ts

Modification

Verification

Presence Reviewers

Restrictions

Reviewing

Checks

Additional Rules

Suggestions

Contributions

`$schema`

`author`

**`*contributors`**

`service`

**`*altnames`**

`description`

`url`

`matches` or `iFrameMatches`

`version`

`logo`

`thumbnail`

`color`

`tags`

`category`

**`regExp`
`iFrameRegExp`**

`readLogs`

`warning`

`settings`

`Restrictions`

`Reviewing`

`Checks`

`Additional Rules`