Description:

Related issue (if applicable): #1009

This is very much a work in progress

Account Setup

Vapid/WebPush requires a subscriptions.json file that identifies all of the users you wish to notify and a private_key.pem

Syntax:

• vapid://subscription_id/
• vapid://subscription_id/target
• vapid://subscription_id/target1/target2/targetN/

Parameter Breakdown

Mode Table:
You will see a lot of duplication (many modes pointing to the same location). The idea is if the end points change, we will update it inside Apprise so your code/URL will not have to change later.

subscriptions.json Setup

In order to use Vapid, you must have a subscriptions.json file that it can point to. The Vapid plugin supports the 2 following formats:

1. standalone; in the below example, the target would be abc123

   {
       "endpoint": "https://fcm.googleapis.com/fcm/send/abc123",
       "keys": {
           "p256dh": "BNcW4oA7zq5H9TKIrA3XfKclN2fX9P_7NR...",
           "auth": "k9Xzm43nBGo=",
       }
   }

2. multiple target support; in the below example, 2 targets are created called name1 and name2

   {
       "name1": {
           "endpoint": "https://fcm.googleapis.com/fcm/send/...",
           "keys": {
               "p256dh": "BNcW4oA7zq5H9TKIrA3XfKclN2fX9P_7NR...",
               "auth": "k9Xzm43nBGo=",
           }
       },
       "name2": {
           "endpoint": "https://fcm.googleapis.com/fcm/send/...",
           "keys": {
               "p256dh": "BNcW4oA7zq5H9TKIrA3XfKclN2fX9P_7NR...",
               "auth": "k9Xzm43nBGo=",
           }
       }

It is though targets that you notify one or more endpoints. If you're using persistent storage with Apprise, you can simply manage your subscription.json file located here and your URL can stay clean. Alternatively, you can specify ?subfile= on your URL and point it to a subscription file you wish to load. The location can be local to the filesystem as well as a remote location (such as subfile=https://user:pass@myhost/special/location/subscription.json

If no target is specified on your URL, then a target that matches your own subscriberid is looked up in the subcriptions.json file

Private Key (PEM) Setup

Similar to the subscription.json, you need to point to a private_key.pem file. If you are using Apprise persisent storage, you can place the file here. Alternatively you can specify ?keyfile= on the URL and point it to a local or remote file you wish to use.

Persistent Storage Tips

The following command will list all of the persistent storage locations associated with your configuration:

apprise storage list

Simply locate the ID associated with the Vapid account you wish to update; consider that the directory ID's can be found as:

1. Microsoft Windows: %APPDATA%/Apprise/cache
2. Linux: ~/.local/share/apprise/cache

For more details on this; see here.

Apprise URL Construction

This is a more complicated plugin to work with since it requires a binary PEM private key and a subscription.json file as well. It would be advised to use a Apprise Configuration YAML file that looks like this:

urls:
   - vapid://:
       mode: apple
       keyfile: /path/to/keyfile
       subfile: /path/to/subscription.json

Remember that both the keyfile and subfile can be URLs as well (even ones protected behind user/passwords such as:

urls:
   - vapid://:
       mode: apple
       keyfile: https://user:pass123@example.com/private_key.pem
       subfile: https://user:pass123@example.com/subscriptions.json

If you do not define a keyfile and/or a subfile, the rules above apply as documented above and default ones are looked upon in your persistent storage directory.

New Service Completion Status

• apprise/plugins/vapid
• KEYWORDS
  • add new service into this file (alphabetically).
• README.md
  • add entry for new service to table (as a quick reference)
• packaging/redhat/python-apprise.spec
  • add new service into the %global common_description

Checklist

• The code change is tested and works locally.
• There is no commented out code in this PR.
• No lint errors (use flake8)
• 100% test coverage

Testing

Anyone can help test this source code as follows:

# Create a virtual environment to work in as follows:
python3 -m venv apprise

# Change into our new directory
cd apprise

# Activate our virtual environment
source bin/activate

# Install the branch
pip install git+https://github.com/caronc/apprise.git@1009-webpush-support

# Test out the changes with the following command:
apprise -t "Test Title" -b "Test Message" \
  "vapid://subscriber_id"