Giter VIP home page Giter VIP logo

webpush-java's Introduction

WebPush

A Web Push library for Java 7. Supports payloads and VAPID.

Build Status

Installation

For Gradle, add the following dependency to build.gradle:

compile group: 'nl.martijndwars', name: 'web-push', version: '3.1.1'

For Maven, add the following dependency to pom.xml:

<dependency>
    <groupId>nl.martijndwars</groupId>
    <artifactId>web-push</artifactId>
    <version>3.1.1</version>
</dependency>

This library depends on BouncyCastle, which acts as a Java Cryptography Extension (JCE) provider. BouncyCastle's JARs are signed, and depending on how you package your application, you may need to include BouncyCastle yourself as well.

Building

To build the project yourself, clone this repository and build a run:

./gradlew assemble

To build a fat JAR in build/libs (e.g. to use the CLI):

./gradlew shadowJar

Usage

This library is meant to be used as a Java API. However, it also exposes a CLI to easily generate a VAPID keypair and send a push notification.

CLI

A command-line interface is available to easily generate a keypair (for VAPID) and to try sending a notification.

Usage: <main class> [command] [command options]
  Commands:
    generate-key      Generate a VAPID keypair
      Usage: generate-key

    send-notification      Send a push notification
      Usage: send-notification [options]
        Options:
          --subscription
            A subscription in JSON format.
          --publicKey
            The public key as base64url encoded string.
          --privateKey
            The private key as base64url encoded string.
          --payload
            The message to send.
            Default: Hello, world!
          --ttl
            The number of seconds that the push service should retain the message.

For example, to generate a keypair and output the keys in base64url encoding:

$ java -jar build/libs/web-push-3.1.1-all.jar generate-key
PublicKey:
BGgL7I82SAQM78oyGwaJdrQFhVfZqL9h4Y18BLtgJQ-9pSGXwxqAWQudqmcv41RcWgk1ssUeItv4-8khxbhYveM=

PrivateKey:
ANlfcVVFB4JiMYcI74_h9h04QZ1Ks96AyEa1yrMgDwn3

Use the public key in the call to pushManager.subscribe to get a subscription. Then, to send a notification:

$ java -jar build/libs/web-push-3.1.1-all.jar send-notification \
  --subscription="{'endpoint':'https://fcm.googleapis.com/fcm/send/fH-M3xRoLms:APA91bGB0rkNdxTFsXaJGyyyY7LtEmtHJXy8EqW48zSssxDXXACWCvc9eXjBVU54nrBkARTj4Xvl303PoNc0_rwAMrY9dvkQzi9fkaKLP0vlwoB0uqKygPeL77Y19VYHbj_v_FolUlHa','keys':{'p256dh':'BOtBVgsHVWXzwhDAoFE8P2IgQvabz_tuJjIlNacmS3XZ3fRDuVWiBp8bPR3vHCA78edquclcXXYb-olcj3QtIZ4=','auth':'IOScBh9LW5mJ_K2JwXyNqQ=='}}" \
  --publicKey="BGgL7I82SAQM78oyGwaJdrQFhVfZqL9h4Y18BLtgJQ-9pSGXwxqAWQudqmcv41RcWgk1ssUeItv4-8khxbhYveM=" \
  --privateKey="ANlfcVVFB4JiMYcI74_h9h04QZ1Ks96AyEa1yrMgDwn3" \
  --payload="Hello, lovely world!"

Proxy

If you are behind a corporate proxy you may need to specify the proxy host. This library respects Java's Network Properties, which means that you can pass https.proxyHost and http.proxyPort when invoking java, e.g. java -Dhttp.proxyHost=proxy.corp.com -Dhttp.proxyPort=80 -Dhttps.proxyHost=proxy.corp.com -Dhttps.proxyPort=443 -jar ....

API

First, make sure you add the BouncyCastle security provider:

Security.addProvider(new BouncyCastleProvider());

Then, create an instance of the push service:

PushService pushService = new PushService(...);

Then, create a notification based on the user's subscription:

Notification notification = new Notification(...);

To send a push notification:

pushService.send(notification);

Use sendAsync instead of send to get a Future<HttpResponse>:

pushService.sendAsync(notification);

See doc/UsageExample.md for detailed usage instructions. If you plan on using VAPID, read doc/VAPID.md.

Testing

Our integration tests use Web Push Testing Service (WPTS) to handle the Selenium and browser orchestrating. To install WPTS:

npm install web-push-testing-service -g

Then, to start WPTS:

web-push-testing-service start wpts

Finally, to run all tests:

./gradlew test

FAQ

Why does encryption take multiple seconds?

There may not be enough entropy to generate a random seed, which is common on headless servers. There exist two ways to overcome this problem:

  • Install haveged, a "random number generator that remedies low-entropy conditions in the Linux random device that can occur under some workloads, especially on headless servers." This tutorial explains how to install haveged on different Linux distributions.

  • Change the source for random number generation in the JVM from /dev/random to /dev/urandom. This page offers some explanation.

Credit

To give credit where credit is due, the PushService is mostly a Java port of marco-c/web-push. The HttpEce class is mostly a Java port of martinthomson/encrypted-content-encoding.

Resources

Specifications

Miscellaneous

Related

The web-push-libs organization hosts implementations of the Web Push protocol in several languages:

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.