Bukkit

AlertAPI - Developer Portal

Prerequisites

• The latest version of AlertAPI.
• You must add the jar file to your plugin's build path
• Add "depend: [AlertAPI]" to your plugin.yml file, if AlertAPI is required for your plugin to run or "softdepend: [AlertAPI]" to your plugin.yml file, if AlertAPI is optional for your plugin to run

Optional - Attach javadocs to AlertAPI referenced library:

• In Eclipse: go to AlertAPI.jar properties, click on javadoc location and enter the url: http://mmonkey.github.io/jd/AlertAPI/

Understanding AlertAPI

AlertAPI was written to be a secure way of sending email and text messages, that is easy to use, and simple to integrate into other plugins. The API uses a server-wide address book to store all of the registered users contact information in. The information is encrypted, and protected keeping it safe, and inaccessable. AlertAPI has all the necessary commands and methods built-in to handle all adding, editing and removing player information in the address book.

Note: Only players that are in the address book, may send and receive messages, this is all handled internally through AlertAPI.

Using the API

Methods

Checking the Address Book:

First and foremost you need to check to see if the player that you want to send a message to is registered in the address book:

  if(AlertAPI.isInAddressBook(player.getName())) {
    //Your code here
  }

Checking to see if a player can send messages:

  if(AlertAPI.canSend(player.getName())) {
    //Your code here
  }

or

  if(AlertAPI.canSendToAll(player.getName())) {
    //Your code here
  }

Sending Messages

There are many ways of sending messages:

Send alert message to a player:

SendResult result = AlertAPI.send(String to, String Message);

Send alert message to a player, from a player:

SendResult result = AlertAPI.send(String from, String to, String Message);

Send alert message to a list of players:

SendResult result = AlertAPI.send(ArrayList<String> to, String Message);

Send alert message to a list of players, from a player:

SendResult result = AlertAPI.send(String from, ArrayList<String> to, String Message);

Send alert message to all players:

SendResult result = AlertAPI.sendAll(String Message);

Send alert message to all players, from a player:

SendResult result = AlertAPI.sendAll(String from, String Message);

Getting Send Result

AlertAPI will return true or false, and a message with information about the transmission, should something go wrong.

  if(result.isSent()) {
    //Congrats, your message was sent!
  } else {
    //There was an error.
    log.info(result.toString());
  }

All the possible SendResults:

SUCCESS (true)
ALERT_SEND_EVENT_WAS_CANCELLED (false)
UNABLE_TO_RETRIEVE_RECIPIENT (false)
UNABLE_TO_RETRIEVE_SENDER (false)
NO_CONTACTS_FOUND (false)
RECIPIENT_NOT_IN_ADDRESS_BOOK (false)
RECIPIENT_HAS_NOT_ACCEPTED_TERMS (false)
RECIPIENT_ONLINE (false)
SENDER_NOT_IN_ADDRESS_BOOK (false)
SENDER_NOT_ALLOWED_TO_SEND_MESSAGES (false)
SENDER_NOT_ALLOWED_TO_SEND_MESSAGES_TO_ALL (false)
SENDER_HAS_NOT_ACCEPTED_TERMS (false)
SENDER_IS_ON_RECIPIENTS_IGNORE_LIST (false)
MESSAGIN_EXCEPTION_CHECK_STACK_TRACE (false)

Events:

Events from AlertAPI are handled just like any other event in Bukkit. You create an event-handler which accepts the proper event as an input. There are three events thrown by AlertAPI: ContactRegisterEvent, ContactUnregisterEvent and AlertSentEvent.

ContactRegisterEvent:

This event is triggered when a player registers in the address book as a new contact. The only variable passed to other plugins is: event.getPlayer() - returns the Player who registered.

ContactUnregisterEvent:

This event is triggered when a player unregisters from the address book. The only variable passed to other plugins is: event.getPlayer() - return the Player who unregistered.

AlertSentEvent:

This event is triggered whenever a message is sent. This event is cancelable. The variables passed by this event are: event.getSender() - returns the player who sent the message as a String. event.getRecipients() - returns an ArrayList<String> of the message recipients. event.isCancelled() - true if cancelled, false if not. You can cancel this event by using: event.setCancelled(true);

Documentation:

• JavaDocs

Examples:

• FriendsOnline - github

Having Issues?

Submit a ticket here.