Skip to content

Latest commit

 

History

History
155 lines (111 loc) · 6.11 KB

metadata.md

File metadata and controls

155 lines (111 loc) · 6.11 KB
Raw
description
List your app in AppCenter and make it accessible from the Applications menu and Dock.

Metadata

Every app comes with two metadata files that we can generate using an online tool. Open AppStream Metainfo Creator and fill out the form with your app's info:

{% embed url="https://www.freedesktop.org/software/appstream/metainfocreator/#/guiapp" %}

{% hint style="info" %} When you get the section titled "Launchables", make sure to select "Generate a .desktop file for me". {% endhint %}

Don't worry about generating Meson snippets, as we'll cover that in the next section. After you select "Generate", you should have two resulting files that you can copy.

MetaInfo

First is a MetaInfo file. This file contains all the information needed to list your app in AppCenter. It should look something like this:

<?xml version="1.0" encoding="UTF-8"?>
<component type="desktop-application">
  <id>io.github.myteam.myapp</id>

  <name>My App</name>
  <summary>Proves that we can use Vala and Gtk</summary>

  <metadata_license>CC-BY-4.0</metadata_license>
  <project_license>GPL-3.0-or-later</project_license>

  <description>
    <p>
      A quick summary of your app's main selling points and features. Just a couple sentences per paragraph is best
    </p>
  </description>

  <launchable type="desktop-id">io.github.myteam.myapp.desktop</launchable>
</component>

In your project's root, create a new folder called "data", and save your MetaInfo to a new file called "hello-again.metainfo.xml".

{% hint style="info" %} Below are some of the most important fields for publishing in AppCenter, but there are even more optional fields that you can read about {% endhint %}

Screenshots

For the purposes of this tutorial, screenshots are optional, but they are required for publishing in AppCenter. Screenshots should only show your app on a transparent background and not contain any additional text or illustrations. You can use the caption tag to provide translatable and accessible descriptions of your screenshots.

<screenshots>
  <screenshot type="default">
    <caption>The most important feature of my app</caption>
    <image>https://raw.githubusercontent.com/myteam/myapp/1.0.0/data/screenshot.png</image>
  </screenshot>
</screenshots>

{% hint style="info" %} You can use the built-in Screenshot app on elementary OS with the "grab the current window" option or secondary-click on your app's title area and select "Take Screenshot" to get transparent window-only screenshots of your app {% endhint %}

Content Warnings

We use the Open Age Rating Service (OARS) standard to describe sensitive content that may be present in your app so that people using it can be informed and actively consent to seeing that content. OARS data is required and can be generated by taking a short survey:

{% embed url="https://hughsie.github.io/oars/generate.html" %}

Branding

You can also specify a brand color for your app by adding the branding tag inside the component tag. Colors must be in hexadecimal, starting with #. The background will automatically be given a slight gradient in your app's banner.

<branding>
  <color type="primary">#f37329</color>
</branding>

Monetization

If you want to monetize your app, you will need to add two keys inside a custom tag inside the component tag. Suggested prices should be in whole USD. You also must include your app's AppCenter Stripe key. This is a unique public key for each app and is not the same as your Stripe account's regular public key. You can connect your app to Stripe and receive a new key on the AppCenter Dashboard.

<custom>
  <value key="x-appcenter-suggested-price">5</value>
  <value key="x-appcenter-stripe">pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</value>
</custom>

{% hint style="info" %} Remember that AppCenter is a pay-what-you-want store. A suggested price is not a price floor. Users will still be able to choose any price they like, including 0. {% endhint %}

Releases

Your app must have a release tag for every version you wish to publish in AppCenter, including the initial release.

<releases>
  <release version="1.0.0" date="2022-09-08">
    <description>
      <p>Initial release, includes features such as:</p>
      <ul>
        <li>Application can be launched</li>
      </ul>
    </description>
  </release>
</releases>

{% hint style="info" %} For more details on available features and advice on writing engaging release notes see Publishing Updates. {% endhint %}

Desktop Entry

This file contains all the information needed to display your app in the Applications Menu and in the Dock. The one generated from AppStream Metainfo Creator looks something like this:

[Desktop Entry]
Version=1.0
Type=Application

Name=My App
Comment=Proves that we can use Vala and Gtk
Categories=Development;Education;

Icon=io.github.myteam.myapp
Exec=io.github.myteam.myapp
Terminal=false

Copy the contents of your Desktop Entry and save it to the data folder you created earlier. Name this new file "hello-again.desktop".

{% hint style="info" %} For more info about crafting .desktop files, check out this HIG entry. {% endhint %}

Mark Your Progress

Each time we add a new file or make a significant change it's a good idea to commit a new revision and push to GitHub. Keep in mind that this acts as a backup system as well; when we push our work to GitHub, we know it's safe and we can always revert to a known good revision if we mess up later.

Add all of these files to git and commit a revision:

git add data/
git commit -am "Add Metadata files"
git push

Now that we've got all these swanky files laying around, we need a way to tell the computer what to do with them. Ready for the next chapter? Let's do this!