Broadcast Notifications #

Pragma supports sending notifications to logged-in players using operator and service endpoints. For example, you can alert all active players of upcoming maintenance, or notify player clients that the content catalog has been updated with new content and should be fetched.

The Player Session service has two endpoints that allow operators (notifyAllActiveSessionsOperatorV1) and services (notifyAllActiveSessionsServiceV1) to send custom notifications to all active player sessions. Custom notification structures are defined in proto messages, and configured via the PlayerSessionConfig.

Create a custom notification proto #

You define the custom notification structure in a proto file appropriate for the notification:

syntax = "proto3";

package zenith.custom;

import "pragmaOptions.proto";

option csharp_namespace = "Zenith.CustomNotifications";
option (pragma.unreal_namespace) = "CustomNotifications";

message MyCustomV1Notification {
    option (pragma.pragma_session_type) = PLAYER;
    option (pragma.pragma_message_type) = NOTIFICATION;

    string message = 1;
}

The notification will have a service created for it based on the message’s proto file. The service will be referenced when hooking up the notification on the client. In our example, we’re using a game called Zenith. The Unreal service generated will be called UZenithCustomNotificationsServiceRaw.

Broadcast a notification #

Using the protos, operators and services can send custom notifications. For example:

Example operator payload

{
    "requestId": 1,
    "type": "PlayerSessionRpc.NotifyAllActiveSessionsOperatorV1Request",
    "payload": {
        "notification": {
            "type": "MyCustomV1Notification",
            "payload": {
                "message": "Maintenance will start in one hour"
            }
        }
    }
}

Example service call

val notification = MyCustomV1Notification.newBuilder()
    .setMessage("servers are going to restart soon")
    .build()
val externalNotificationProto = ExternalNotification.newBuilder()
    .setType(JumpData.getIntForType(notification::class))
    .setPayload(notification.toByteString())
    .build()
val notifyAllRequest = NotifyAllActiveSessionsServiceV1Request.newBuilder()
    .setNotification(externalNotificationProto)
    .build()
service.requestRpcV2(notifyAllRequest, NotifyAllActiveSessionsServiceV1Response::parseFrom)

Configure notification settings #

Pragma Engine allows you to configure the number of notifications that are sent per gateway in each batch, as well as the time between each batch. This ensures that notifications are sent at appropriate intervals.

The following broadcast notification settings are available via the PlayerSessionConfig:

configdescription
notifyAllActiveSessionsBatchSizeNumber of notifications per gateway sent in a batch every notifyAllActiveSessionsBatchIntervalMillis
notifyAllActiveSessionsBatchIntervalMillisTime in milliseconds between sending each batch of notifications

For example:

game:
  serviceConfigs:
    GamePlayerSessionConfig:
      notifyAllActiveSessionsBatchSize: 500
      notifyAllActiveSessionsBatchIntervalMillis: 1000
social:
  serviceConfigs:
    SocialPlayerSessionConfig:
      notifyAllActiveSessionsBatchSize: 500
      notifyAllActiveSessionsBatchIntervalMillis: 1000

Handle notifications #

The AllActiveSessions notifications use the same notification logic as player-specific notifications, allowing a notification to be triggered by service-to-service or operator RPCs in addition to the normal means. The AllActiveSession notifications use the same notification logic as player-specific notifications.

The following is an example of how to subscribe to the MyCustomV1Notification message defined at the beginning of this topic.

void USomeSubsystem::Initialize(...)
{
    GetPragmaPlayer()->RegisterApi<UZenithCustomNotificationsServiceRaw>();

    UZenithCustomNotificationsServiceRaw& notifications =
        GetPragmaPlayer()->Api<UZenithCustomNotificationsServiceRaw>();

    notifications.OnMyCustomV1.AddUObject(
        this, &USomeSubsystem::HandleOnMyCustom);
}

void USomeSubsystem::HandleOnMyCustom(
    FPragma_CustomNotifications_MyCustomV1Notification Notification, 
    const FPragmaMessageMetadata& Metadata
    )
{
    //handle notification. For example:
    UE_LOG(LogTemp, Display, TEXT("Got My Custom Notification: %s"), *Notification.Message);
}

Dependent Jobs
Monitoring