TsgcWSAPIServer_WebPush

TsgcWSServer_API_WebPush is a component that provides functionality for handling WebPush subscriptions. WebPush is a protocol for delivering real-time notifications to web applications that run in the browser. This component can be used to manage subscriptions and send notifications to subscribed clients. Find below the properties, events, and methods provided by TsgcWSServer_API_WebPush class, along with code examples that demonstrate how to use them.

 

 

Configuration

1. Attach a TsgcWSServer_API_WebPush to a WebSocket server using the Server property.
2. Configure the public and private keys in the WebPush.VAPID property. (Registered users can download an executable that generates the VAPID keys for windows).
3. Requires deploying the OpenSSL 3.0.0 version
4. In the WebPush.Endpoints property you can define your own endpoints to handle the WebPush subscriptions; by default, accessing the "/sgcWebPush.html" endpoint will show a simple webpage that allows you to subscribe to the WebPush notifications.
5. Start the server and access to the endpoint configured to test it.

 

 

Properties

• VAPID: This property is used to set the VAPID (Voluntary Application Server Identification) details for sending WebPush notifications. VAPID is a method for identifying who is sending the push notifications. It is mandatory for all push notifications to have VAPID credentials. The TsgcHTTP_API_WebPush_VAPID_Options object has two properties, PublicKey and PrivateKey, which are used to identify the application server that sends the notification.
  • DER: the public and private keys in DER format
  • PEM: the private key in PEM PKCS8 format.
  • Details: currently only the mailto used for signing the HTTP request.
• ClientOptions: This property is used to set the client-side options for sending WebPush notifications. 
  • Log: enable if you want to save the client HTTP requests to a text log.
  • LogOptions: here you can set the filename.
  • TLSOptions: currently only OpenSSL 3.0.0 supports sending WebPush notifications.
• EndPoints: This property is used to set the endpoints for various WebPush operations, such as subscription, unsubscription, and notification. The TsgcWSWebPushEndpoints_Options object has several properties, including Subscription, Unsubscription, ServiceWorker, Home, WebPush, and VAPIDPublicKey. Each of these properties is an instance of the TsgcWSWebPushEndpoint class, which contains the endpoint URL and other details.
  • Home: the default HTML page.
  • WebPush: the default webpush javascript code.
  • ServiceWorker: the javascript code that handles the push notifications.
  • VAPIDublicKey: the endpoint that returns the public key in DER format.
  • Subscription: the endpoint that notifies the webpush subscriptions.
  • Unsubscription: the endpoint that notifies the webpush unsubscriptions.

 

 

Methods

Find below the most important methods.

 

SendNotification

 

Use this method to send a notification given a subscription object. The subscription object is just a class with the following properties

 

• Endpoint: the url where the client must POST a message.
• PublicKey: the public key used to encrypt the message.
• AuthSecret: the secret used to encrypt the message.
• RawText: contains the full JSON string of the subscription.

 

The message can be a string or an object of TsgcWebPushMessage

 

procedure SendNotification(const aSubscription: TsgcHTTP_API_WebPush_PushSubscription);
var
  oMessage: TsgcWebPushMessage;
begin
  oMessage := TsgcWebPushMessage.Create;
  Try
    oMessage.Title := 'eSeGeCe Notification';
    oMessage.Body := 'Subscription Successfully Registered!!!';
    oMessage.Icon := 'https://www.esegece.com/images/esegece_logo_small.png';
    oMessage.Url := 'https://www.esegece.com';
    sgcWSAPIServer_WebPush1.SendNotification(aSubscription, oMessage);
  Finally
    oMessage.Free;
  End;
end;

 

BroadcastNotification

 

Use this method to send a Notification to all the clients registered using the Subscriptions property (every time a new client is subscribed, it's added to an internal list. And when the client unsubscribed it's deleted). You can Add or Remove subscription manually using the method Subscriptions.AddSubscription and Subscription.RemoveSubscription.

 

procedure BroadcastNotification;
var
  oMessage: TsgcWebPushMessage;
begin
  oMessage := TsgcWebPushMessage.Create;
  Try
    oMessage.Title := 'eSeGeCe Notification';
    oMessage.Body := 'New version released!!!';
    oMessage.Icon := 'https://www.esegece.com/images/esegece_logo_small.png';
    oMessage.Url := 'https://www.esegece.com';
    sgcWSAPIServer_WebPush1.BroadcastNotification(oMessage);
  Finally
    oMessage.Free;
  End;
end;

 

Events

OnWebPushSubscription

This event is fired when a client subscribes to WebPush notifications. The event handler can be used to store the subscription details on the server-side.

 

OnWebPushUnsubscription

 

This event is fired when a client unsubscribes from WebPush notifications. The event handler can be used to remove the subscription details from the server-side.

 

OnWebPushSendNotificationException

 

This event is fired when an exception occurs while sending a WebPush notification using the BroadcastNotification method. The event handler can be used to handle the exception and remove the subscription details if required.