sgcWebSockets · Technical Document

Web Push Server

TsgcWSAPIServer_WebPush — RFC 8030 Web Push server, VAPID-signed (RFC 8292) push to all major browser push services.

Overview

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.

At a glance

Component class
TsgcWSAPIServer_WebPush
Standards / spec
Web Push Protocol — RFC 8030
Transports
TCP, TLS
Platforms
Windows, macOS, Linux, iOS, Android
Frameworks
VCL, FireMonkey, Lazarus / FPC
Edition
Standard / Professional / Enterprise

Features

Technical specification

Standards & specsWeb Push Protocol — RFC 8030 · VAPID — RFC 8292
Component classTsgcWSAPIServer_WebPush (unit sgcWebSocket_Server_API_WebPush)
FrameworksVCL, FireMonkey, Lazarus / FPC
PlatformsWindows, macOS, Linux, iOS, Android

Main properties

The principal published / public properties used to configure and drive the component. Consult the online help for the full list.

ServerWebSocket/HTTP server this API component is attached to; its HTTP listener is used to serve the Web Push endpoints (subscription, service worker, VAPID public key).
WebPushOptions container for Web Push configuration: VAPID keys, client TLS/log settings and the built-in HTTP endpoints served by the component.
VersionRead-only string that returns the sgcWebSockets library version compiled into the component.

Main methods

The principal public methods exposed by the component.

SendNotification()Encrypts and POSTs a Web Push notification to a single subscription endpoint using the configured VAPID credentials.
BroadcastNotification()Sends the same notification to every subscription currently held in the internal Subscriptions list.
KeepAlive()Inherited helper that writes a keepalive/ping frame to a single WebSocket connection so idle links stay open through proxies.

Public events

The component exposes the following published events; consult the online help for full event-handler signatures.

OnWebPushSendNotificationExceptionTsgcWSAPIServer_WebPush › Events › OnWebPushSendNotificationException
OnWebPushSubscriptionFires when a browser POSTs to the Subscription endpoint after calling PushManager.subscribe(); receive the endpoint, p256dh key and auth secret to persist server-side.
OnWebPushUnsubscriptionTsgcWSAPIServer_WebPush › Events › OnWebPushUnsubscription

Quick Start

Drop the component on a form, configure the properties below and activate it. The snippet that follows shows the typical TsgcWebPush_Client configuration sourced from the online help.

About this scenario. The TsgcWebPush_Client is a class that allows you to send a notification once you obtain the subscription details.

Delphi (VCL / FireMonkey)

procedure SendWebPushNotification;
    var
      oSubscription: TsgcHTTP_API_WebPush_PushSubscription;
      oWebPush: TsgcWebPush_Client ;
    begin
      oSubscription := TsgcHTTP_API_WebPush_PushSubscription.Create;
      try
        oSubscription.Endpoint := 'endpoint';
       oSubscription.PublicKey := 'public key';
        oSubscription.AuthSecret := 'authentication secret';
        oWebPush := TsgcHTTP_API_WebPush_Client.Create(nil);
        try
          oWebPush.VAPID.PEM.PrivateKey.Text := 'private_key_pem';
          oWebPush.VAPID.DER.PrivateKey := 'private_key';
          oWebPush.VAPID.DER.PublicKey := 'public_key';
          oWebPush.SendNotification(oSubscription, '{"title": "eSeGeCe Notification", "body": "Hello from eSeGeCe!!!"}');
        finally
          oWebPush.Free;
        end;
      finally
        oSubscription.Free;
      end;
    end;

C++ Builder

void SendWebPushNotification()
    {
        TsgcHTTP_API_WebPush_PushSubscription* oSubscription = new TsgcHTTP_API_WebPush_PushSubscription();
        try
        {
            oSubscription->Endpoint = "endpoint";
            oSubscription->PublicKey = "public key";
            oSubscription->AuthSecret = "authentication secret";
            TsgcHTTP_API_WebPush_Client* oWebPush = new TsgcHTTP_API_WebPush_Client(NULL);
            try
            {
                oWebPush->VAPID->PEM->PrivateKey->Text = "private_key_pem";
                oWebPush->VAPID->DER->PrivateKey = "private_key";
                oWebPush->VAPID->DER->PublicKey = "public_key";
                oWebPush->SendNotification(oSubscription, "{\"title\": \"eSeGeCe Notification\", \"body\": \"Hello from eSeGeCe!!!\"}");
            }
            __finally
            {
                oWebPush->Free();
            }
        }
        __finally
        {
            oSubscription->Free();
        }
    }

.NET (C#)

public void SendWebPushNotification()
    {
        var oSubscription = new TsgcHTTP_API_WebPush_PushSubscription();
        oSubscription.Endpoint = "endpoint";
        oSubscription.PublicKey = "public key";
        oSubscription.AuthSecret = "authentication secret";
        var oWebPush = new TsgcWebPush_Client();
        oWebPush.VAPID.PEM.PrivateKey.Text = "private_key_pem";
        oWebPush.VAPID.DER.PrivateKey = "private_key";
        oWebPush.VAPID.DER.PublicKey = "public_key";
        oWebPush.SendNotification(oSubscription, "{\"title\": \"eSeGeCe Notification\", \"body\": \"Hello from eSeGeCe!!!\"}");
    }

Sources used to build this document

Every external claim links back to a primary source. The online-help references decode the canonical deep-link the company maintains for this component.

Document scope. This document covers the publicly-documented surface of the Web Push Server component shipped with sgcWebSockets. For full property, method and event reference consult the online help linked above.