The basics are really easy, all you need is to create a new class that implements the net.dandielo.stats.api.Listener or net.dandielo.stats.api.Updater interface and add methods with the @Stat annotation. It is similar to the bukkit event Listener and works quite in the same way :)

I will also use here some PHP scripts to show you how to trigger updaters and listeners, the usage and PHP API can be found PHP API.

Listeners are used to return data requested from the webpage. So if you want to show on your website any data from your plugin you would use a Listener to listen to a webpage request for that data. They can be also used to update data on the server, it only depends on the method you are creating, but remember you need always to send data back to the webiste.

Listeners are for to way Server <-> Website communication

I will show you a simple example

class MyListener implements net.dandielo.stats.api.Listener
{
    @Stat(name = "testStat")
    public int anyNumber()
    {
        return 34;
    }
}

The above example would return the number 34 as a String to the website on the following request

//returns "34"
Stat::get("testStat");

Updater are a way to control plugin or server behavior/settings using your website. You can execute commands, send messages, or even when you want edit the players inventory. Updaters do not return any data to the website so they are only for one way Website -> Server communication.

class MyUpdater implements net.dandielo.stats.api.Updater
{
    @Stat(name = "testMessage")
    public int broadcast(String value)
    {
        Bukkit.broadcastMessage(value);
    }
}

The example above would send a broadcast message on the following website script

//send a broadcast message
Stat::update("testMessage", "MyMessage");

You are not forced to use always one word for a stat you can create a path to it, and also use arguments in that path, that you can later use for different things :)

We will use our old listener and change it a bit to use paths and a simple argument

class MyListener implements net.dandielo.stats.api.Listener
{
    @Stat(name = "testStat/{multiplier}")
    public int anyNumber(String multiplier)
    {
        return 34 * Double.parseDouble(multiplier);
    }
}

Now when we want to get that stat we would use the following script

//get the number multiplied by 3.00
Stat::get("testStat/3.00");

This would return the value 102.00

We can use also the @Stat annotation on the Updater or Listener class, the path of that stat will be used as a prefix to all method stat paths.

Example below:

@Stat(name="{player}")
class MyUpdater implements net.dandielo.stats.api.Updater
{
    @Stat(name = "message") 
    //this will be evaluated to the following stat path "{player}/message/{value}"
    public int broadcast(String player, String message)
    {
        Bukkit.getPlayer(player).sendMessage(message);
    }

    @Stat(name = "teleport/{x}/{y}/{z}")
    //this will be evaluated to the following stat path "{player}/teleport/{x}/{y}/{z}/{world}"
    public int teleport(String player, String x, String y, String z, String world)
    {
        Bukkit.getPlayer(player).teleport(... etc);
    }
}

The following updated could be used to teleport players with the following script.

//teleport the player to... 
Stat::update("playerName/teleport/112/67/23", "world");

or send a message to a player

//send a message to a player
Stat::update("playerName/message", "A message to a player");

You just need to remember that an updater method needs always to have one String argument more that all arguments in the path, as because it has by default one argument.

You can without problems use both interfaces on a class then each method will be added as a Listener method and as a Updater method, but only one will work for each depending on the Argument count. To not register each method in both places you can precise for what is the method used.

The @Stat annotation has a second argument named requestType you can set it to three values: AUTO, UPDATE, GET. The AUTO value us the default one and registers a method depending on the class interfaces, the UPDATE value registers only when the class has the Updater Interface and as a updater method, and the GET value does the same just for Listeners.

The JSonRequest class is used to make a JSon response, those responses are used to parse large amounts of data to not send too many requests to the plugin from the website. JSonRequests are only used for Listeners as because Updaters do not return any data.

On the PHP side API a JSonRequest can be easily changed into class that will use the JSon base keys as static methods or fields on class objects.

class MyListener implements net.dandielo.stats.api.Listener
{
    @Stat(name = "TestClass")
    public int anyRequest()
    {
        JSonRequest request = new JSonRequest();
        
        request.object().set("key", "a Value").endobject();

        return request;
    }
}

This is a very simple example of a JSonRequest and on the PHP side you could do sth like this:

//create a class that responds to the stat path (better description in the PHP API)
class TestClass extends StatClass { }

//show the value of the key
echo TestClass::key();