Setup and installation
To include Plugserv on your site, you'll need to:
The snippet is configured using a plugserv_config object on the window.
The object must include:
elementId: an id of a DOM element. Its innerHTML will be replaced by your plug html.endpoint: the url to retrieve your plugs from. This will usually point to plugserv.com and provide your id, but it may be changed if you are self-hosting.
The snippet source is available here, if you would like to inspect it. The security section has recommendations on including it safely, especially if you're adding it to a site with user data.
Plug serving
If you have multiple plugs, properties rotate between them every 24 hours. Different properties are not guaranteed to show the same plug at the same time. Adding and removing plugs may also affect which is currently being served.
To avoid sites plugging themselves, plugs are not served to origins with the exact same domain, including any subdomains.
This means that a plug with domain example.com could be served to a user on www.example.com
(this may be addressed in the future if it's deemed problematic).
Metrics and Google Analytics export
To limit database requirements, Plugserv does not record the number of times a plug is served ("impressions") or clicked. If you'd like to track this information you can configure Plugserv to export events to Google Analytics. To do this:
- create a free Google Analytics account if you do not already have one
- create a new account and property for your Plugserv data
- disable "Exclude all hits from known bots and spiders" for the view you plan to use (more on this below)
- enter the tracking code from your new property in your Plugserv user settings
Plugserv will start sending events immediately; there is no update required to your snippet. To stop sending events, update your Plugserv user settings to use an empty tracking code.
Events have the following schema:
- category: 'click' or 'impression'
- action: the domain of the plug
- label: the domain of the site the plug was served to
Here are some more details on how events are sent:
- events are sent from Plugserv's backend via the Measurement Protocol
- bot/spider filtering must be disabled since there's no way to authenticate Plugserv's events; factors like bots previously run from my provider's IP may otherwise result in missing data. Bots should not be a concern since your tracking code is never shared publicly.
- impressions are sent when a plug is served, regardless of whether it was actually seen by someone
- clicks are sent any time the plug element is clicked (ie, not just links inside it) and the user's browser supports the Beacon API (to avoid navigation latency)
- users with the Google Analytics Opt-Out extension installed will never have their clicks tracked
Security
Plugserv can include arbitrary html in your site, which is a security risk. While the same-origin policy provides some basic protections, you can further limit your exposure in a few ways.
First, keep the provided SRI hash in the snippet. This ensures that if the Plugserv client code were to change unexpectedly, browsers will refuse to run it.
Second, consider setting an appropriate CSP policy on any site running Plugserv.
For example, a policy like script-src 'sha256-...' www.plugserv.com; (with the hash set for your window.plugserv_config inline code) will prevent malicious plugs from executing code.
Alternatively, you can self-host a copy of the configuration and client code, then use script-src 'self';.
Either of these will help protect your sites if Plugserv or your Plugserv account were compromised.