Distributing Your Plugin

About this guide

Read this guide if

Guide assumptions

This guide assumes that you:

The Marketplace

Piwik's plugin marketplace is the main way to download and install third-party plugins. Every instance of Piwik running version 2.0 or greater is able to directly download and install plugins from the marketplace. Making your plugin available on the marketplace is the best way for you to get your plugin out into the hands of Piwik users.

It's also a great way for you to:

Adding your plugin to the marketplace

Getting your completed plugin on the marketplace takes a couple steps, all listed below.

Make sure your plugin has a unique name

Every plugin on the marketplace has a unique name. If your plugin's name is already taken, you won't be able to put it on the marketplace.

Make sure the name you chose is currently available, and if it's not, pick another one.

Getting your plugin ready to publish

Two files are required to be present in your plugin before you can publish: the README.md file and the plugin.json file.

README.md file

The README.md file should contain a description of your plugin and some documentation. Sections in this file are used to build the plugin page on the Marketplace.

Let's take a look at the CustomAlerts plugin README file. This file is written in Markdown format. It includes the following sections: Description, FAQ, Changelog and Support. The sections in your README are then directly displayed on your plugin page in the Marketplace! Checkout the CustomAlerts plugin page created from the README file.


To make your plugin shine on the Piwik marketplace: include screenshots in your Git repository!

Prepare a few screenshots of your plugin in action. Place them in a directory screenshots/ in your plugin folder. Give them a descriptive name: filenames will be used as the legend below each screenshot.

See the result for the CustomAlerts plugin screenshots (click on the Screenshots link). These screenshots are stored in git: CustomAlerts/screenshots.

plugin.json file

The plugin.json file must contain the following information:

The following fields are not required for publishing a plugin, but you may want to add them:

Put your plugin on Github

The marketplace uses Github webhooks to learn about your plugin and serve it to Piwik users that want it. This means you don't manually upload any files to the marketplace. Instead, you put your code into a Github repository and let the marketplace know about it.

Creating and initializing a git repo on Github is out of scope for this guide. If you need to learn how to create a Github repo, read this article.

Activating the Piwik Plugins webhook

Once you have a Github repo for your plugin, you need to let the marketplace know about it. This is done by activating the Piwik Plugins webhook.

To activate this webhook, follow these steps:

  1. Go to your plugin's Github repo in a browser.
  2. Click on Service Hooks.
  3. Scroll down until you see the Piwik Plugins option and then click on it.
  4. Click the Active checkbox.
  5. Click the Update Settings button.

The marketplace will now be notified every time you push a commit or a tag to your repository.

Publish the first version of your plugin

Now that the marketplace will know of any changes to your plugin, you can publish the first version. First, make sure the version in your plugin.json file is 0.1.0. Then, we'll run two git commands to publish a version of your plugin:

$ git tag 0.1.0
$ git push origin --tags

Everytime you push a new tag to your Github repository, a new version of your plugin will become available in the marketplace. The name of the tag doesn't matter, the marketplace will always use the version in your plugin.json file.

Assuming all goes well, your plugin should now be visible on the marketplace!


If your plugin is not on the marketplace, then there was an error validating your plugin.json file and you will receive an email describing what the problem was.

Here are some common errors:

If you still encounter trouble while publishing your plugin, please join the IRC channel #piwik on freenode. If you can't find anyone in the IRC channel, please ask for help on the forums.

Rules for Plugins

There are some restrictions regarding what can be published on the marketplace. Chances are your plugin is fine, but if we find a plugin that violates one of the following rules, it will be immediately removed:

Using the marketplace

Now that you've gotten your plugin on the marketplace, it's time to learn how to use it. This section will explain how you can the most out of the marketplace.

Your plugin's page

Every plugin gets its own page on the marketplace. On the left is the name and a short description of your plugin followed by a set of tabs.

The content of the tabs is determined by the headings in your README.md file. See this README.md for an example.

On the right side is the download link, information about your plugin and some relevant links.

Our plans for the marketplace

Like Piwik, the marketplace is a constant work in progress! We will be improving and changing it often to make it easier for you to find users for your plugin.

Here are the things we are currently working on: