Plugins

A plugin adds a feature to your Broadcast server. You write it in JavaScript, and Broadcast runs it for you.

Here are some things a plugin can do:

• Post a message to Slack when someone subscribes.
• Add a tag to each new subscriber.
• Add a poll to an email, and count the answers.
• Run a referral program.
• Add a step such as “Post to Slack” to your sequences.
• Show a report page inside Broadcast.

You do not need to know Ruby or how Broadcast works inside. If you can write a JavaScript function, you can write a plugin. This section assumes you have never written a plugin, used a sandbox or read a manifest. It explains each of those words when it needs them.

The four words you need

Plugin. A folder of files, packed into one file that ends in .broadcast-plugin.

Manifest. A file named manifest.json. It is the label on the box. It says what the plugin is called, what it wants to listen to and what it wants to be allowed to do. Broadcast reads it before any code runs.

Hook. A place where Broadcast calls your code. For example, the onEvent hook runs when something happens, such as a new signup. You write a function, and Broadcast calls it at the right time.

Sandbox. A closed room for your code. Your plugin runs in its own process, away from Broadcast. It cannot see the database, the disk or the server settings. It can only talk to Broadcast through one object, named ctx. Everything it asks for is checked.

How the pieces fit

This picture shows what happens when a person subscribes and a plugin adds a tag:

 Your Broadcast server
+------------------------------------------------------------+
|                                                            |
|  Broadcast app                    Plugin sandbox           |
|  +----------------------+         +---------------------+  |
|  | 1. Ada subscribes.   |         |                     |  |
|  |                      | event   | 2. Your onEvent     |  |
|  |    Is a plugin on    | ------> |    function runs.   |  |
|  |    in this channel?  |         |                     |  |
|  |                      |  ctx    | 3. It asks: add the |  |
|  | 4. Is this plugin    | <------ |    tag "new" to     |  |
|  |    allowed to do     |         |    subscriber 12.   |  |
|  |    that? Yes.        |         |                     |  |
|  |    Add the tag.      | ------> | 5. It gets the      |  |
|  |                      | answer  |    answer.          |  |
|  +----------+-----------+         +----------+----------+  |
|             |                                |             |
|        Your database                   Network gate        |
|      (no plugin can reach it)     (declared hosts only)    |
+------------------------------------------------------------+

There are three things to see here:

1. Broadcast calls your code. Your code does not run all the time.
2. Your code never touches the database. It asks through ctx, and Broadcast does the work.
3. Your code can reach the internet only through a gate. The gate lets it reach only the hosts that the manifest names.

What a plugin can do

What a plugin can never do

No permission unlocks these things. They are not possible for any plugin, and this list is the same for code you trust and code you do not:

• Run SQL or read the database.
• Read files, or read server settings and environment variables.
• Start other programs.
• Resubscribe a person, or remove a suppression.
• Skip double opt-in.
• Change who an email goes to, or remove the unsubscribe link.
• Change a topic, because a topic is a subscriber’s consent.
• Load more code while it runs. There is no eval, and no import from the network.

Who does what

A plugin passes through two kinds of people, and they can be the same person.

The author writes the code. If you read this section, that is you.

The admin decides what runs. An admin is a user with sudo access. The admin reads the permissions and the code, clicks Deploy, and then turns the plugin on in each channel that needs it.

Nothing runs until both of those steps are done. Plugins are installed once on the server, and they are turned on for each channel. So the same plugin can be on in one channel and off in another, with different settings.

Where to go next

1. Your First Plugin: build a plugin from an empty folder.
2. Plugin Core Concepts: learn the manifest, hooks, ctx, permissions, settings and storage.
3. Plugin Hooks: pick the hook for your idea.
4. Build a Poll and Build a Referral Program: see how two complete plugins are built.
5. Plugin Reference: look up every field, function, permission and limit.