SubNotMENU

Integrating the service

Creating the button

You can create a button directly from the dashboard after registration.

Provide a button name, and it will generate a button ID and Authorization key that can be used to complete the rest of the setup.

The button ID is public, and will be used on the subscribe button to identify your button, while the Authorization key is a secret, which should not be shared, as it can manage you button and send notifications.

Basic setup

The most basic integration of the button is really simple. Just add the following code to your website, and it starts working to subscribe via Telegram messages, if you have that channel enabled.

<script src="https://subnot.mvplog.com/button.js" data-button-id="<your-button-id>" async></script>

To get Browser Notifications to work it is required that you serve the service worker from your own website. This is a limitation of Service Workers registration, which do not allow cross-origin registration.

The simplest way around this is to serve service-worker.js with the following contents, from your root directory.

importScripts('https://subnot.mvplog.com/service-worker.js');

The path to the service worker can be customized via attribute, but defaults to 'service-worker.js' in your root directory.

<script ... data-worker="/scripts/my-custom-worker.js"></script>

Pushing Notifications

To push a message to all channels it only requires a single POST request to https://subnot.mvplog.com/api/post. The parameters are shown in the curl request below.

curl -d '{"button_id":"<button id>", "message":"<message>"}' \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <authorization key>" \
     -X POST https://subnot.mvplog.com/api/post

The authorization for the button works with the Authorization header with a bearer token provided in the dashboard.

This is the most basic functionality, allowing to easily set up notifications on your system.

Styling and customizing the button

Right now it is possible only to customize the text of the button. This can be achieved as below.

<script ... data-button-text="Hello, subscribe"></script>

More customization options will likely be possible in the future.

Advanced use - Filtering options

Sometimes people want more control over what they subscribe, and while this can be achieved with multiple buttons, it is also possible to specify filters to facilitate a better experience.

The filter categories and values can be set through the dashboard (and via API, in the future) to allow finer control over the subscriptions.

For these cases buttons can be declared filterable, which allows the subscriber to select which category values to subscribe.

<script ... data-filterable="true"></script>

If you want to programmatically set the filters for the button you can do so by setting the data-filter attribute.

<script ... data-filter='{"<category key>": "<value key>"}'></script>

The filter can be set even if the button is not set as filterable. It will act as default options in the case it is filterable.

Multiple categories can be specified, with only one value each. It somehow limits the categories, but it is an initial implementation of filters, with more options coming in the future.

If you are using buttons with filters, the filter should be specified. It functions as a restriction basis, if you are subscribed to a certain category value, you only receive from that category value, but if the subscriber doesn't have that restriction they will receive all notifications.

curl -d '{"button_id":"<button id>", "message":"<message>", "filter": {"<category-key>": "<value key>"}}' \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <api key>" \
     -X POST https://subnot.mvplog.com/api/post